Build custom Bootstrap documentation [closed]

Question

Closed. This question needs to be more focused. It is not currently accepting answers.

---

Want to improve this question? Update the question so it focuses on one problem only by editing this post.

Closed 5 years ago.

Improve this question

I have been working on a customized version of Twitter Bootstrap as a base for a new university website. We want to have public documentation for campus developers to be able to see all of the components Bootstrap provides, so serving the documentation via Jekyll is not a feasible option. We also want to be able to build the documentation using our customizations.

I have been looking around online, and I can't find anyone who has built static documentation for 3.x. Has anyone done this, or is the only way going to be simply parsing the HTML files and re-creating them in the appropriate format?

Answer 1

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.

Answer 2

I think you are skimming over Jekyll a bit too quickly. I can see a moderately painless way to make this happen.

1. Create a GitHub repo for your version of Bootstrap.

2. Create a gh-pages branch.

3. View the working docs - which should have your customized styles - at GHACCOUNT.github.io/REPONAME/docs

gh-pages is actually how Bootstrap serves their online documentation. They just laid a custom domain on top of it.

Note that you will have to update the docs with any components you may have created that are not out-of-the-box Bootstrap, but that is just a matter of updating the docs folder, merging the changes in to the gh-pages branch, and pushing up to GH.

Answer 3

I made a small "Theme elements" demo page for my Jekyll Bootstrap theme, you can see it here http://hmfaysal.github.io/hmfaysal-omega-theme/theme-setup/theme-elements/

The theme documentation is here: http://hmfaysal.github.io/hmfaysal-omega-theme/documentation/

Its a work in progress. So expect some typos and missed elements. Like I havent demostrated most of the bootstrap elements as I expect everyone to know them already :)

Let me know if you need anything