Relative links to non-markdown files?

[felipecrs]

For example, I have a index.md that includes something like:

The source code is available at [Dockerfile](../../Dockerfile).

And I would expect Docusaurus to properly link the file to the matching GitHub page of it (following the relative path since the index.md file).

But instead, Docusaurus tries to link to this file in my website, which is quite misleading. And OFC broken.

The only workaround I found was to use the full link:

The source code is available at [Dockerfile](https://github.com/felipecrs/jenkins-agent-dind/tree/HEAD/Dockerfile).

Which of course isn't much scalable. Any tips?

[Josh-Cena]

Hi, Docusaurus of course would try to link to the page on your site, since not everyone is hosting their site on GitHub! It's quite weird if we decided to transform relative paths to GitHub URLs. We are not GitHub pages plus: we don't couple ourselves to GitHub in any way. Your solution is correct if you actually want to link to your GitHub page.

Your URL is unambiguously a relative page URL, so we can't infer at all that you meant an asset with relative paths. However, if you want to include that file in your build as well, you can use the @site alias:

The source code is available at [Dockerfile](@site/../Dockerfile).

Where @site is the alias for the folder that docusaurus.config.js is in. Does that work for you?

[felipecrs]

In fact, despite as I used GitHub in the example, I don't use GitHub on where I'm hosting my website with Docusaurus. What I was actually seeking for was something like:

// docusaurus.config.js
module.exports = {
  presets: [
    [
      "classic",
      /** @type {import('@docusaurus/preset-classic').Options} */
      ({
        docs: {
          path: "docs",
          routeBasePath: "docs",
          editUrl:
            "https://review.gerrithub.io/plugins/gitiles/felipecrs/gerrit-jenkins/+/HEAD",
          relativeFilesBaseUrl:
            "https://review.gerrithub.io/plugins/gitiles/felipecrs/gerrit-jenkins/+/HEAD"
        },
      }),
    ],
  ],
};

Namely look at relativeFilesBaseUrl. This would tell Docusaurus to use this instead of the website itself to link relative files (which otherwise would be broken links). Some examples:

Considering that this file is at docs/index.md:

- [Dockerfile](../Dockerfile) links to https://review.gerrithub.io/plugins/gitiles/felipecrs/gerrit-jenkins/+/HEAD/Dockerfile
- Also [.gitignore](.gitignore) links to https://review.gerrithub.io/plugins/gitiles/felipecrs/gerrit-jenkins/+/HEAD/docs/.gitignore
- Or, [Jenkinsfile](./Jenkinsfile) links to https://review.gerrithub.io/plugins/gitiles/felipecrs/gerrit-jenkins/+/HEAD/docs/Jenkinsfile 

This would have the benefit of:

1. Work in both the website and in Gitiles (or whatever markdown renderer provided by the Git project)
2. No need to write the full URL link, which
   • Hostname may change
   • Project name may change
   • And most importantly: the branch does change
     • Docusaurus would still point to "HEAD" as the example below, but at least in Gitiles it would follow the branches accordingly.

Also, I don't think it makes sense to bundle things like Dockerfile and Jenkinsfile in the website assets. When I make such a link in my markdown, it's because I want the readers to know directly where the files are defined in case they would like to contribute.

[Josh-Cena]

Sorry, the problem is that ../../Dockerfile itself is unambiguously a URL, so we won't even attempt to resolve it as a file. If this link appears on the URL docs/foo/bar, 99% of the users would mean a link to page docs, instead of a file link to whatever it represents in the FS.

The problem here is that Dockerfile doesn't have an extension, so you have to be more explicit in helping Docusaurus in figuring out that it's a file path, not a URL page (e.g. with the file:// protocol or whatever)

Your proposal of relativeFilesBaseUrl sounds interesting. Could you send a feature request instead?

[felipecrs]

I shall do. Thank you!

[felipecrs]

Refs: #6463