Skip to content

About💣

How it works💣

  1. Add bigbang as a Git submodule.
  2. Use bigbang/chart/values.yaml to pull in all the packages as submodules.
  3. Use Git to list all of bigbang‘s tagged versions.
  4. Checkout that release of bigbang.
  5. Use bigbang/chart/values.yaml as the source of truth for each package’s version for that release.
  6. Copy each packages’ docs over using declarative config from base/packages/<package>/config.yaml.
  7. Copy Big Bang’s docs over, using base/config.yaml.
  8. Reformat Helm docs contained in the READMEs. Creates a separate values.md file that is accessible via site search.
  9. Add certain tags to YAML frontmatter to aid in easier site search. Also patch in revision date back into page footer.
  10. Build that version of the docs.
  11. Repeat steps 4-9 for each version specified.

Demo GIF💣

Demo GIF

Comparisons to other tools💣

In my pursuit to write this, I did look at alternative build tools to MkDocs. The below contain a subjective comparison betweeen MkDocs and other static site generators.

Note

It is worth noting that whichever tool I went with, I would also build the pre, and post build steps in whichever language the tool was written in. This would ensure maximum interop across the build process.

Gatsby💣

“Gatsby is the fast and flexible framework that makes building websites with any CMS, API, or database fun again. Build and deploy headless websites that drive more traffic, convert better, and earn more revenue!”1

Pros:

  • Very mature plugin ecosystem
  • React based, so very easy to extend (for me)
  • Widely used as a docs static site generator

Cons:

  • Personally, I have had some bad experiences with Gatsby and their design decisions / DX
  • Too verbose / complex for simple sites

Verdict: A large inspiration to this project was Cloudflare’s Developer Docs, which (formerly) used Gatsby in its docs-engine. However, my past experiences with Gatsby, and the complexity that would be required to build a simple docs site, led me to look elsewhere.

Hugo💣

“Hugo is one of the most popular open-source static site generators. With its amazing speed and flexibility, Hugo makes building websites fun again.”2

Pros:

  • Fast (written in Go)
  • Container already approved and in Iron Bank
  • Powerful and versatile templating system

Cons:

  • No good documentation themes (imo)
  • Confusing naming conventions
  • API has changed rapidly within last few months
  • Go has a higher barrier to entry vs Python or JavaScript

Verdict: While Hugo is insanely powerful, I don’t think it fits this use case. I did not relish the idea of building my own docs site using Go templates, and would rather use a batteries included theme like Material, and tweak it to my liking.

MkDocs💣

“MkDocs is a fast, simple and downright gorgeous static site generator that’s geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML configuration file.”3

Pros:

  • Written in Python (essentially no learning curve)
  • Simple (single YAML file configuration)
  • Material for Mkdocs theme is insanely good

Cons:

  • Python is slower than Go/NodeJS so build times are longer
  • Less configurable than building a site from scratch using Hugo/Gatsby

  1. https://www.gatsbyjs.org/ ↩

  2. https://gohugo.io/ ↩

  3. https://www.mkdocs.org/ ↩