Introduce option to preview from subdirectory - Python mkdocs

Problem

Relative paths to assets and links behave differently at the root of a domain compared to sub-directories. Notably, relative paths backward from the root always resolve to the root, whereas relative paths backward from subdirectories adhere to the directory structure.

When docs are built and published to a subdirectory, this quirk will mean that the preview experience created by mkdocs serve will differ from what is actually published.

Example:

|-- docs
|   |-- images
|   |   `-- example.png
|   `-- index.md
`-- mkdocs.yml
# index.md

Both images are rendered when using `mkdocs serve`, but only the bottom
image is rendered if built/published to a subdirectory/subfolder:

![should not render](../images/example.png)
![should render](./images/example.png)

mkdocs serve -> http://localhost:8000/../images/example.png
published -> http://example.com/all-docs/my-doc/../images/example.png

Possible Ways to Support

  • Maybe interpret and leverage the site_dir configuration option as part of the preview (so that instead of http://localhost:8000/ the preview would be available at http://localhost:8000/{site_dir} or similar?
  • Or add an explicit preview_dir configuration to the serve command to achieve the same?
Asked Oct 11 '21 15:10
avatar iamEAP
iamEAP

2 Answer:

I'm assuming you have not set the site_url config option. If that setting includes a subdir (https://example.com/subdir/) then the local server will alter its behavior to account for it. The site is still served from http://localhost/ but other adjustments are made to ensure links make sense, etc.

1
Answered Nov 20 '20 at 13:42
avatar  of waylan
waylan

https://github.com/mkdocs/mkdocs/pull/2424 implemented the suggested way to alleviate this.

1
Answered Jul 07 '21 at 23:55
avatar  of oprypin
oprypin