Rethink plugin config

[rstacruz]

Docpress is simply metalsmith with 2 plugins: docpress-core and docpress-base.

You can add plugins with the plugins configuration:

/* docpress.json */
"plugins": {
  "docpress-core": {},
  "docpress-base": {},
  "docpress-disqus": {}, /* hypothetical plugin */
  "docpress-edit-in-github": {} /* hypothetical plugin too */
}

This convention is not ideal. As a new user, my first instinct is just add docpress-disqus to the plugins list, but that's not the case. You need to repeat docpress-core and docpress-base in there.

My first instinct is to configure it this way because:

• You may need to use something other than docpress-base, it should be easy to remove it
• Some plugins may need to be before or after docpress-base (or -core), so it should be possible to do that

No idea what the best plugin API would be. Opening the discussion here on that.

(ps: @Kikobeats what's your npm email?)

[rstacruz]

Idea 1: use different plugin keys

Instead of just dumping plugins into plugins, we can add these config keys:

• transforms - plugin(s) that may augment docpress-core's functionality. There are no plugins for this at the moment.
• generator - plugin(s) responsible for turning plain .html's (from docpress-core) into a full site. docpress-base is currently the only plugin for this.
• addons - plugin(s) added after the generator. These would be plugins that "inject" things, like Analytics integration, Search, and so on.

That would make:

/* docpress.json */
"transforms": {
  "docpress-jsdoc": {}, /* hypothetical support for .js comments */
},
"generator": {
  "docpress-base": {},
}
"addons": {
  "docpress-search": {},
  "docpress-disqus": {},
  "docpress-edit-in-github": {}
}

Pros:

• Users don't need to know about docpress-core and docpress-base.

Cons:

• Too much config keys...?

Pending questions:

• How would we handle a hypothetical PDF/ePub generator?

[Kikobeats]

Instead of:

"addons": {
  "docpress-search": {},
  "docpress-disqus": {},
  "docpress-edit-in-github": {}
}

maybe a better markup could be an array and just providing specific options when is necessary:

"addons": [
    "docpress-search",
    { "docpress-disqus": { shortname: 'my-shortname' }},
    "docpress-edit-in-github"
]

I have a similar plugin pipeline at bumped and I decide use CSON. Also is possible provide a JSON file but with CSON it lloks more legible:

'addons': [
  'docpress-search'
  { 'docpress-disqus': shortname: 'my-shortname' }
  'docpress-edit-in-github'
]

[rstacruz]

that can work. I chose the object notation because that's the convention metalsmith uses (example). In the spirit of keeping up with the Metalsmith community, I'd like to continue support for it. (We can support both object notation and array notation.)

For the array syntax, I think it's better for options to be passed through array tuples, like so:

"addons": [
    "docpress-search",
    [ "docpress-disqus", { shortname: 'my-shortname' } ],
    "docpress-edit-in-github"
]

This is browserify's convention, and I think it's sensible because it even allows you to specify multiple options to pass if need be.

[rstacruz]

I added you to the docpress org by the way. Thanks for all your help!

[Kikobeats]

I like browserify convention; I understand your support to metalsmith convention but maybe for this case don't have much sense pass a empty object the major part of time.

[rstacruz]

I think the argument for the Metalsmith convention is that it's easier to parse (not just by MS but by other things as well), and the shape is uniform without any "smart" rules involved.

The array convention is also used by Babel, which typically turns into a mess when auto-formatted:

  "babel": {
    "presets": [
      "es2015",
      "es2017"
    ],
    "plugins": [
      "syntax-jsx",
      [
        "transform-react-jsx",
        {
          "pragma": "element"
        }
      ]
    ]
  },

Nonetheless I'm cool with both; they're both widely-used conventions (metalsmith/postcss on the object notation, browserify/babel on the array convention).

[rstacruz]

what do you all think about the transforms/generator/addons config keys tho?

[rstacruz]

Btw, in the future generators can add more generators like so:

{
  "generators": [
    "docpress-base", /* html website */
    ["docpress-epub": { filename: "myapp.epub" } ],
    ["docpress-pdf": { filename: "myapp.pdf" } ]
  }
}

[rstacruz]

(And I just realized docpress-base is better named as docpress-html.)

[knownasilya]

I like the rename to docpress-html.

Where would themes go? generators or addons?

[rstacruz]

Haha. addons I guess? At least for themes that will keep the same HTML structure, which I assume most will wanna do (generating HTML is hard!)

I'd add another theme key but just might be an extra config key for no reason.

It'd be in generators if it's a theme that generates its own HTML.

[knownasilya]

Might be a pain to try and override the existing css in docpress-html, should that be pulled out as a theme that's included by default? Just thinking out loud.

[rstacruz]

Hm, probably not. Here's how I'd approach a totally custom theme:

• Make my theme completely replace the stylesheet (files['assets/style.css'].contents = '...')
• Build my stylesheet from scratch using Stylus
• Make that Stylus @import 'docpress-html/data/style.styl' so I can extend from the default theme

Of course I'd also refactor docpress-html to have its stylus a bit more easily-extensible (separate it into multiple .styl files so people can cherry-pick what they wanna use)

[knownasilya]

Ah, sounds good. We'd need to document some of this once it has been implemented.

[rstacruz]

Yeah, and I'll make https://github.com/rstacruz/docpress-rsc to be an official theme (docpress/docpress-white or something), and build it using that convention.