Make TypeDoc Generate a 404 Page

Motivation

TypeDoc is a document generator that, among other things, converts comments in TypeScript source code into rendered HTML documentation. The generated HTML documentation can be hosted on static website hosting services, such as GitHub Pages, GitLab Pages, Netlify, and CloudFlare Pages. All of them by default use a 404.html file as the content of the 404 page of the site. However, TypeDoc does not generate a 404.html by default. How can we make TypeDoc generate such a 404.html file?

Solution

To make TypeDoc generate a 404.html, one easy way is to use typedoc-plugin-404 developed by 8 Hobbies. In your TypeDoc-enabled source tree, install this plugin by executing:

npm install --save-dev @8hobbies/typedoc-plugin-404

Then, in your typedoc.json file, add @8hobbies/typedoc-plugin-404 to the plugin field:

{
  "plugin": ["@8hobbies/typedoc-plugin-404"]
}

Right now, you can run npx typedoc and you should be seeing a 404.html page at the root of the generated HTML docs. But we are not done yet…

Address the Asset File Link Issue in the Default Theme

If you use the default TypeDoc theme, the links to asset files in the generated HTML are relative. This means, 404.html would not be displayed properly if the user visits a non-existing page in a subdirectory. For example, assuming that the HTML documentation is hosted at https://example.com, then https://example.com/non-existing-page leads to a correctly rendered 404 page, but https://example.com/non-existing-dir/page would not render the 404 page correctly.

This is because the default theme makes 404.html link to asset files by their relative paths. When a user visits https://example.com/non-existing-dir/page, the static hosting service does not redirect the browser to https://example.com/404.html; instead, it merely renders the content of 404.html without modifying the URL. As a result, relative links to asset files now refer to incorrect locations. For example, consider the asset file https://example.com/assets/style.css. 404.html refers to it as assets/style.css, which in this case refers to a different (and non-existing) location https://example.com/non-existing-dir/assets/style.css.

To address this issue, run a script to replace relative asset file links in 404.html with absolute paths. This can be done by using replace-in-files-cli:

npm install --save-dev replace-in-files-cli

Assuming that the documentation is to be hosted at the root of the URL, add the following section to package.json:

{
  "scripts": {
    "doc": "typedoc && replace-in-files --string '=\"assets/' --replacement '=\"/assets/' docs/404.html"
  }
}

Now, running npm run doc generates the doc with a correct 404.html file.

After making this change, to preview 404.html locally, you will likely need to use a local http server, such as npx http-server ./docs, or the one that comes with Python: python3 -m http.server -d docs.

Further Customization

The content of the 404 page can be further customized in typedoc.json:

{
  "plugin": ["@8hobbies/typedoc-plugin-404"],
  "page404Content": "This page is not found 🤯"
}

Or with HTML:

{
  "plugin": ["@8hobbies/typedoc-plugin-404"],
  "page404Content": "<em>This page is not found 🤯</em>"
}

Screenshot: