[Docusaurus v3.4] index.html in static directory raises "Multiple assets emit different content to the same filename" error

Devon-White commented 3 months ago

Have you read the Contributing Guidelines on issues?

[X] I have read the Contributing Guidelines on issues.

Prerequisites

[X] I'm using the latest version of Docusaurus.
[X] I have tried the npm run clear or yarn clear command.
[X] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
[X] I have tried creating a repro with https://new.docusaurus.io.
[X] I have read the console error message carefully (if applicable).

Description

Using docusaurus start while having a index.html in the static directory will cause the following error:

Conflict: Multiple assets emit different content to the same filename index.html

Reproducible demo

https://codesandbox.io/p/devbox/kind-khorana-zg4f99?file=%2Fstatic%2Findex.html%3A5%2C8

Steps to reproduce

Delete index.tsx in src/page
create a index.html in the root of the static directory
Observe failure

Expected behavior

For the html file to be added to the build like before this update, and to be able to serve a index.html file as the landing page.

Actual behavior

Error mentioned above occurs.

Your environment

No response

Self-service

[ ] I'd be willing to fix this bug myself.

homotechsual commented 3 months ago

Not a bug. We build to HTML pages. You cannot have an index.html file in static because we output a root index file. This is expected (and frankly required) behaviour. We have to output some kind of built index page to handle the scaffolding/app loading/container/routing. Even if you don't explicitly make one - we still have to write one for that purpose

Devon-White commented 3 months ago

Not a bug. We build to HTML pages. You cannot have an index.html file in static because we output a root index file. This is expected (and frankly required) behavior. We have to output some kind of built index page to handle the scaffolding/app loading/container/routing. Even if you don't explicitly make one - we still have to write one for that purpose

Understood, this is however a recent behavior as we have had a site since Docusaurus v2 and have handled the index page this way up until this version. We will look into swapping our approach if this is now expected.

Edit: A docusaurus build will also not throw this error, but instead links to / will throw a broken link error instead.

However, in the navbar config you can set like such do avoid the broken links:

  themeConfig:
    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
    ({
      // Replace with your project's social card
      image: 'img/docusaurus-social-card.jpg',
      navbar: {
        title: 'My Site',
        logo: {
          alt: 'My Site Logo',
          src: 'img/logo.svg',
          href: "pathname:///"
        },

Using the pathname protocol will allow you to correctly be redirected back to the index.html

Now the build will complete, and all links work.

Josh-Cena commented 2 months ago

Hmmm. If you don't have a pages/index.tsx, I don't think we would emit build/index.html, so there shouldn't be duplicate assets.

slorber commented 2 months ago

`Using docusaurus start while having a index.html in the static directory will cause the following error:``

During docusaurus start this is normal because we don't use SSR and we have to build/serve an initial entrypoint that is by default index.html

CleanShot 2024-07-19 at 13 32 43

https://webpack.js.org/plugins/html-webpack-plugin/

Afaik this file is served from memory when using the dev server.

We could probably do something but I'm not sure what makes sense. Do you expect Docusaurus dev server to start on http://localhost:3000/docs/myDoc for example?

I'm surprised this ever worked in v2. This behavior probably broke a long time ago already.

Maybe we could generate a random index name, and use this in devServer.historyApiFallback ?

Devon-White commented 2 months ago

We could probably do something but I'm not sure what makes sense. Do you expect Docusaurus dev server to start on http://localhost:3000/docs/myDoc for example?

I'm surprised this ever worked in v2. This behavior probably broke a long time ago already.

For additional context, this remains working on Docusaurus version 3.3.2, which is the version our site is currently running. Upon upgrading to the next version, 3.4, is where you begin to experience this failure.

Hmmm. If you don't have a pages/index.tsx, I don't think we would emit build/index.html, so there shouldn't be duplicate assets.

I was also in this mindset of thinking, that the index.html file should just work (like previously) if there is not a pages/index.tsx file.

Maybe we could generate a random index name, and use this in devServer.historyApiFallback ?

I'm not sure what the best solution here would be, but this feels like it would make sense.

facebook / docusaurus