Link to file without getting content hash in downloaded file's name

[Feuermurmel]

I'm using the @docusaurus/plugin-content-docs plugin to generate a site. The pages link to files that users should download (e.g. PDF files). My problem is that in the built site, the files have their content's hash added to the file names. This results in the downloaded files also having that hash in their name. I would like to find a way to prevent that.

I know that the content hash is intentionally added to the file names so that the web server can send headers to allow aggressively caching the files. I like that.

The project's structure looks like this:

- docs/
  - index.mdx
  - file.pdf

index.mxd:

---
sidebar_position: 1
---

# Index

[file.pdf](file.pdf)

And the file structure of the generated site looks like this:

- build/
  - assets/
    - files/
      - file-9175cd858280b0c1d81c05c7ed2e85ce.pdf

What I tried is to write a plugin using the configureWebpack() hook to change the file name pattern used by Webpack for these assets. But I think I'm poking at the wrong place, because I can't see any change to the output file structure:

import type { Plugin } from "@docusaurus/types";

function isObject(value: unknown): value is Exclude<object, null> {
  return typeof value === "object" && value !== null;
}

export default (): Plugin<void> => ({
  name: "foo",
  configureWebpack(config, isServer) {
    if (!(process.env.NODE_ENV === "production")) {
      return;
    }

    // Find the right loader rule and overwrite its "name" option.
    if (Array.isArray(config?.module?.rules)) {
      for (let rule of config.module.rules) {
        if (isObject(rule) && Array.isArray(rule.use)) {
          for (let use of rule.use) {
            if (isObject(use) && "options" in use && isObject(use.options)) {
              if (use.options.name === "assets/files/[name]-[contenthash].[ext]") {
                use.options.name = "assets/files/[contenthash]/[name].[ext]";
              }
            }
          }
        }
      }
    }
  },
});

My goal with the plugin was to change the output file structure to this:

- build/
  - assets/
    - files/
      - 9175cd858280b0c1d81c05c7ed2e85ce/
        - file.pdf

Is there any way I can achieve this? Or is this potentially a feature that Docusaurus could provide via an option/configuration?

[Feuermurmel]

Btw I have a workaround now using this in a .htaccess file (glad that my crummy hosting provider still uses Apache):

RewriteEngine On
RewriteCond %{REQUEST_URI} ^/assets/files/([^/]+)-[a-f0-9]+(\.[^./]+)$
RewriteRule ^ - [env=filename:%1%2]
Header set "Content-Disposition" "attachment; filename=\"%{filename}e\"" env=filename

[slorber]

You need to put your file in website/static/myfile.pdf, and you can link to it using the pathname:///myfile.pdf protocol

https://docusaurus.io/docs/markdown-features/assets#static-assets

[Feuermurmel]

Thanks for the tip. I was already aware of it. But it does not seem viable to me because I'm working with hundreds of files across tens to hundreds of docs pages. I'd like to keep the files close to the pages (currently, each page is at docs/<category>/.../<page-name>/index.mdx and associated files are in docs/<category>/.../<page-name>/). Additionally, Markdown editors generally are able to automatically produce relative links to files by dragging them into the editor, greatly increasing ease-of-use for my users. But editors can't produce or follow pathname:///myfile.pdf URLs.

What do you think about making the asset name pattern configurable, so that it can e.g. be set to assets/files/[contenthash]/[name].[ext], preserving the original file name?

There is prior art: For example, GitHub does something similar when attaching a file to an issue/discussion (and probably other places). As an example, I have this PDF locally called "Software Error Incident Categorizations in Aerospace.pdf". When I drag it into the editor here, I get this link:

[Software Error Incident Categorizations in Aerospace.pdf](https://github.com/user-attachments/files/28140863/Software.Error.Incident.Categorizations.in.Aerospace.pdf)

Software Error Incident Categorizations in Aerospace.pdf

[slorber]

I'd like to keep the files close to the pages

By default, Docusaurus doesn't expose those co-located files, unless you require them. These files have no path, the docs/blog/pages plugin does not understand them, and simply ignore them.

However you can configure extra static directories if you want to expose more files, so it's technically possible to give an url to docs/blog/pages folder content:

https://docusaurus.io/docs/next/api/docusaurus-config#staticDirectories

---

What do you think about making the asset name pattern configurable, so that it can e.g. be set to assets/files/[contenthash]/[name].[ext], preserving the original file name?

It's technically already possible, although we don't recommend it nor plan to introduce a first-class config option. Create a plugin and use configureWebpack() hook.

You can write a remark plugin that processes the links before our own link processor runs: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-mdx-loader/src/remark/transformLinks/index.ts

You can create a beforeDefaultRehypePlugins that adds the pathname:// prefix automatically to certain links for example, or do whatever else modification to the URLs you want that will make it compatible with your editor system.

---

If you want to expose files automatically in website/build with more granularity (for example, only pdfs, not mdx files), you can also use configureWebpack to add your own custom CopyPlugin.

See how we implement ours here: https://github.com/facebook/docusaurus/blob/main/packages/docusaurus/src/webpack/plugins/StaticDirectoriesCopyPlugin.ts

The abstraction is only for Webpack/Rspack compatibility, but behind it's just https://webpack.js.org/plugins/copy-webpack-plugin/ or https://rspack.rs/plugins/rspack/copy-rspack-plugin

Keep in mind that this only copies your files from one folder to another.

At the end of the day, you can also copy files manually with terminal commands to expose them in your deployment:

cp website/docs/category/myfile.pdf website/build/docs/category

[slorber]

There is prior art: For example, GitHub does something similar when attaching a file to an issue/discussion (and probably other places). As an example, I have this PDF locally called "Software Error Incident Categorizations in Aerospace.pdf". When I drag it into the editor here, I get this link:

[Software Error Incident Categorizations in Aerospace.pdf](https://github.com/user-attachments/files/28140863/Software.Error.Incident.Categorizations.in.Aerospace.pdf)

You can see for yourself that the file has a unique identifier. If I do the same, I get a different id:

[Software.Error.Incident.Categorizations.in.Aerospace.pdf](https://github.com/user-attachments/files/28142377/Software.Error.Incident.Categorizations.in.Aerospace.pdf)

This is automatically generated and does not reference an asset by a file-system path, so I don't believe it's similar. You can also use IDE/browser extensions that automatically upload files to a unique cloud endpoint and then get a stable URL.