New Mkdocs-catalog documentation

[fralfaro]

Hello, I migrated the code at https://fralfaro.github.io/catalog/. Documentation was mainly done with mkdocs (+ mkdocs plugins).

However, I need to automate the process with the projects.yaml file.

I am very happy to hear suggestions and continue contributing.

[pawamoy]

Thanks for offering your help :slightly_smiling_face:

Just to be clear: do you intend to send a PR again, or are you just looking for help automating your docs at https://fralfaro.github.io/catalog/?

We actually do not plan to deploy the catalog as an MkDocs subsite at ww.mkdocs.org/catalog. I myself would like to start by only integrating a gallery of themes directly within the docs and not as a subsite. But this can be discussed of course. Happy to also get feedback from you @tomchristie.

If you want to send a PR again @fralfaro, your documentation will have to use the theme used by the official docs, which currently is mkdocs. But also know that there's work in progress to create a new default theme, or to improve the current one. IMO we're not clear yet on whether we want to integrate the full catalog in the official docs.

We would also have to discuss about the neoteroi extensions you're using, to make sure they work well with the default theme. By the way they seem to require that we add quite a lot of CSS to the assets: isn't there a way to make these plugins include the assets dynamically and transparently, so we don't have to track them in Git?

Regarding automation: I would myself probably write hooks that read projects.yaml, and generate dynamic files and their contents with mkdocs-gen-files, maybe building the navigation in combination with mkdocs-literate-nav.

[pawamoy]

Closing for now, feel free to comment further, and I'll reopen :slightly_smiling_face: