Monorepo documentation
As part of my mono-repo project, I was looking for a solution to my documentation system. Although I don't fully know what I want to write, but I wanted to find something like g3doc, an internal documentation system at Google, a Markdown-based, doc-as-code solution that accompany many Google projects.
Context
Previously, I have tried Jekyll and Hugo. Between them, Hugo was a promising choice to me. At one point, I wanted to use Hugo as an entry point to learn the Go programming language. That didn't happen, but my github page and one of my podcast page was made with Hugo.
Alternatively, Citadel has recently started to adopt mkdocs, especially Material for Mkdocs, as an internal documentation solution, in addition to, or in hope of replacing, the existing many different documentation solutions, among which Confluence Wiki was the main one.
There are many problems with the Wiki as the documentation solution. It is a problem not only in Citadel, but also in Google. Wiki are not easy to maintain, or to discover, if you don't have tools built for enriching the Wiki system. It is also not easy to extend, although many wiki frameworks are trying very hard to ship different plugins.
The biggest problem, in my mind, is that the documentation in Wiki stays far away, and independently from, the software projects; at the same time, the most needed documentations are closely related to specific software projects. Maintaining the documentation and maintaining the software project becomes two independent projects; extra efforts are required to connect them together and keep them in sync. In most cases, people end up with spending all resources to grow the software projects and no effort is made to improve the documentation. When the documentation is out of sync, some people would start to say "the outdated doc is worse than no doc", and instead of spending effort on improving the documentation, they choose stop documenting entirely.
My Search
To facilitate my own documentation, I need a documentation system that can span across the entire monorepo, and at the same time can maintain relative independent from the other. My brief research indicates that Hugo has a module system, and mkdocs has the mkdocs-monorepo-plugin. Reading the documentation for each solution, I feel the mkdocs with the monorepo plugin is closer to what I need. After all, the plugin was made by Spotify to build their own documentation system in their monorepo, exactly the same as what I want to achieve.
So here we are, onboarding the mkdocs in my own monorepo.
Mkdocs
I have installed the following plugins for my mkdocs
| python package | version | description |
|---|---|---|
| mkdocs | 1.4.3 | base package |
| mkdocs-material | 9.1.16 | main theme. It's documentation is great |
| mkdocs-material-extensions | 1.1.1 | additional extensions for mkdocs |
| mkdocs-monorepo-plugin | 1.0.5 | support the entire monorepo. Still experimenting |
| mkdocs-terminal | 4.4.0 | an alternative theme |
| mkdocs-git-revision-date-localized-plugin | 1.2.0 | added for mkdocs-material's git support |
| neoteroi-mkdocs | 1.0.2 | additional renderings |
| mkdocs-badges | 0.4.0 | some badge like rendering |
| mkdocs-conditional-include | 0.0.1 | not sure I need it yet. |
| 2.9.1 | an easier way to group pages under navigation. However, it doesn't work well with monorepo plugin. |