Relative Paths in VuePress
The following are all scenes in VuePress that involve referencing another markdown file via
- From normal page to normal page;
- From normal page to permalink page;
- From permalink page to normal page;
- From permalink page to permalink page.
All above usages are only valid under
Since VuePress 1.x supports permalinks, that is, the original link based on the directory structure can be converted to any link according to the user's permalink config.
Let us give a practical example, you have a markdown file named
permalink.md in your document's source directory, the default route path that you'll get at the dev server or production will be
permalink.html, once you set the permalink as follows:
--- permalink: /foo/bar/ sidebar: auto ---
The final route path of
permalink.html will be
/foo/bar/, this looks great, but the problem is coming: when you want to write a relative path to link to another page in
permalink.md, such as:
[Go to `./normal.md`](./normal.md)
In a lower version of VuePress, above markdown file will be transformed into following markup:
It means that the relative path will be resolved by vue-router at runtime, since current
/foo/bar/, the resolved path will be
/foo/bar/normal.html, which will let you to get a 404.
A workaround of this issue is to use absolute path at your source code:
[Go to `normal.md`](/normal.md)
But in this case, you will lose some very useful features —— "Ctrl+Click Go To Definition", as well as the automatic correction of file path when the referenced file moves, so the best is that VuePress could help us to transform the relative path to correct absolute path during the build process.
Of course, VuePress did it! for now you're free to use relative paths in VuePress.
The motivation of introducing the above background is that you need to know that once you use relative paths, you don't have to care about the paths of production environment. and also needn't worry about it may goes 404.
Just enjoy your documentation!