MkDocs

[loleg]

I've added some thoughts about the process to the wiki here and plan to install https://github.com/mkdocs into this repo. Why MkDocs and not..

• Pelican, like ogd-handbook-site
• Gridsome, like our blog
• ReadTheDocs or GitBook

The question is really, why not? MkDocs is open source, fully self hostable and Python based, seems to be actively supported and has a lot of well maintained plugins. I haven't used it yet in a project, and am keen to try to set up something usable. We won't lose any of the content anyway, as having the (Markdown) content in this repo is a pre-requisite. Other questions that needs to be answered in this test:

• Is it searchable? Multilingual? Support annotations or other cool doc features?
• Does it have good theme support? Could we easily make it fit our CI/UX?
• Can it be simply built and hosted (e.g. at Vercel or GitHub Pages/Actions)?
• Can it also easily include source code-level documentation?

[loleg]

@bkarolina @n0rdlicht I've added an initial fully working project structure along with a couple of further thoughts in this issue.

[n0rdlicht]

Thanks @loleg. I converted it into a discussion thread to talk about the criteria.

[n0rdlicht]

Regarding hosting: Let's give vercel another round here.

[n0rdlicht]

Another option we could consider: VuePress

Pros:

• supports multilanguage
• built in search, integrations with Algolia search if needed
• statically publishes .md files based on a .vuepress/config.js as html/css/js assets
• easily themable, nice built in theme with color and logo configuration options

Cons:

• no built in way to generate documentation from source-code documentation automatically

[n0rdlicht]

Deployment is now setup via GitHub Actions to deploy on pushes / merges to main, linked to handbook.cividi.space.

[loleg]

Woohoo! The pencil icon link doesn't work yet though..