Ability to refer to links within included files from different levels of docs

[gomathyk]

I have two docs (doc-a and doc-b) that pull the same smaller doc (doc-s) using the markdown include extension.

docs
-folder-1
--subfolder
---doc-a
-folder-2
--subfolder-1
---subfolder-2
----doc-b

Doc-s has a link that refers to another internal doc. When doc-s gets included in doc-a and doc-b, the internal link doesn't work since the no. of levels that needs to be specified for the relative paths are different ((../../../<internal doc path>) for doc-a and (../../../../<internal doc path>) for doc-b).

We tried using the absolute URL instead. Though it works fine locally (mkdocs serve), it doesn't work in the hosted version, since the root folder has child folders (in the example below, en and latest get elimintated).

Example:
docs.example.com/en/latest

Is there a way to retain the link in the smaller doc (doc-s) relative to the site root (docs.example.com/en/latest)?

The current mkdocs.yml config -

- markdown_include.include:
      base_path: docs

[waylan]

I suspect there is no way to make this work at this time. When MkDocs encounters relative URLS to local files it properly modifies them (so long as the path points to a file which exists). In all other situations, MkDocs makes no changes to the URL. Therefore you are completely responsible for ensuring the URL is accurate.

The problem with relative URLs in your case is that MkDocs has no knowledge of markdown_include. It only sees the links of the "combined" source, with the origin location being the parent document, not the location of the included child document. It is not clear how MkDocs would even address that. Seems to me like perhaps this is something which markdown_include should address by ensuring any "included" relative links are adjusted to be relative to the parent document.

There is one other potential solution which occurs to me. If the dev server incorporated the subdirectory, then absolute URLs would work consistently on both the hosted site and in the dev server. For example, if the site_url was set to https://example.com/foo/, then the dev server would use http://localhost/foo/ as the root of the site. This is a feature which has been requested multiple times over the years. @oprypin what are your thoughts about incorporating that into the server?

[oprypin]

For example, if the site_url was set to https://example.com/foo/, then the dev server would use http://localhost/foo/ as the root of the site.

Yes, that would be good to have, regardless of any other considerations.

What would be even better is to just support absolute URLs :s

[oprypin]

So yes, I really like @waylan's idea. I have implemented it at oprypin@b2ac728, but that depends on PR #2385 (and I would prefer not to add this incompatible change directly to that PR).

[waylan]

So yes, I really like @waylan's idea. I have implemented it at oprypin@b2ac728, but that depends on PR #2385 (and I would prefer not to add this incompatible change directly to that PR).

I like it 👍. Not sure why you feel the need to keep it separate though. I see it as a "feature" of the new server implementation. And as / redirects to the correct location, most users will likely never notice.

[mondeja]

mkdocs-include-markdown-plugin rewrites relative URLs including markdown snippets, I suggest you to use it. Otherwise, seems that the problem of rewriting links as absolute ones has been solved, at least as far as possible. I think that relative rewriting of included URLs is the plugins job, so should this issue be closed?

[pawamoy]

As mentioned above, the mkdocs-include-markdown-plugin seems to support this by rewriting relative URLs. Also, upcoming MkDocs v1.6 brings support for absolute URLs, which would solve this too. Therefore we'll close this as completed 🙂 Feel free to comment further.