resource page and content management

[lionpeloux]

Hello,

I am using mkdocs-material to build a kind of research wiki on the physics of buildings. So far everything goes well thanks to your incredible work.

Beyond the theme, I would like to build a custom resources section. My resources are books, web pages, institutional contacts, YouTube videos, pdf papers or blog articles ...

So I am thinking of building a custom json database of all the references I want to manage (citekey, title, author, link to pdf or url, link to thumbnail img, date, description, resume, tags, ...). This might (or might not) be done through a standard citation manager. I think I will have about 100 curated resources to expose to the readers.

The json file is here to separate the data and the view in mkdocs.

Then, I want to preprocess the json file to output custom lists of resources in some pages/sections.

Ultimately, I would like to be able, through a unique citationkey mechanism, to reference the resources through an anchor link.

Question Is

• What would be the best way to proceed ?
• Can it be done directly through theme extension with partials.
• Do I need to preprocess my json file (python ?) to build the resource lists as html files before building with mkdocs ?
• How/When to implement a hook in the process to replace citationkeys to html anchors ?

Thanks in advance for your insights !

[squidfunk]

I can't say what the best way is, but MkDocs 1.4+ offers a simple functionality called hooks to add custom logic to the build process. You can then use theme extension, add custom templates or override partials as described in our documentation to fit everything to your taste. One idea might be to use a hook to generate Markdown files from the JSON, which MkDocs will then convert into HTML, but YMMV. Maybe somebody else who has done some customization can share her/his process.

[kcgthb]

I would also recommend taking a look at https://mkdocs-macros-plugin.readthedocs.io/ for this. We successfully use it to build "dynamic" pages based on the content of YAML files.