How can I use Snippet at the same time as README and index.md?

[AsheKR]

My directory structure

- README.md
- mkdocs.yml
- assets/
  - image/
    - coverage.svg
- docs/
  - index.md  => --8<-- "README.md"

My mkdocs settings

markdown_extensions:
- pymdownx.snippets:
    check_paths: true

"assets/image/coverage.svg" can see it at README.md, but not at index.md.
How can I see them in both places?

[facelessuser]

I'm not exactly sure what you are asking, but I'm assuming it is similar to what we are doing with our license file?

• We reference the license file here: https://github.com/facelessuser/pymdown-extensions/blob/main/docs/src/markdown/about/license.md
• But include the license file at the root of the project (along with our snippet folder) in our config: https://github.com/facelessuser/pymdown-extensions/blob/main/mkdocs.yml#L143

[ssbarnea]

This approach breaks once you start to build multi-site/mono-repo sites as the base_path is no longer valid.

[facelessuser]

Yep, if you are having different sites that all need different base_path, then yeah, its going to break, but this is a multi-repo problem, not a Snippets problem.

[ssbarnea]

Path to images continue to work as they are relative to current file. Still, with snippets, it seems that there is no way to have any way to express inclusion relative-to-current file, as that relativeness is always to base_path, which by default is mkdocs.yml location.

As with multi-sites building, you now have another mkdocs.yml file and there is no way to specify a 'base_path` for each child, you endup with not being able to use snippets at all.

If i am correct, that problem is valid for any implementation of multi-site, not only the one I mentioned.

How can we address it? Would it be possible to have a way to express a relative path to current file or mkdocs internals do not offer any way to express this? Maybe something like {{mydir}}/../README.md?

I kinda understand why mkdocs went the extra mile to prevent users from importing files from outside docs/ folder.

Sidenote: now I am considering if adding a requirement that for a any sub-projects to not use any form of inclusions, as all apparently all of them seem to break when combining into a parent site. So far I only tested symlinks, markdown_include.include and pymdownx.shippets and none worked.

As I suspended the migration to mkdocs after the first two projects, that would not be a big deal. Still, the issue of README.md, CONTRIBUTING.md shared between repository root and docs/ folder seems to be a real PITA. Any practical suggestion would be appreciated, tx.

[facelessuser]

First, please create a new discussion as what you are talking about is a whole new use case.

Second, I have no idea how your multi-repo environment looks, how you are managing and generating your docs, nor what the MkDocs CWD is when generating each repo's docs. I don't use multi-site/mono-repo sites. Please create a new discussion and provide more specifics. Right now I have no idea how you are doing what you are doing, so any suggestions from me will not be helpful until you can clearly lay out the process by which your sites are generated.

[AsheKR]

I think the question was too vague. Thank you for reading my comment!

You can see the image ( /assets/images/main.png ) at README.md, but you can't see the image at overview.md you're referring to.

[facelessuser]

Yep, Snippets doesn't rewrite your image links or any links for that matter, so if they are relative to a certain location, and you insert a snippet into another file at a different relative location, image links may not match up.

Snippets simply insert the content of a file in another. It doesn't scan the content and make sure it will make sense in the context you are inserting it in. If you use absolute links, then it'll probably find things just fine.

[AsheKR]

How can I use the absolute path? Can you give me an example?
I don't think /assets/image/coverage.svg works either.

[facelessuser]

How can I use the absolute path? Can you give me an example?

A full path where an image can actually be found.

In this file: https://github.com/facelessuser/pymdown-extensions/blob/main/docs/src/markdown/extensions/tabbed.md. I have one image showing in the page when you click over to the link (in the documentation it actually shows more images, but we will focus on the one that is visible for this example). It is specified with ![Tabbed Style Narrow](../images/tabbed-default-narrow.png). GitHub can find it because it is, in fact, relative to the tabbed.md file in the repository. It also shows in my MkDocs documentation because it is relative to the HTML file on the pages server as well: https://facelessuser.github.io/pymdown-extensions/extensions/tabbed/#alternate-style.

But, if it wasn't, I'd have to somehow specify the link in a way in which it could be seen in both cases. That could be done using an absolute path. A path that is no longer relative to location. You could maybe pull it off if you:

1. knew the exact location of the image on the pages server, which I can figure out: https://facelessuser.github.io/pymdown-extensions/images/tabbed-default-narrow.png
2. or if you knew the exact location of the raw image on the repository, which I can also figure out: https://raw.githubusercontent.com/facelessuser/pymdown-extensions/main/docs/src/markdown/images/tabbed-default-narrow.png

Both of the above links are absolute and would work no matter where they are specified. They are full URLs pointing to an image on some server. There is no relative normalization of the path needed.

[AsheKR]

Thank you for your quick response and clear and detailed response. I was touched. I want to buy you a cup of coffee.

[facelessuser]

Thank you! And glad I could help.