shanduur
commented
4 months ago Bootstrapping
-
Docsy
hugo new site . hugo mod init github.com/registry-operator/docs hugo mod get github.com/google/docsy@v0.9.1 echo '[module]' >> hugo.toml echo ' proxy = "direct"' >> hugo.toml echo ' [module.hugoVersion]' >> hugo.toml echo ' extended = true' >> hugo.toml echo ' min = "0.73.0"' >> hugo.toml echo ' [[module.imports]]' >> hugo.toml echo ' path = "github.com/google/docsy"' >> hugo.toml echo ' disable = false' >> hugo.tomlThis produces the following file structure:
registry-operator.docsy ├── archetypes │ └── default.md ├── assets ├── content ├── data ├── go.mod ├── go.sum ├── hugo.toml ├── i18n ├── layouts ├── public │ ├── 404.html │ ├── categories │ │ ├── index.html │ │ └── index.xml │ ├── css │ │ └── prism.css │ ├── favicons │ │ ├── android-144x144.png │ │ ├── android-192x192.png │ │ ├── android-36x36.png │ │ ├── android-48x48.png │ │ ├── android-72x72.png │ │ ├── android-96x96.png │ │ ├── apple-touch-icon-180x180.png │ │ ├── favicon-1024.png │ │ ├── favicon-16x16.png │ │ ├── favicon-256.png │ │ ├── favicon-32x32.png │ │ ├── favicon.ico │ │ ├── pwa-192x192.png │ │ ├── pwa-512x512.png │ │ ├── tile150x150.png │ │ ├── tile310x150.png │ │ ├── tile310x310.png │ │ └── tile70x70.png │ ├── index.html │ ├── index.xml │ ├── js │ │ ├── click-to-copy.js │ │ ├── deflate.js │ │ ├── main.js │ │ ├── prism.js │ │ └── tabpane-persist.js │ ├── scss │ │ ├── main.css │ │ └── main.css.map │ ├── sitemap.xml │ ├── tags │ │ ├── index.html │ │ └── index.xml │ └── webfonts │ ├── fa-brands-400.ttf │ ├── fa-brands-400.woff2 │ ├── fa-regular-400.ttf │ ├── fa-regular-400.woff2 │ ├── fa-solid-900.ttf │ ├── fa-solid-900.woff2 │ ├── fa-v4compatibility.ttf │ └── fa-v4compatibility.woff2 ├── resources │ └── _gen │ └── assets │ └── scss │ ├── main.scss_3f90599f3717b4a4920df16fdcadce3d.content │ └── main.scss_3f90599f3717b4a4920df16fdcadce3d.json ├── static └── themesWhich looks like this:
-
Docusaurus
npx create-docusaurus@latest registry-operator classicThis produces the following file structure:
registry-operator.mkdocs ├── docs │ └── index.md ├── mkdocs.yml └── venv └── ...Which looks like this:
-
Doks
npm create hyas@latest -- --template doks npm installThis produces the following file structure:
registry-operator.doks ├── LICENSE ├── assets │ ├── cover.png │ ├── favicon.ico │ ├── favicon.png │ ├── favicon.svg │ ├── images │ ├── js │ │ └── custom.js │ ├── mask-icon.svg │ ├── scss │ │ └── common │ │ ├── _custom.scss │ │ └── _variables-custom.scss │ └── svgs ├── config │ ├── _default │ │ ├── hugo.toml │ │ ├── languages.toml │ │ ├── markup.toml │ │ ├── menus │ │ │ ├── menus.en.toml │ │ │ └── menus.nl.toml │ │ ├── module.toml │ │ └── params.toml │ ├── babel.config.js │ ├── next │ │ └── hugo.toml │ ├── postcss.config.js │ └── production │ └── hugo.toml ├── content │ ├── _index.md │ ├── blog │ │ ├── _index.md │ │ └── example │ │ └── index.md │ ├── docs │ │ ├── _index.md │ │ ├── guides │ │ │ ├── _index.md │ │ │ └── example.md │ │ └── reference │ │ ├── _index.md │ │ └── example.md │ └── privacy.md ├── layouts │ ├── index.html │ └── partials │ ├── footer │ │ └── script-footer-custom.html │ └── head │ ├── custom-head.html │ └── script-header.html ├── netlify.toml ├── node_modules │ └── ... ├── package.json └── staticWhich looks like this:
-
Material for MKDocs
python3 -m venv venv && source ./venv/bin/activate pip install mkdocs-material mkdocs new . echo 'theme:' >> mkdocs.yml echo ' name: material' >> mkdocs.ymlThis produces the following file structure:
registry-operator.mkdocs ├── docs │ └── index.md ├── mkdocs.yml └── venv └── ...Which looks like this:
-
Zola
zola initThis produces the following file structure:
registry-operator.zola ├── config.toml ├── content ├── sass ├── static ├── templates └── themesWhich looks like this:
-
Cobalt
cobalt initThis produces the following file structure:
registry-operator.cobalt ├── _cobalt.yml ├── _defaults │ ├── pages.md │ └── posts.md ├── _layouts │ └── default.liquid ├── index.md └── posts └── post-1.mdWhich looks like this:
Versioning
- Docsy: built-in support (see docs);
- Docusaurus: built-in support (see docs);
- Doks: built-in support, but it is not particularly well documented (see docs);
- Material for MKDocs: supported via Mike plugin;
- Zola: No info;
- Cobalt: No info;
Examples
- Docsy:
- Docusaurus:
- Doks:
- Material for MKDocs:
- Zola:
- Cobalt:
niesmaczne
Context and Problem Statement
Effective documentation is paramount for the successful adoption and utilisation of the
registry-operator, a robust tool tailored for managing CNCF Distribution Registry instances. As developers and DevOps teams engage with theregistry-operator, they require comprehensive, easily accessible documentation to streamline deployment, scaling, and management tasks.The choice of documentation framework or static site generator is crucial to ensure that the documentation meets the needs of our users. Templating flexibility, support for custom scripts, and availability of extra plugins for enhancing functionality are key factors to consider in this decision-making process.
Considered Options
MKDocs + Material Theme for MKDocs
Hugo + Docsy Theme
Hugo + Doks Theme
Docusaurus
Cobalt
Zola