Use absolute URL's for the assets

[jeffreymeng]

I want to be able to use clean URLs with trailing slashes for the links in my generated docs (e.g. page.html becomes /page/), however all the references to the assets are relative, so they all break when using clean URLs with a trailing slash.

Is there any way to make the links to the assets relative (I provide a base path)?

[Gerrit0]

This isn't possible right now with the default theme, but it would be a neat feature to have.

[RohitRox]

Momentarily I am doing this bad hack in typedoc.js to get base path/url prefix

  const Handlebars = require('handlebars');

  const BASE_URL="https://some.app/";

  Handlebars.registerHelper('relativeURL', function(url) {
    return BASE_URL + url;
  });

  module.exports = {
  // typedoc configs
  }

[DavidPeicho]

I went for another hack. It's broken only for the index.html page. There are not many links, so this should be good enough:

sed -re 's@<(\w+)(.*)href="([^http].*)"(.*)>@<\1\2href="/api\/\3"\4>@g' -i ./dist/api/index.html
sed -re 's@"(assets/.+)"@"/api/\1"@g' -i ./dist/api/index.html

Basically I use the sed utility to create my own path relative to a subroute api.
I am sure my regexp isn't 100% reliable, but for this use case it should be good enough.

To explain a bit more:
The first sed will look for tag like <link> and <a>, extract their href when they don't start with the letters "http", and I then prepend to the href my subroute (in this case api).

The second one works the same way but search for every "assets/" (for script, search, etc...)

[weibinzhu]

Momentarily I am doing this bad hack in typedoc.js to get base path/url prefix

  const Handlebars = require('handlebars');

  const BASE_URL="https://some.app/";

  Handlebars.registerHelper('relativeURL', function(url) {
    return BASE_URL + url;
  });

  module.exports = {
  // typedoc configs
  }

@RohitRox sorry to bother, but could you explain more? Because I tried to config in the same way but didn't work.

[weibinzhu]

Momentarily I am doing this bad hack in typedoc.js to get base path/url prefix

  const Handlebars = require('handlebars');

  const BASE_URL="https://some.app/";

  Handlebars.registerHelper('relativeURL', function(url) {
    return BASE_URL + url;
  });

  module.exports = {
  // typedoc configs
  }

@RohitRox sorry to bother, but could you explain more? Because I tried to config in the same way but didn't work.

I get it. Basically I need to overwrite the custom helper "relativeURL" initally defined in typedoc, to do that I need to register another one and make sure that both typedoc and my own project are using the same Handlebars.

[marcin-wlodarczyk]

+1

There should be absoluteUrl cli option available.

[zhixinbao]

+1

[chrisui]

Slightly confused how this works in the actual typedoc website where generated docs are hosted at /example and /api? Links throughout the docs are all generated relative to those. Ie. /example/assets/main.js

edit: ah, trailing slash is important. I was using next.js as a proxy for the generated output which strips trailing slashes by default.

[aminya]

GitHub Pages doesn't work with relative paths. This option is necessary.
https://www.pluralsight.com/guides/fixing-broken-relative-links-on-github-pages

[Gerrit0]

GitHub Pages doesn't work with relative paths.

Given that TypeDoc's site, which includes two rendered TypeDoc projects, is deployed to GH pages with no issues I'm pretty confident in saying this is false...

[aminya]

It doesn't work for Zeromq.js. I just broke the documentation so that you can check:

http://zeromq.github.io/zeromq.js/modules/_index_.html

The source
https://github.com/zeromq/zeromq.js

Here is the reason:
https://maximorlov.com/deploying-to-github-pages-dont-forget-to-fix-your-links/
https://www.pluralsight.com/guides/fixing-broken-relative-links-on-github-pages

[Gerrit0]

The site you linked to is built with an ancient version of TypeDoc... which isn't even TypeDoc, it's an unmaintained fork. The problem you're running into is not relative links, but that the githubPages option was added in 0.22.4. Prior to that, if deploying to GitHub pages, you had to manually create a .nojekyll file in your deployed directory to prevent GitHub pages from removing files starting with _ from your deployed site.

[aminya]

OK, updating the typedoc fixes that issue. I missed the package renaming and npm-check-updates didn't update beyond that version.

[isaacyakl]

Slightly confused how this works in the actual typedoc website where generated docs are hosted at /example and /api? Links throughout the docs are all generated relative to those. Ie. /example/assets/main.js

edit: ah, trailing slash is important. I was using next.js as a proxy for the generated output which strips trailing slashes by default.

I was in the same situation (deploying to a subdirectory in Vercel: /public/docs). As @chrisui stated, link to your TypeDoc documentation directory with a trailing slash until this issue is resolved or an option is provided.

Do NOT do this:

example.com/docs

Do this:

example.com/docs/

[Gerrit0]

An option --useHostedBaseUrlForAbsoluteLinks is included in TypeDoc 0.26, which is releasing 2024/06/21