Allow configuration of `cleanUrls` option for `serve` command

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

Allow configuration of the cleanUrls option passed to serve-handler package when running docusaurus serve.

Currently, Docusaurus sets the cleanUrls option for the serve-hander package to true and it isn’t configurable by the user. https://github.com/facebook/docusaurus/blob/bd9f29a4698963d3b139f7419877a300640b09ff/packages/docusaurus/src/commands/serve.ts#L76-L82

Proposing that this should be a user-configurable option.

Has this been requested on Canny?

No response

Motivation

By default, at least a few major hosting providers (GH Pages, Netlify, Vercel) don’t enable this ‘feature’. Having this as an option would allow for more accurate testing of the documentation website before deploying.

A Use Case: It is possible to embed an iframe into a documentation page which serves as a self-contained example. The example file can be loaded using the file-loader web pack loader.

<iframe
     src={require('!!file-loader!./assets/example.html').default}
 ></iframe>
 <a href={require('!!file-loader!./assets/example.html').default} target="\_blank">
     View example in a new window
 </a>

This works correctly when using docusaurus start and when deploying the build onto a hosting provider. However, when running docusaurus serve, any url ending with .html is rewritten without the extension and a 404 error occurs.

API design

ServeCLIOptions could include cleanUrls?: boolean; which defaults to true. https://github.com/facebook/docusaurus/blob/bd9f29a4698963d3b139f7419877a300640b09ff/packages/docusaurus/src/commands/serve.ts#L20-L25

When the user wishes to disable cleanUrls then they would call the serve command as follows: docusaurus serve --no-clean-urls

A similar options could be added to the configuration file (https://github.com/facebook/docusaurus/blob/bd9f29a4698963d3b139f7419877a300640b09ff/packages/docusaurus-types/src/config.d.ts).

Have you tried building it?

I’ve tried the changes locally and passing cleanUrls: false to serve-handler works as expected.

Self-service

• I’d be willing to contribute this feature to Docusaurus myself.

[SlicedSilver]

Within serve.ts, if I set cleanUrls: false then it works as expected.

However, if I remove the http 302 ‘found’ redirect logic then it works as well (without changing the cleanUrls):

    // if (!req.url?.startsWith(baseUrl)) {
    //   res.writeHead(302, {
    //    Location: baseUrl,
    //  });
    //  res.end();
    //  return;
    // }

Changing the Location value within the redirect also works (without changing the cleanUrls):

Location: baseUrl + req.url.slice(1),

If changing the location value is the best option then obviously it might make sense to check if baseUrl ends with / and url starts with / if that is quietly allowed within the configuration.

const slicePoint = (baseUrl.endsWith('/') && req.url.startsWith('/')) ? 1 : 0;
// ...
Location: baseUrl + req.url.slice(slicePoint),

@slorber Hope this helps, and thanks for your assistance.

[SlicedSilver]

I’ve created a stackbiltz example where the site functions correctly on npm run start, but not when running npm run serve.

https://stackblitz.com/edit/github-sifwoz?file=docusaurus.config.js

It appears that this behaviour only occurs when baseUrl is changed from the default of '/'.

---

The example:

• Click ‘View Example’ on the landing page of the documentation site.
• When run with start then you will see a light blue iframe
• When run with serve then you will see the landing page within the iframe.