Docusaurus: Support Relative Path

[huchenme]

Docusaurus expect baseUrl to be absolute path, to use relative path, I have tried to put baseUrl='' and it does not work for docs link and generated build.

It will be nice that Docusaurus support relative mode as well

[JoelMarcey]

@huchenme Hi. What error do you get when you use baseUrl = ''? Do you get the same thing if you use baseUrl='/'?

[huchenme]

@JoelMarcey
After running npm start in develop mode, docs folder is not working, visiting http://localhost:3000/docs/abc.html will result in http://localhost:3000/docs/abc.html

After running build command, css path and docs path not working as well

[JoelMarcey]

@huchenme Hi. Do you have a repo I can look at to see your siteConfig.js? Thanks!

[huchenme]

Hi @JoelMarcey , I have just created this repo https://github.com/huchenme/docusaurus-demo

It is generated from docusaurus-init and changed the baseUrl to "", you could cd into website and try

yarn start

and click Docs header, you should able to see the error.

and then try run docusaurus build and open generated index.html, click the Docs header again, the css is not rendered correctly.

If you guys are busy, I can work on it and send a PR, is that ok with you?

[jacarma]

I think this is the same feature request: "Make the built site work without a web server"
Acceptance criteria:
yarn build
open file://{PATH}/website/build/{projectName}/index.html in a browser

Expected behaviour: You can navigate through pages and docs and links work

[stoffeastrom]

It would be really nice if this was supported. I just save my build artifacts on circle ci but the site will not work since it doesn't handle relative baseUrl e.g ./

Problems seem to be that in the generated html files css and images are referenced as

./css/main.css
./img/some-image.png

when it should have been

../css/main.css
../img/some-image.png

since they are relative to their html file.

Using the ./css/main.css will be relative to web server root

[kevinbarabash]

The problem I ran into was I want to deploy to docs to both khan.github.io/KaTeX (for production) as well as katex.netlify.com (for testing). We can probably use an environment variable to handle these different base URLs, but it would be nice if we didn't have to.

[lwasylow]

Would be great feature as its quite painful to review build on local machine

[JoelMarcey]

@endiliey - you haven't done anything around this for the next version of Docusaurus, right? I know we had #864 for static asset.

If not, could we employ something similar to what was done in https://github.com/Khan/KaTeX/issues/1525, but within the core instead of siteConfig?

[olafurpg]

This would be a nice feature addition. It would enable users to download an offline zip of the website, open index.html and everything works without a server. Another use-case is that it becomes possible to serve the same generated site from different base URLs.

For example, I'm using docusaurus for documenting Scala projects https://olafurpg.github.io/sbt-docusaurus/ I also release the documentation as a zip file to Maven Central (similar to npm) and it's possible to browse those docs and download offline archives via https://www.javadoc.io/. Currently, the css/js/html artifact links return 404s when browsing sbt-docusaurus docs on https://static.javadoc.io/com.geirsson/sbt-docusaurus-docs_2.12/0.1.1/sbt-docusaurus/docs/installation.html I could work around this problem by generating the site with baseUrl com.geirsson/sbt-docusaurus-docs_2.12/0.1.1/sbt-docusaurus/ but then the site would not work anywhere else.

[olafurpg]

A workaround for this issue is to post-process the anchor links in the html files generated by yarn run build. I wrote a simple transformation in Scala using Jsoup that does a few things (actual code and test suite)

• convert /absolute/path/page.html links to ../relative/page.html links
• process <a href, <img src and <link href (I'm probably missing some other cases, but this was enough on my small sample)
• prefix //example.com with https: to prevent such links from resolving as file://example.com when browsing plain html files without a server
• append /index.html to directory links

None of these transformations are Docusaurus-specific, they can be applied to any static site. I would not be surprised if there already exists a JavaScript library that can do this (more robustly than me 😅 ). The benefit of relative links is that

• the site can be browsed by opening index.html without a file server, which is especially handy if you distribute zip archives of the site for offline browsing.
• the site can hosted at any base url such as on static.javadoc.io for Java/Scala libraries https://static.javadoc.io/com.geirsson/sbt-docusaurus-docs_2.12/0.3.1/sbt-docusaurus/index.html

[tibdex]

Relative paths make deployments really simpler. It would be great to support them in a future release.

In the meantime, here's how you can transform absolute links to relative ones in a postbuild script:

// utils.js
const path = require('path');

const fs = require('fs-extra');
const recursiveReaddir = require('recursive-readdir');

const baseUrlPattern = '/_baseUrlPattern_/';
const baseUrlRegExp = new RegExp(baseUrlPattern, 'g');

const buildDirectory = path.join(__dirname, 'build');

const relativify = (content, filePath) =>
  content.replace(baseUrlRegExp, () => {
    const result = `${path.relative(`${path.dirname(filePath)}`, '')
      // Normalize Windows path separators to Unix ones
      .replace(/\\/g, '/')}/`;
    return result === '/' ? '' : result;
  });

const websiteTextualFileExtensions = ['.css', '.js', '.html', '.xml'];

const isNotWebsiteTextualFile = (filePath, stats) =>
  !(stats.isDirectory() || websiteFileTextualExtensions.includes(path.extname(filePath))));

const postProcess = async () => {
  const filePaths = await recursiveReaddir(buildDirectory, [isNotWebsiteTextualFile]);
  await Promise.all(
    filePaths.map(async filePath => {
      const content = await fs.readFile(filePath);
      const relativePath = path.relative(buildDirectory, filePath);
      await fs.writeFile(filePath, relativify(String(content), relativePath));
    })
  );
};

module.exports = {
  baseUrlPattern,
  postProcess,
};

// siteConfig.js
const {baseUrlPattern} = require('./utils');

const isBuilding = process.env.npm_lifecycle_script
  && process.env.npm_lifecycle_script === 'docusaurus-build'; 

const siteConfig = {
  // Keep `/` in watch mode.
  baseUrl: isBuilding ? baseUrlPattern : '/',
  // ...
};

module.exports = siteConfig;

// postprocess.js
'use strict';

require('loud-rejection/register');

const {postProcess} = require('./utils');

postProcess();

// package.json
{
  "devDependencies": {
    "docusaurus": "1.6.2"
  },
  "scripts": {
    "build": "docusaurus-build",
    "postbuild": "node postprocess"
  }
}

[amimas]

Any update available on this item? This would allow me to have a review site deployed very easily. I can deploy the site in a different path other than what's mentioned in baseUrl but all the generated links are set to absolute path.

[amimas]

@JoelMarcey @yangshun - Would you be able to provide some feedback? If I can I'd love to look into implementing this and submit a PR for it.

[yangshun]

@amimas Sure, go ahead 😄

[amimas]

Any guidance available? I'm new to this and not really sure where to begin.

[endiliey]

I think at this point our architecture relies a lot on baseUrl and supporting this will be quite a huge refactor. I personally feel the effort is better spent elsewhere

_{Sent with GitHawk}

[endiliey]

Just for the sake of people who revisit this issue in the future requesting “build artifacts without a web server”, here is my opinion.

I dont think its a good idea to support serving files without a webserver. At least from my point of view it causes lot more problems than bringing benefit.

It got to do with the protocol used to access the files. When you request anything over the web you're using http, and the server level security is enough to ensure you can only access files you're meant to. But when you drag a file in it's loaded via the local file system (technically file://) and that is massively restricted, for obvious reasons. Under file:// there's no concept of domains, no server level security, just a raw file system.

Ask yourself this: do you really want JavaScript to have the ability to load files from anywhere on your local file system?
Your immediate answer should of course be "not in a million years!". If JavaScript had free reign while operating under file:// there would be nothing stopping it loading pretty much any file, and sending it off who knows where.

Your site is going to need to load resources: images, JSON data, maybe other JavaScript files. And in order to do this it needs to run unhindered by the browser security shackles. It needs http:// access to the files. And for that we need a web server.

I remember https://blog.chromium.org/2008/12/security-in-depth-local-web-pages.html?m=1. explained this security loophole really well

[jacarma]

I agree with you @endiliey, I wanted to provide an easy way to check the requirement is complete, it's not that I use it with file://

We generate the documentation site as an artifact on the CI and it stores and serves it for us. The builds have auto-generated ids so we don't know the final url in advance.
It's a nice feature for us to be able to check the docs in past versions and it would be great to publish them too for our users to check what's supported on each version.
We can do that by knowing the final url in advance and changing the baseurl as part of the build, but we can't make the built site to work both in the CI and the public site.

Of course you know where to put the effort, thanks a lot for the great work :D

[olafurpg]

To echo @jacarma 's comment, our primary use-case is also to host Docusaurus sites at URLs we don't know in advance. For example, here is a 3rdparty service that is hosting our Docusaurus documentation for every published version of a library we maintain https://www.javadoc.io/doc/org.scalameta/munit-docs_2.12/0.4.3/index.html

[ghost]

@endiliey That is your view based on 12 years old article and a couple of false information.

[tiptronic]

@endiliey Sorry - the whole security in a browser is about running a browser safely on a local machine AND on the web. This is how browsers worked since they were invented.
And since Flash is dead, there's no risk at all to run under the file:// protocol... that's why browser-security is there.
For the link, I agree with @atilkan

[JoelMarcey]

All - I find it surreal that I was looking at this closed issue less than 24 hours ago and all of a sudden it started gaining traction with comments again.

That said, I just want you to be aware, in case you didn't know, that @endiliey passed away earlier this year after a long battle with cancer. https://docusaurus.io/blog/2020/01/07/tribute-to-endi

He really gave maximum effort to this project, and I want him to be remembered for that.

[tiptronic]

@JoelMarcey That's really, really sad to read... :(

[ghost]

RIP.

[jacarma]

My most sincere condolences