Coming back to this question after a couple years, I wanted to share the solution that worked best for our use case.
tl;dr: Jekyll works just fine. You just need to set it up for your particular use case
As mentioned by @SeanRyan , I was dismissing Jekyll too quickly. When I posted this, I had the impression that Jekyll was primarily a way to quickly serve a site locally rather than generate a static site that you can push almost anywhere. However, we did not have a public (or even private) GitHub organization or GitHub Enterprise server to which I could push a gh-pages
branch with our custom doc.
The best solution for our use case (which I unfortunately never quite finished) was to incorporate the Jekyll build into the rest of the build process. Instead of making a separate gh-pages
branch to push to a GitHub server somewhere, I had a style-guide
branch, which contained the files for the Jekyll site. I set up tasks in our Grunt build which would compile the documentation using the templates and assets from master
and automatically create a new commit in style-guide
. The idea was that, during the build process, we could automatically build our site and assets, generate the documentation and style guide, push the static site to its own branch, and deploy the compiled style guide to its own URL on our web server.
Obviously, if you are using GitHub or GitHub Enterprise, the process is even easier. See @SeanRyan's answer or GitHub's documentation for detailed instructions on setting up a Jekyll site on gh-pages
.
Since asking this question, I have learned quite a bit more about automated builds in general and Jekyll specifically, and I have set up builds very similar to what I describe above. For anyone finding this question, I wanted to come back and summarize what I think are the best solutions.