How to use snippets to show code?

[ssbarnea]

I do have some code blocks (triple backtick) for which I do want to load the content from an external file, so snippets was the most likely candidate.

Still, when I inserted the snippet as the body of the code block it did render as plain text instead of including the external code.

What is the solution for showing code from external files with mkdocs?

--8<-- "test/example.py"

[facelessuser]

Please provide a minimal reproducible example. I'm not sure how you've configured anything, how the files are relative to each other.

[facelessuser]

As there has been no response back, I'll give my official statement. You must configure Snippets with a base path. Python Markdown has no concept of file location as it only deals with a text buffer. The file information, assuming there even is one associated with the buffer, is not tracked in Python Markdown. For this reason, a base path is needed. If you give it one or more base paths, the specified snippet path will be compared relatively against each base path until it finds the file. All of this is covered in the documentation: https://facelessuser.github.io/pymdown-extensions/extensions/snippets/.

If you have a specific question about something in the documentation, please feel free to ask more specific questions, particularly with examples of what you are doing.

[ssbarnea]

Let's imagine the use case of someone trying to build a single website formed of multiple projects, structured like

/mkdocs.yml                  # parent site definition
/docs                        # documentation for master site
/projects/foo/mkdocs.yml     # child project
/projects/foo/docs/some.md

foo is also a standalone mkdocs project, so it can build from its root.

Still, when someone builds the parent site (while using one of the exist plugins to enable this), that will always use another mkdocs.yml file which will never be near the child one. In our case that would be two levels up.

That means that any path used by snippets (or other similar plugin) will be broken too.

I am aware that this is not effectively bug unique to snippets, but the question is what can we do to allow people to build compose sites / portals? Do we need some special changes in mkdocs itself to allow that?

Maybe the plugin as https://github.com/backstage/mkdocs-monorepo-plugin#usage could also configure a custom base_path for each included page? I am not sure if that is even possible, but clearly we need a way to set the "context" in which this code runs or all these plugins will not be able to find the files. Still the lookup paths needs to different based on where the files come from or the rendering will not work.

Note that I a still new to mkdocs and I never wrote a plugin for, so I do not know its internals.

A very simple practical example can be seen at https://github.com/ansible/devtools/blob/main/mkdocs.yml#L49 where I have one subproject under projects. MkDocs renders this one well but only because I do not have any use of snippets inside it. If would have, it would fail. The resulted documentation site is at https://ansible-devtools.readthedocs.io/ansible-language-server/development/

PS. I am still trying to get in contact with the authors of the two multi-site plugins so see what can be done as they should clearly know more about these challenges.

[facelessuser]

Unfortunately, I am not familiar with exactly how the multi repo plugin works, but it sounds like each repo has its own mkdocs.yml? If so, they each need to point to the base path. That base path can be relative to the CWD of the current project being generated if needed.

# Up one, two, or however many folders you need to and then redirect it to the snippet folder.
base_path: ../snippet/path

This answer is based on my limited understanding of how things will work in the plugin.