0

Just discovered mkdocs and really like it. I am currently porting online done in a proprietary tool into it.

The only stumbling block I've had is implementing auto-appending snippets.

I was able to implement abbreviations as described here:

https://squidfunk.github.io/mkdocs-material/reference/abbreviations/

My next step was to add a glossary as described on that page by moving those abbreviations into a snippets file as described on the same page.

But rather than having to manually add the snippets to every Markdown file in my project, I wanted to use auto-append as described here:

https://facelessuser.github.io/pymdown-extensions/extensions/snippets/

My mkdocs.yml file declares its theme and extensions as follows:

theme:
    name: material 
markdown_extensions:
  - attr_list
  - abbr
  - pymdownx.snippets

But, I'm unclear on where I exactly configure "auto_append", "base_path" and the other options mentioned in that latter document. If anyone has a working example I'd appreciate it.

EDIT 18 Jan 2023: I can now get the auto_append working using the following configuration in mkdocs.yml:

theme:
    name: material 
markdown_extensions:
  - pymdownx.snippets:
      auto_append: ["abbreviations.md"]
      # base_path: ["."]  
      base_path: ["docs"]

...where my file structure is as follows:

[docs]
  abbreviations.md
  {other topics.md}
[includes]
[site]
mkdocs.yml

However, as soon as I add - attr_list and - abbr to mkdocs.yml, auto append stops working:

theme:
    name: material 
markdown_extensions:
  - attr_list
  - abbr
  - pymdownx.snippets
      auto_append: ["abbreviations.md"]
      # base_path: ["."]  # for root of repo
      base_path: ["docs"]
oceanclub
  • 477
  • 1
  • 4
  • 13

1 Answers1

1

The snippet options are provided where you specify the markdown_extensions in your mkdocs.yml file, e.g.

# mkdocs.yml
...

markdown_extensions:
  - pymdownx.snippets:
      auto_append: ["../LICENSE"]
      # base_path: ["."]  # for root of repo
      base_path: ["docs"]

Hopefully this helps!

hotenov
  • 911
  • 1
  • 11
  • 17
Jacob Lärfors
  • 81
  • 7
  • Hi Jacob, unfortunately that didn't work, or perhaps there's just more configuration I need to do. For example the docs say: "The Snippets extension can be included in Python Markdown by using the following: import markdown md = markdown.Markdown(extensions=['pymdownx.snippets'])" Which file do I put those two lines? – oceanclub Aug 31 '22 at 19:37
  • Hi! @oceanclub I'm not sure what you want as final result, but I corrected the answer by Jacob Lärfors and now in EVERY Markdown content the text of LICENSE file from "root" repo will be appended, including your index.md file (home page). If you don't use `docs` folder you can use `["."]` (root) as your base_path, then link will be ["LICENSE"] – hotenov Dec 07 '22 at 04:53
  • Thanks! The following works (with abbreviations.md file being in my 'docs' folder: markdown_extensions: - pymdownx.snippets: auto_append: ["abbreviations.md"] # base_path: ["."] # for root of repo base_path: ["docs"] That appends the abbreviations.md to each of my topics. However, with this: theme: name: material markdown_extensions: - attr_list - abbr - pymdownx.snippets: auto_append: ["abbreviations.md"] # base_path: ["."] # for root of repo base_path: ["docs"] ....the abbreviations.md file is no longer appended. – oceanclub Jan 15 '23 at 18:16
  • @oceanclub because you forgot column `:` after `pymdownx.snippets` *(at least in the edited description)* must be `pymdownx.snippets:`. Check your YAML syntax if something does not work, for example [here](https://www.yamllint.com/). And by the way, use user mentions in comments `@somenickname` then the user will get notification in SO. – hotenov Mar 10 '23 at 09:41
  • Hi @hotenov, I have the colon after pymdownx.snippets. See the excerpt here: https://pastebin.com/Zh9r5xQp Perhaps something else is wrong? – oceanclub Mar 29 '23 at 10:49
  • @oceanclub, well, should work. Check all your paths carefully. PAY ATTENTION that `base_path` path MUST be the list, ie. `["docs"]` and `auto_append` is also a list. Do NOT use `null` for `attr_list` and `abbr` plugins (or DO if you really understand what it means). Update description again (if you can). Try to change the order of plugins, restart your mkdocs server (and update mkdocs to the latest version) – hotenov Mar 29 '23 at 14:03