Roadmap about docpress

[rstacruz]

Theming roadmap (v0.8)

1. docpress-base will be renamed to docpress-html. (#143) This is a Metalsmith plugin responsible for building basic the HTML structure.

2. docpress-html will be made to only generate HTML... no CSS or JavaScript. This will greatly simplify docpress-html, which is very overloaded right now.

3. The CSS/JS parts will be extracted to docpress-theme-base. This allows us to manage the complexity build tools (stylus, postcss, browserify) in just one module.

   Docpress will now use a pipeline of:

   • docpress-core (parses .md files) →
   • docpress-html (generates .html) →
   • docpress-theme-base (adds .css and .js).

Future themes will replace docpress-theme-base in that pipeline. There will be tools in docpress-theme-base to allow you to build themes on top of it easily (ie, reuse the same stylus/browserify pipeline to build your own themes).

[knownasilya]

Might be nice to have a docpress init command that sets up a docpress.json with some nice defaults, docs folder, and gh-pages deploy setup? Maybe post 1.0 though.

Also docpress -h doesn't work, it should.

[rstacruz]

...you can even build that as a docpress-init module, which docpress will just delegate to later.

[rstacruz]

Oh, thats not a bad idea. It's actually pretty easy. If you guys wanna take a stab at it, go ahead.

npm install --save-dev docpress
mkdir -p docs
cat << EOF
# Table of Contents

* [Project name here](../README.md)
EOF > docs/README.md
echo '{ "github": "github/url" }' > docs/docpress.json
# add { scripts: { docs: "docpress build" } } to package.json
# add { scripts: { "docs:watch": "docpress" } } to package.json

gh-pages integration is harder though (it has some manual steps), so I'd hold off on that.

[knownasilya]

I'd love if we could switch stylus --> postcss and pug --> to something html like (handlebars?). Makes contributing so much simpler, and understanding the code for building themes.

[rstacruz]

stylus to postcss-cssnext + postcss-easy-import? yes, that's certainly possible. the lack of var ?= value would be a shame (it's a way to make variables easily overridable), but I think we'll survive.

pug to something else? that'd be hard. the menu generation relies on pug's recursive mixins, something not easily doable in handlebars. mustache, maybe.

[knownasilya]

Maybe swig, not really set on a specific preprocessor, but it should be something that keeps the html in it's normal state.

[knownasilya]

We should probably also lock into Node 6.9-lts for v1.0