Help with Snippets - can't locate include file

[rossco555]

I'm having trouble trying to setup a glossary in accordance with adding a glossary and would appreciate anyone's help.

I can get abbreviations to work when I define these in the same file, but I seem to not be able to get the external file to include with --8<-- "includes/abbreviations.md" as documented.

I have abbreviations.md in a folder called includes in the project root directory and used the above line from the documentation in documentation markdown files in various levels of my docs structure.

I tried both inline and block notation, which I saw mentioned at PyMdown.

I checked both pip install pymdown-extensions and pip install Pygments and get a "requirement already satisfoed" type confirmation whch leads me to believe I have everything installed as necessary.

My mkdocs.yml includes the below

# Extensions
markdown_extensions:
    - abbr
    - admonition
    - attr_list
    - pymdownx.details
    - pymdownx.highlight
    - pymdownx.superfences
    - pymdownx.snippets:
        check_paths: true

Now that I have added check_paths I can see the error is in locating the snippet file as per below:

INFO    -  Cleaning site directory 
INFO    -  Building documentation to directory: /Users/xxxx/Sites/yyyy/site 
ERROR   -  Error reading page 'index.md': Snippet at path include/abbreviations.md could not be found 
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 829, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 782, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 1259, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 1066, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.9/site-packages/click/core.py", line 610, in invoke
    return callback(*args, **kwargs)
  File "/usr/local/lib/python3.9/site-packages/mkdocs/__main__.py", line 176, in gh_deploy_command
    build.build(cfg, dirty=not clean)
  File "/usr/local/lib/python3.9/site-packages/mkdocs/commands/build.py", line 271, in build
    _populate_page(file.page, config, files, dirty)
  File "/usr/local/lib/python3.9/site-packages/mkdocs/commands/build.py", line 171, in _populate_page
    page.render(config, files)
  File "/usr/local/lib/python3.9/site-packages/mkdocs/structure/pages.py", line 175, in render
    self.content = md.convert(self.markdown)
  File "/usr/local/lib/python3.9/site-packages/markdown/core.py", line 261, in convert
    self.lines = prep.run(self.lines)
  File "/usr/local/lib/python3.9/site-packages/pymdownx/snippets.py", line 137, in run
    return self.parse_snippets(lines)
  File "/usr/local/lib/python3.9/site-packages/pymdownx/snippets.py", line 129, in parse_snippets
    raise IOError("Snippet at path %s could not be found" % path)
OSError: Snippet at path include/abbreviations.md could not be found

Please help!

[facelessuser]

Is includes relative to your base path? Or do you need to set base_path?

[facelessuser]

Well, if you are running MkDocs from gte-m-framework/.. then I assume -8<-- "gte-m-framework/includes/abbreviations.md" would work. Or, you could set base_path to gte-m-framework and then use -8<-- "includes/abbreviations.md". This is all configured in Snippets options in the mkdocs.yml.

[rossco555]

I tried that (-8<-- "gte-pm-framework/includes/abbreviations.md") just now and get the same error, ending in:

OSError: Snippet at path gte-pm-framework/includes/abbreviations.md could not be found

Also tried (again in desperation rather than expectation) -8<-- "orgName.github.io/includes/abbreviations.md" and got a similar result.

For completeness, I also tried --8<-- "includes/abbreviations.md" with the following base_path configs:

• base_path: "gte-pm-framework" gives OSError: Snippet at path includes/abbreviations.md could not be found (with no mention of the base_path)
• base_path: "gte-pm-framework/" (similar result)
• base_path: "gteGroup.github.io" (similar result)
• base_path: "gteGroup.github.io/" (similar result)

Not sure what else to try or how to provide any further information! Thanks for all your persistence so far.

[facelessuser]

Unfortunately, I'm guessing right now at how your project is configured and run. You will not use gteGroup.github.io as that is not part of the file system when this is built. There is no magic when it comes to snippets and paths. We are doing a simple

os.path.exists(os.path.join(base, path))

The default base_path is ., so you are simply doing the following if you are not specifying a base_path:

os.path.exists(os.path.join('.', path))

The problem is that I don't understand where you are executing mkdocs and where the path is relative to where you are executing. This is also assuming MkDocs doesn't change the working directory, but I don't think it does.

[rossco555]

I realised as I was about to post that I'm running as follows - gteGroup.github.io % mkdocs gh-deploy --config-file ../gte-pm-framework/mkdocs.yml --remote-branch main - that the answer is right there: settings base_path: "../gte-pm-framework" (ie with the step up a directory out of gteGroup.github.io first) has solved the issue.

Thanks again for your persistence in helping me out - can imagine that was almost as frustrating for you!

[facelessuser]

lol, no problem. I figured if I explained what Snippets was doing that the answer would become obvious. I'm glad it finally clicked 🙂.