Slug with explicit .html extension breaks build

[rwwilden]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Prerequisites

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

Description

I'm migrating a blog from Jekyll. It is necessary for me to keep the exact same url structure because there's external refs to these posts. So I have a

slug: a/b.html

in every blog post frontmatter. On build, this fails with the following error:

[ERROR] Unable to build website for locale en.
[ERROR] Error: Expected output HTML file to be found at /home/projects/kkviyzpmp.github/build/blog/a/b.html/index.html.

Running the site works fine, error only happens on build.

Reproducible demo

https://stackblitz.com/edit/github-iuz7vq?file=blog/2021-08-26-welcome/index.md

Steps to reproduce

1. Set a slug in a blog post frontmatter: /a/b.html
2. Run yarn build

Expected behavior

Build should succeed, especially since running the site poses no problems.

Actual behavior

Build fails with the following error message:

[ERROR] Unable to build website for locale en.
[ERROR] Error: Expected output HTML file to be found at /home/projects/kkviyzpmp.github/build/blog/a/b.html/index.html.

Your environment

On stackblitz playground.

Self-service

• I'd be willing to fix this bug myself.

[Josh-Cena]

Could you try setting trailingSlash: false?

[rwwilden]

Could you try setting trailingSlash: false?

That doesn't seem to have any effect. I get the exact same error.

However, I think I have a work-around. If I define the slug as /a/b, the build succeeds and the resulting url becomes /a/b.html. I left trailingSlash as undefined in this case.

Not sure if this is still a bug now or expected docusaurus behavior :)

My work-around leaves me with this url: /a/b/index.html. I'll try it again but now again with trailingSlash: false.

[rwwilden]

Ok, if I put the slugs as /a/b and set trailingSlash: false, I end up with urls like /a/b.html, which is exactly what I want.

I do think that it's a bit unclear from just looking at the slug to understand what the end result will be, but this now seems more like a feature than a bug :)

[Josh-Cena]

Setting slug: /a/b.html is a hacky but not obscure technique to ensure canonical URL, SEO, etc. all work the same as before. I'll need to experiment what happens with trailingSlash: true, but it shouldn't be too surprising.

[rwwilden]

Never mind, this was actually a broken link that I didn't see earlier because of the build issues.

Hm, getting broken links now that weren't there before. And I don't really understand the error message. What's the 23 and 24?

Exhaustive list of all broken links found:

- On source page path = /programming/cloudfoundry/2019/02/26/net-service-broker-03:
   -> linking to 23 (resolved as: /programming/cloudfoundry/2019/02/26/23)
   -> linking to 24 (resolved as: /programming/cloudfoundry/2019/02/26/24)

    at throwError (/home/rwwilden/projects/rwwilden.gitlab.io/node_modules/@docusaurus/logger/lib/index.js:76:11)
    at handleBrokenLinks (/home/rwwilden/projects/rwwilden.gitlab.io/node_modules/@docusaurus/core/lib/server/brokenLinks.js:153:47)
    at async buildLocale (/home/rwwilden/projects/rwwilden.gitlab.io/node_modules/@docusaurus/core/lib/commands/build.js:177:5)
    at async tryToBuildLocale (/home/rwwilden/projects/rwwilden.gitlab.io/node_modules/@docusaurus/core/lib/commands/build.js:38:20)
    at async mapAsyncSequential (/home/rwwilden/projects/rwwilden.gitlab.io/node_modules/@docusaurus/utils/lib/jsUtils.js:34:24)
    at async Command.build (/home/rwwilden/projects/rwwilden.gitlab.io/node_modules/@docusaurus/core/lib/commands/build.js:73:21)

(I stopped using the toy example /a/b.html)

[slorber]

@rwwilden please when. you have a stacktrace, post it in its entirety. You removed the stacktrace from the error message, preventing us to immediately understand what's the issue, needing to reproduce it locally to understand the problem.

The stacktrace is:

[ERROR] Unable to build website for locale en.
[ERROR] Error: Expected output HTML file to be found at /Users/sebastienlorber/Desktop/projects/docusaurus/website/build/blog/docu2.1.html/index.html.
    at readOutputHTMLFile (/Users/sebastienlorber/Desktop/projects/docusaurus/packages/docusaurus-utils/lib/emitUtils.js:75:15)
    at async /Users/sebastienlorber/Desktop/projects/docusaurus/packages/docusaurus-plugin-content-blog/lib/feed.js:41:25
    at async Promise.all (index 0)
    at async generateBlogFeed (/Users/sebastienlorber/Desktop/projects/docusaurus/packages/docusaurus-plugin-content-blog/lib/feed.js:39:5)
    at async createBlogFeedFiles (/Users/sebastienlorber/Desktop/projects/docusaurus/packages/docusaurus-plugin-content-blog/lib/feed.js:85:18)
    at async Object.postBuild (/Users/sebastienlorber/Desktop/projects/docusaurus/packages/docusaurus-plugin-content-blog/lib/index.js:315:13)
    at async /Users/sebastienlorber/Desktop/projects/docusaurus/packages/docusaurus/lib/commands/build.js:171:9
    at async Promise.all (index 1)
    at async buildLocale (/Users/sebastienlorber/Desktop/projects/docusaurus/packages/docusaurus/lib/commands/build.js:167:5)
    at async tryToBuildLocale (/Users/sebastienlorber/Desktop/projects/docusaurus/packages/docusaurus/lib/commands/build.js:38:20)

This makes it clear for us maintainers that the problem is in our blog feed: we added a readOutputHTMLFile() method to create the blog RSS feed HTML content, but it's not reading from the correct output file location.

When an URL already ends with .html, such as /x/y/z.html, we output /x/y/z.html and not /x/y/z/index.html => readOutputHTMLFile apparently doesn't support this logic

---

I'm migrating a blog from Jekyll. It is necessary for me to keep the exact same url structure because there's external refs to these posts.

External refs can be handled with redirects. Many hosts will auto redirect, or serve x.html from both /x and /x.html.

You may want to keep using slug: /x.html but it's really if you want to keep the exact same caninocal URL as before.

Using .html in URL is old school: maybe it's a good time to tell Google that your URLs use a more modern conventional format and drop the extension? In 10 years you'd still want to have the extension? 🤷‍♂️

[slorber]

Good first issue

This is an easy issue that can be easily solved by an external contributor.

Here are some instructions for anyone willing to fix the bug:

• Reproduce by adding slug: /x/y/z.html to any of our website blog post
• Add this to website/_dogfooding/_blog tests (visible here: https://docusaurus.io/tests/blog) => we'll keep this in git and ensure this issue doesn't come back
• Fix the bug in readOutputHTMLFile() + cover in unit test
• Ensure it works fine under all trailingSlash combinations (CI should tell you, we build with trailingSlash: isDeployPreview,)

Disclaimer

We, project maintainers, have limited time and need to protect it.

We kindly ask you to invest your time, trying to be autonomous and proactive instead of expecting us to guide you step-by-step.

• Don't expect us to teach you the basics of Docusaurus: if you want to contribute, you have to get familiar with the project first, reading the official doc
• Don't claim the issue and then ghost us (like it often happens)
• Please at least submit a PR, and only then we assign the issue to you
• Don't ask for advice even before giving it a try and submitting a failing PR
• Maybe it's not a good issue for you, and you should simply move on

[Pranav2612000]

Hey @slorber I'll like to work on this. I've read the disclaimer and don't expect the PR to be assigned but just wanted to give up a heads up to prevent some one else from working on the same task.

( I'll try create a PR quickly, but if you don't see a message in the next 12 hours, feel free to pick this up )

[Pranav2612000]

I've been able to setup the project and am able to reproduce this issue. Will send a PR soon.

[Pranav2612000]

I've created a PR which fixes this. Feel free to take a look when you get time