Introduce option to preview from subdirectory - Python mkdocs


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.


|-- docs
|   |-- images
|   |   `-- example.png
|   `--
`-- mkdocs.yml

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 ->

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

2 Answer:

I'm assuming you have not set the site_url config option. If that setting includes a 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.

Answered Nov 20 '20 at 13:42
avatar  of waylan
waylan implemented the suggested way to alleviate this.

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