Bug: Docsify's path handling is problematic (and broken in some scenarios)

Bug Report

Docsify's default path handling is problematic and/or broken in several scenarios:

Docsify's path behavior is inconsistent
Docsify handles paths differently for links and other resources like images and embedded content. This inconsistency requires users to research and memorize how and why path behavior varies based on resource type which is unnecessarily confusing and makes Docsify unintuitive for users.
Docsify's relative path behavior is non-standard
Relative paths are generally expected to be relative to the context in which they are used. In the context of a website made up of a collection of separate pages, this means relative paths should be relative to the page where they are used. This provides document portability by allowing links between documents and resources to remain intact as they are moved throughout the hierarchy so long as their location relative to each other remains the same.
- 🟢 Docsify treats relative non-link paths (images, embedded content, ...) as relative to the current page route. This is the correct behavior for relative paths.
- 🟡 Docsify treats relative link paths as relative to a site's index.html route. This makes sense from a technical perspective, but this is not expected behavior based on how relative paths work elsewhere. For sites with a flat hierarchy where the index.html and markdown pages are located at the root (/) this isn't an issue, but for sites with nested routes (e.g., /dir/page.md) or a nested index.html (e.g., /docs/index.html) this results in confusion, the need to use unintuitive paths, and broken or incorrect links.
Docsify's absolute path behavior is non-standard
Absolute paths are generally expected to be relative to the top-most level in a domain or directory hierarchy. In the context of a Docsify site, this most commonly means the root of the domain (/), but nested sites (/docs/index.html) may prefer to have absolute paths relative to the index.html route for site portability. This provides consistent and reliable paths to resources from any level within the hierarchy (e.g., accessing /assets/image.png from /, /foo/, or /foo/bar/baz).
- 🟡 Docsify treats absolute non-link paths (images, embedded content, ...) as relative to the current page route. This is not how absolute paths work elsewhere which causes confusion, the need to use unintuitive paths, and broken or incorrect links.
- 🟡 Docsify treats relative link paths as relative to a site's index.html route. This is not how absolute paths work elsewhere which causes confusion, the need to use unintuitive paths, and broken or incorrect links.
- 🔴 Docsify's handling of absolute paths prevents absolute paths from being used to access resources above the site's level in the hierarchy. For example, it is not possible to access /assets/image.png from /dir/page.md using an absolute URL.
Docsify's absolute path behavior is broken for nested routes
🔴 In Docsify attempt to treat absolute non-link paths (images, embedded content, ...) as relative to the current page route, it incorrectly adds the current page route to paths that already contain the page route. For example:
```
[Root]
└─ docs
   ├─ dir
   │  ├─ image.png
   │  └─ page.md
   ├─ index.html
   └─ README.md
```
```


![](/dir/image.png)
```
Result:
```
<img src="/dir/dir/image.png">
```
Docsify does not provide a way to modify or opt-out of its problematic handling of absolute paths
This has led users resorting to using HTML instead of markdown and PRs like fix: render image in absolute path #1868 which propose working around these issues by introducing more options or custom markdown syntax. None of these would be necessary if paths simply worked the way people expected them to by default. Docsify does offer configuration options like basePath and relativePath, but neither of these issues allows paths in Docsify to work the way they do outside of Docsify and as people expect them to.

The result has been many issues and PRs that remain unresolved. These are the ones I've found from a very simple search for "absolute" and "relative". There are most likely others that are not accounted for here.

Steps to reproduce

To help others understand the problem, I have created a demo link and non-link paths can be tested:

What is current behaviour

Test results from the Codesandbox Demo can be seen in the following table:

What is the expected behaviour

Paths should be consistent for all resource types.
All relative paths should be relative to the page in which they are used by default.
All absolute paths should be relative to the top-most level in the domain or directory hierarchy by default.
Configuration options should allow users to define base paths for relative and absolute links:
- basePath: Defaults to null. Functionally the same as setting relativeBasePath and absoluteBasePath to the same value.
- relativeBasePath: Defaults to current page route. Overrides basePath.
- absoluteBasePath: Defaults to /. Overrides basePath.

A :basepath markdown attribute (or similar) should allows specifying the base path for individual elements. This is required to allow accessing resources outside of the current index.html route when one of the base path options above would otherwise prevent it. For example:

[Root]
├─ assets
│  └─ image.png
└─ docs
   ├─ index.html
   └─ README.md

window.docsify = {
  basePath: '/docs/`
}

<!-- /docs/README.md -->

![](/assets/image.png ':basepath=/')   
![](image.png ':basepath=/assets/')

Result:

<img src="/assets/image.png">
<img src="/assets/image.png">

If these changes are implemented, the default behavior will be as follows:

@jhildenbiddle

@jhildenbiddle I agree with you about the path issues in docsify and the whole pic designs which we need take care.
About the :basepath config, It indicates the base path directly with / path/ or even ../path/scenarios, if we support the new path config, I think we may need refactor getAndRemoveConfig#1825 in advance.

Hi, I am currently encountering the problem of resolving absolute paths to relative paths, using the basepath mentioned in the issue, but it did not solve the problem.

![image.png](/assets/image/design-patterns-01.png ":basepath=/")

Any news in this issue?

I am currently encountering issue 2, and I do not want to change my document directory structure. Is there any way to resolve this?

@L-Super

I am currently encountering issue 2, and I do not want to change my document directory structure. Is there any way to resolve this?

Hi @L-Super , could provide more details on your issue? and I may find a workaround to solve it before we settle this issue down.
For path related issue, consider try alias or rewrite it in hooks instead of re- structure your docs totally.

@L-Super

I am currently encountering issue 2, and I do not want to change my document directory structure. Is there any way to resolve this?

Hi @L-Super , could provide more details on your issue? and I may find a workaround to solve it before we settle this issue down. For path related issue, consider try alias or rewrite it in hooks instead of re- structure your docs totally.

I placed this repo under the docs folder and renamed SUMMARY.md to guide.md, while my directory structure for docs is as follows:

index.html:

<body>
  <div id="app"></div>
  <script>
    window.$docsify = {
      name: '<span>docsify</span>',
      logo: '/favicon.svg',
      relativePath: true,
      loadSidebar: 'guide.md',
      auto2top: true,
      loadNavbar: true,
      subMaxLevel: 2,
      mergeNavbar: true,


      repo: 'https://github.com/L-Super',

      pagination: {
        previousText: '上一章节',
        nextText: '下一章节',
        crossChapter: true,
        crossChapterText: true,
      },
      loadFooter: true,
      baiduTjId: "xxxx",
      // 广告配置
      ads: [
        {
          img: 'resources/images/wx_qrcode.png'
        },
      ],
    }

    window.$docsify.customPageTitle = {
      prefix: false,      // [optional] title prefix. default: false eg: prefix: "Application"
      suffix: "在线充电站",      // [optional] title suffix. default: false eg: suffix: "v1.0.0"
      separator: '|',       // [optional] separator for title eg: title->   prefix | title | suffix
      debug: false,      // [optional] should debug
    }
  </script>
  <!-- Docsify v4 -->
  <script src="resources/js/docsify.js"></script>

  <script src="resources/js/prism-bash.min.js"></script>
  <script src="resources/js/prism-cpp.min.js"></script>
  <script src="resources/js/docsify-pagination.min.js"></script>
  <script src="resources/js/docsify-footer.min.js"></script>
  <script src="resources/js/vanilla-back-to-top.min.js"></script>
  <script src="resources/js/docsify-plugin-title.min.js"></script>
  <script src="resources/js/docsify-ads.min.js"></script>
  <script src="resources/js/docsify-baidu-tj.min.js"></script>

  <script>
    addBackToTop({
      diameter: 56,
      backgroundColor: 'rgb(66, 185, 131)',
      textColor: '#fff',
    });
  </script>

  <script>
    if (typeof navigator.serviceWorker !== 'undefined') {
      navigator.serviceWorker.register('pwa.js')
    }
  </script>
</body>

root guide.md:

* [程序员英语学习指南](/A-Programmers-Guide-to-English/README.md)

Directory structure:

docs/A-Programmers-Guide-to-English
├─assets
├─essence
├─make-a-program
├─qa
├─resources
└─training

When I switch between different sections from the left side, the URL shows an incorrect path.

Current behaviour：

http://localhost:3000/#/A-Programmers-Guide-to-English/essence/make-a-program/README

Expected behaviour:

http://localhost:3000/#/A-Programmers-Guide-to-English/make-a-program/README

@L-Super

Hi @L-Super , I think you can try the alias config to do the trick.
You can refer our docs here to see how it works on live, we rewrite routes also, see the behavior in our site docsify here.

docsify/docs/index.html

Line 77 in cec43d7

alias: {

And if you could make a PR on your own repo (or other new place ) with the changes you mentioned above ( I could fork and reproduce it ).
I can help you to find a feasible solution as well.

@L-Super

Hi @L-Super , I think you can try the alias config to do the trick. You can refer our docs here to see how it works on live, we rewrite routes also, see the behavior in our site docsify here.

docsify/docs/index.html

Line 77 in cec43d7

alias: {

And if you could make a PR on your own repo (or other new place ) with the changes you mentioned above ( I could fork and reproduce it ).
I can help you to find a feasible solution as well.

I created my repo, you can reprodeuce it.

@L-Super

Hi @L-Super , I think you can try the alias config to do the trick. You can refer our docs here to see how it works on live, we rewrite routes also, see the behavior in our site docsify here.

docsify/docs/index.html

Line 77 in cec43d7

alias: {

And if you could make a PR on your own repo (or other new place ) with the changes you mentioned above ( I could fork and reproduce it ).
I can help you to find a feasible solution as well.

I created my repo, you can reprodeuce it.

Hi @L-Super In order not mess up this main assumption on this issue, I move it to #2370 .

Thank you John for making this extensive tracking of all the URL problems. I haven't read the whole issue, but we should eliminate custom URL handling and use the standardized URL API, and paths should be have as they do naturally in vanilla web (basically we simply add .md is a browsable file type for web sites, but we should not otherwise change standard path behavior).

Hi, I've hit this bug while using alias and images and I was wondering if there is any progress on fixing it or a workaround?

@chetta19

Hi, I've hit this bug while using alias and images and I was wondering if there is any progress on fixing it or a workaround?

Hi @chetta19 , the image relative path isn't consistent to the generic behavior for now. If you have to use it.
I suppose you may have a try on building an image link post processor as an afterEach hook, which could filter links and convert it to what your expectation is.

Is this issue being worked on?

Handling hyperlink paths properly is a pretty essential thing in the World Wide Web!

I'm not sure if some fixes were made in #2579, but if any new issues arise, feel free to submit an issue.

Does that mean we can expect the issue to be fixed in the next release, probably version 5.0.0?

Maybe. I just released version v5.0.0-rc.3. You can give it a try.

I tested v5.0.0-rc.3, and path handling is still broken. Attached is the simplest possible demo I could put together.

Again, the link behaviour is inconsistently wrong. Here's the project structure:

.
└── DemoProject
    ├── DemoProjectIcon.svg
    ├── docs
    │   ├── DocsIcon.svg
    │   └── Docs-ReadMe.md
    ├── index.html
    └── ReadMe.md

Here's the docsify config in DemoProject/index.html:

      window.$docsify = {
            name: "My Project's Docs",
            basePath: `${window.location.origin}/DemoProject`,
            hideSidebar: true,
            homepage: 'ReadMe.md',
            // homepage: 'docs/Docs-ReadMe.md',
      };

I played around with using different markdown files as the home-page, and the results were inconsistent.

when docs/Docs-ReadMe.md is opened as the homepage, relative references to embedded images don't work
when ReadMe.md is set as the homepage, and docs/Docs-ReadMe.md is opened, the absolute references to embedded images don't work, but the absolute hyperlink to the ReadMe.md file does
in both cases the relative markdown file link to the parent directory doesn't work

DocsifyDemo.zip

Navigation Menu

Repository navigation

Bug: Docsify's path handling is problematic (and broken in some scenarios) #1891

Bug Report

Steps to reproduce

What is current behaviour

What is the expected behaviour

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Bug: Docsify's path handling is problematic (and broken in some scenarios) #1891

Description

Bug Report

Steps to reproduce

What is current behaviour

What is the expected behaviour

Activity

Koooooo-7 commented on Sep 20, 2022

loprx commented on Jul 22, 2023

johnfercher commented on Aug 18, 2023

L-Super commented on Feb 9, 2024

Koooooo-7 commented on Feb 9, 2024

L-Super commented on Feb 10, 2024

Koooooo-7 commented on Feb 10, 2024

L-Super commented on Feb 10, 2024

Koooooo-7 commented on Feb 11, 2024

trusktr commented on Feb 12, 2024

chetta19 commented on Nov 6, 2024

Koooooo-7 commented on Nov 12, 2024

emendir commented on Sep 4, 2025

sy-records commented on Sep 5, 2025

emendir commented on Sep 5, 2025

sy-records commented on Sep 5, 2025

emendir commented on Sep 5, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions