Adding a snippet to mkdocs

[audgirka]

Hi,

I would like to add a snippet (or maybe a template) to a custom mkdocs theme and use the same in different projects that use this theme.
Any suggestions or ideas if this would even be possible?

If yes, would love to have some pointers.

Thanks

[kamilkrzyskow]

Hello @audgirka,
if you're asking about how to make your own theme, then better to ask in MkDocs' discussion board or check out their theme development guide.

But let's say you want to extend this theme. There are 2 possible options given your query:

1. Snippets: https://squidfunk.github.io/mkdocs-material/setup/extensions/python-markdown-extensions/#snippets
   They allow you to include other files in the content of the page, you can share information across pages, or define different pages
   with the same content. The looks of the site, structure of HTML will remain the same as if you'd write inside them directly. Example discussion found with search:
   Including same .md file in "nav" structure on different places results bad behaviour mkdocs/mkdocs#3596

2. Custom templates: https://squidfunk.github.io/mkdocs-material/reference/#setting-the-page-template
   https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme
   They allow you to define the structure of the HTML that will be used to render everything around the content.
   You can make a page with smaller adjustments like a blog post - blog-post.html (by extending main.html).
   You can also make a home page that completely replaces the content like https://squidfunk.github.io/mkdocs-material/ (though the parallax source code is available to Insiders only, and you can access only the community template without it) or https://www.privacyguides.org/en/

[alexvoss]

You can have a custom_dir that is located in a parent directory if you want to use a custom template in different projects. If each project needs its own specific custom templates as well then it would become a bit more involved. If you can use symbolic links that would be a way to solve the problem.

It should also be possible to build a custom theme that can be installed with pip but that is not something I would know how to do other than to create and maintain a fork. Certainly possible for internal use but a bit of a heavy-weight approach so you'd need to be pretty sure it is worth it.

[ssbarnea]

I am afraid that this is about adding a static piece of code inside the theme repository and aiming to use it later inside markdown files from projects that rely on this theme.

The key aspect here is that the definition should not be inside the project, it must be in the theme.

[kamilkrzyskow]

So as far as I know there is no solution for you without some major customizing.

An MkDocs theme is mainly a group of Jinja2 template files that are loaded and processed to return the HTML output. The theme's author can also add CSS and JavaScript to style it and make it more interactive after the build was complete.

But you can't reference templating data inside Markdown, so that's not the solution.

So we need to look further. An MkDocs theme is also a Python package that can contain its own coding solutions. The Material theme replaces the Search plugin for example, so it's a different search from the default MkDocs uses.

Going even further you can add your own Markdown Extensions to the theme. The Snippets extension that loads snippets, loads them based from the current working directory, so the location where you run mkdocs build.
However, you could provide your own extension that loads the data from internal theme directory.

So I guess this would be the route to take, custom theme with custom markdown extension (which needs to be activated in the project file) that allows to inject Snippets into the project's Markdown files from the theme's directory.

[alexvoss]

One thing that I have done recently is to start writing a plugin that replaces YAML code in code blocks with rendered versions. For this I am using the custom fences extension mechanism available in the superfences markdown extension. I parse the YAML and return an HTML fragment rendered using Jinja2. The code looks a bit like this:

from jinja2 import Environment, BaseLoader, TemplateError
from mkdocs.exceptions import PluginError

_environment = Environment(loader=BaseLoader())
template = _environment.from_string("""
  <div>your HTML and Jinja code here</div>
""")

def format(data):
    try:
        html = _caring_template.render(
             # pass in any data you need here
        )
    except TemplateError as err:
        raise PluginError("Error rendering template") from err
    return html

Also wrote some code for the plugin to add the format function to the configuration so the user does not have to do this. If this looks like it might solve your problem let me know. The intention is for this plugin to be released under MIT, so I am happy to show you more before the project itself sees the light of day. I am also available to help build a solution if you need an extra hand. Feel free to drop me a line.

[ssbarnea]

On fralau/mkdocs-macros-plugin#218 (comment) I seen that the pluglets may be another approach for achieving this.