I'm planning to build a stack for internal company domain knowledge, and I've been thinking about middleman (http://middlemanapp.com) instead of Jekyll.
Middleman has impressive workflows and markdown processing (I'm guessing parallel to that of the Github/Jekyll solution or better).
Also conrefs can be implemented by simple partials (which makes less contention for the probably huge conref file)
Though I have to be convinced by trying the Github/Jekyll stack, this does open my mind regarding Jekyll 2.0. I'm happy to see Github tell us their Jekyll story :)
I think the main take-away with this post is that static sites for docs are awesome. GitHub uses [nanoc](http://nanoc.ws/) for the [API documentation](https://developer.github.com/).
The only downside of hosting static text on GitHub Pages without Jekyll is that you have to push the generated HTML too.
which makes less contention for the probably huge conref file
We're planning on splitting up the conref files by section. So for example, we'd get a separate conref file for Pages, one for UI stuff, one for Enterprise, etc. My only compliant with partials is that it's one piece of content per file, but it's a trade-off vs one file with several conrefs (gotta CTRL-F for that text you want to change).
Ironcially, just earlier today my co-worker and I were also discussing plans to setup a domain knowledge service internally. He came across a tool called Raneto [1] which looks very promising, but we have not had time to play with it extensively yet. Perhaps it could be useful for your use-cases too.
Comments
I'm planning to build a stack for internal company domain knowledge, and I've been thinking about middleman (http://middlemanapp.com) instead of Jekyll.
Middleman has impressive workflows and markdown processing (I'm guessing parallel to that of the Github/Jekyll solution or better). Also conrefs can be implemented by simple partials (which makes less contention for the probably huge conref file)
Though I have to be convinced by trying the Github/Jekyll stack, this does open my mind regarding Jekyll 2.0. I'm happy to see Github tell us their Jekyll story :)
I think the main take-away with this post is that static sites for docs are awesome. GitHub uses [nanoc](http://nanoc.ws/) for the [API documentation](https://developer.github.com/).
The only downside of hosting static text on GitHub Pages without Jekyll is that you have to push the generated HTML too.
We're planning on splitting up the conref files by section. So for example, we'd get a separate conref file for Pages, one for UI stuff, one for Enterprise, etc. My only compliant with partials is that it's one piece of content per file, but it's a trade-off vs one file with several conrefs (gotta CTRL-F for that text you want to change).
Ironcially, just earlier today my co-worker and I were also discussing plans to setup a domain knowledge service internally. He came across a tool called Raneto [1] which looks very promising, but we have not had time to play with it extensively yet. Perhaps it could be useful for your use-cases too.
[1] http://raneto.com/
you probably mean https://middlemanapp.com/
Much thanks, fixed :)
Middleman has almost no automated testing suite. Important to note if you are going to invest in something.