squidfunk / mkdocs-material

Documentation that simply works

Home Page:https://squidfunk.github.io/mkdocs-material/

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

Pre-processing markdown content for later processing usage (ie. generating ePub versions)

BjoernSchotte opened this issue · comments

Contribution guidelines

I want to suggest an idea and checked that ...

  • ... to my best knowledge, my idea wouldn't break something for other users
  • ... the documentation does not mention anything about my idea
  • ... there are no open or closed issues that are related to my idea

Description

Thanks for mkdocs Material! In my POV, mkdocs Material is more than publishing static HTML with bells & whistles (header/footer/nav) around it.

There are a lot of "inline" features, i.e. emoji syntax or !!! info block syntax inside Markdown.

This comes at a cost: Currently, when using those features it's not possible to transform the Markdown into other formats i.e. ePub (through pandoc). You may argue that for some features like tooltips etc. this doesn't make sense. While I agree to this there are features like emoji syntax where it would make sense to use it when producing ePub versions of the content.

So I thought about how to achieve some ePub functionality. I read in the documentation about overriding some of the theme's blocks like header / footer / navigation.

So my question is: Would this be the right way to go? Or would it be better to feature suggest (hence this issue here) some kind of pre-processing step of the content and make it configurable per cli so that in a CI/CD pipeline one could specify to pre-process only the content without the surrounding HTML stuff? For example, conferting :emoji: syntax into markdown image references.

Use Cases

Processing the content into different formats without forgoing some of the mkdocs-material features like emoji etc.

Screenshots / Mockups

No response

Thanks for suggesting! Publishing other formats than HTML is really beyond the scope of this project. We jump through some hoops to make browser print mode work to a reasonable degree, but everything that is essentially transforming Markdown into something else than HTML is not a concern for Material for MkDocs. It's also nothing specifically tied to the theme, thus an excellent opportunity for leveraging the plugin system of MkDocs 😊 Closing as out of scope.

Hm, not sure if you got me wrong: I would happily welcome transforming the .md to .html BUT without the surrounding things like navigation, header etc. (my guess is that I could use the base HTML for transforming it to ePub then)

So the question is: is it possible to use the override mode in a more configurable way when invoking mkdocs?

I'm not sure what you mean by "more configurable way". Care to elaborate? In general, you can extend the theme and adjust the partials to fit your taste. This is a core design philosophy of Material for MkDocs – always allowing easy customization. You could also provide a completely different template and only include the content partial if you only want the bare bone content without navigation.

I would love to invoke mkdocs two times inside my build process (one for creating the beautiful full HTML site which will be published to i.e. gh-pages; the other one for creating the barebone HTML files for processing them further).

As far as I've understood https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme the configuration for extending the theme is baked into mkdocs.yml

As I try to DRY currently I have to use 2 mkdocs.yml configuration files (one without extension, the other one with extending the theme and using overrides) - but I just wanted to avoid using two duplicates.

You can set a custom overrides directory via environment variable. We're doing this in our repository to allow building the documentation with Insiders.

custom_dir: !ENV [THEME_DIR, "material"]

If you need to switch other configuration flags on/off, there's no way around a second mkdocs.yml, which I understand is a very minor inconvenience. You can even use configuration inheritance to share most of your config.

Ah wow! Thanks for the fast reply!