feat(v2): add trailingSlash config option #4908

slorber · 2021-06-04T18:05:47Z

Motivation

After analyzing the behavior of multiple static hosting providers (see https://github.com/slorber/trailing-slash-guide), I think we should have a trailingSlash option (like Next.js has)

This is a risky change that can have deep SEO impacts for some sites, so we are keeping a retrocompatible behavior by default.

It would allow 3 values:

true: force a trailing slash to SPA routes + links, output /myPath/index.html
false: remove trailing slashes on SPA routes + links, output /myPath.html
undefined: retrocompatible behavior: leave routes unchanged (often no trailing slash), output /myPath/index.html

If the new behaviors are successful, we should add them to the init template, and deprecate the undefined legacy behavior with a Joi warning, telling the users to be extra careful about the potential SEO impacts.

Have you read the Contributing Guidelines on pull requests?

yes

Test Plan

Tests + deploy previews

I'm implementing a new {trailingSlash: boolean | undefined} config.

undefined: it keeps the existing retro-compatible behavior (paths not modified), and output /path/index.html
false: remove a potential trailing slash on routes, links, canonical URLs, and output /path.html
true: force a trailing slash on routes, links, canonical URLs, and output /path/index.html

Refer to https://github.com/slorber/trailing-slash-guide for how the files will be served by your host.

I've created 3 deployments to test this feature:

trailingSlash undefined: https://docusaurus-trailing-slash-undefined.netlify.app/ (Netlify pretty URLs off)
trailingSlash false: https://docusaurus-trailing-slash-false.netlify.app/ (Netlify pretty URLs on)
trailingSlash true: https://docusaurus-trailing-slash-true.netlify.app/ (Netlify pretty URLs on)

Note: using true/false instead of undefined allows to use Netlify with pretty URLs on without having any annoying redirection, but it's not the case for the undefined behavior that will keep redirecting with pretty URLs on (default behavior). Had to disable this.

PLEASE: help me review those deployments and let me know if you see any unwanted side-effects: now is a better time to complain than after merging the PR :)

Note: this feature is generic and in core, to avoid the need to have each plugin implement custom trailingSlash logic. In some cases it might require some plugin tweaks but it should work fine in a generic way for plugin authors in most cases.

netlify · 2021-06-04T18:10:13Z

✔️ [V1]

🔨 Explore the source changes: c17235f

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-1/deploys/60c0fe24933cf8000703b391

😎 Browse the preview: https://deploy-preview-4908--docusaurus-1.netlify.app

…-generator-webpack-plugin

github-actions · 2021-06-08T15:59:17Z

Size Change: 0 B

Total Size: 620 kB

ℹ️ View Unchanged

Filename	Size	Change
`website/build/assets/css/styles.********.css`	87.7 kB	0 B
`website/build/assets/js/main.********.js`	443 kB	0 B
`website/build/blog/2017/12/14/introducing-docusaurus/index.html`	62.1 kB	0 B
`website/build/docs/introduction/index.html`	235 B	0 B
`website/build/index.html`	27 kB	0 B

_{compressed-size-action}

…reliable

netlify · 2021-06-08T16:46:57Z

✔️ [V2]

🔨 Explore the source changes: c17235f

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/60c0fe2470bcda0008648986

😎 Browse the preview: https://deploy-preview-4908--docusaurus-2.netlify.app

github-actions · 2021-06-08T16:47:18Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟠 Performance	58
🟢 Accessibility	97
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-4908--docusaurus-2.netlify.app/

thehappybug · 2021-06-09T12:29:19Z

trailingSlash false: docusaurus-trailing-slash-false.netlify.app (Netlify pretty URLs on)

@slorber The docs page is missing the navigation on the left. I can't tell if this is intentional or a bug introduced in this PR.

See page https://docusaurus-trailing-slash-false.netlify.app/docs.

trailingSlash true: docusaurus-trailing-slash-true.netlify.app (Netlify pretty URLs on)

This has the right behavior for me based on my requirements in #3372 (comment).

I see that the URLs in the pages, in the canonical meta tag, the sitemap, and the browser bar are all matching and contain trailing slashes. And Netlify's Pretty URL redirects users correctly.

I will now wait for the canary build to test this on my site.

slorber · 2021-06-09T13:59:43Z

@slorber The docs page is missing the navigation on the left. I can't tell if this is intentional or a bug introduced in this PR.

Thanks, definitively not intentional but understand why it happens, due to using slug: "/". Other docs work fine see https://docusaurus-trailing-slash-false.netlify.app/docs/installation
Will fix this asap.

thehappybug · 2021-06-15T05:12:08Z

I wasn't able to get my site working with the current canary release. I get build errors and I'm not sure what the cause is.

Yarn install output

PS D:\Repositories\Documentation\apimatic-docs> yarn upgrade @docusaurus/core@canary  @docusaurus/preset-classic@canary
yarn upgrade v1.22.10
[1/4] Resolving packages...
[2/4] Fetching packages...
info fsevents@2.3.2: The platform "win32" is incompatible with this module.
info "fsevents@2.3.2" is an optional dependency and failed compatibility check. Excluding it from installation.
info fsevents@1.2.13: The platform "win32" is incompatible with this module.
info "fsevents@1.2.13" is an optional dependency and failed compatibility check. Excluding it from installation.
[3/4] Linking dependencies...
warning "@docusaurus/preset-classic > @docusaurus/theme-search-algolia > @docsearch/react@3.0.0-alpha.36" has unmet peer dependency "@types/react@>= 16.8.0 < 18.0.0".
y "@algolia/client-search@^4.5.1".
[4/4] Rebuilding all packages...
success Saved lockfile.
success Saved 8 new dependencies.
info Direct dependencies
└─ @docusaurus/preset-classic@2.0.0-beta.aff848e87
info All dependencies
├─ @docusaurus/cssnano-preset@2.0.0-beta.aff848e87
├─ @docusaurus/plugin-debug@2.0.0-beta.aff848e87
├─ @docusaurus/plugin-google-analytics@2.0.0-beta.aff848e87
├─ @docusaurus/plugin-google-gtag@2.0.0-beta.aff848e87
├─ @docusaurus/plugin-sitemap@2.0.0-beta.aff848e87
├─ @docusaurus/preset-classic@2.0.0-beta.aff848e87
├─ @docusaurus/theme-classic@2.0.0-beta.aff848e87
└─ @docusaurus/theme-search-algolia@2.0.0-beta.aff848e87
Done in 61.44s.

Build output (has error)

Unable to build website for locale en.
RangeError: Invalid time value
    at D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\plugin-content-blog\lib\blogUtils.js:118:12
    at async Promise.all (index 16)
    at async Object.generateBlogPosts (D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\plugin-content-blog\lib\blogUtils.js:84:5)
    at async Object.loadContent (D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\plugin-content-blog\lib\index.js:59:25)
    at async D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\core\lib\server\plugins\index.js:54:46
    at async Promise.all (index 6)
    at async Object.loadPlugins (D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\core\lib\server\plugins\index.js:53:34)
    at async Object.load (D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\core\lib\server\index.js:102:82)
    at async buildLocale (D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\core\lib\commands\build.js:80:19)
    at async tryToBuildLocale (D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\core\lib\commands\build.js:32:20)
    at async Object.mapAsyncSequencial (D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\utils\lib\index.js:328:24)
    at async build (D:\Repositories\Documentation\apimatic-docs\node_modules\@docusaurus\core\lib\commands\build.js:68:25)
error Command failed with exit code 1.

Let me know if this is something that will go away with the next beta release. If this feels like a bug, let me know how I can debug it to help avoid this going to release.

slorber · 2021-06-15T09:29:14Z

@thehappybug this does not look related to trailing slashes. From which version are you upgrading? May be related to refactor in #4759

It looks like we can't compute a proper date for some of your blog posts using this code:

      date = date ?? (await fs.stat(source)).birthtime;
      const formattedDate = new Intl.DateTimeFormat(i18n.currentLocale, {
        day: 'numeric',
        month: 'long',
        year: 'numeric',
      }).format(date);

Can you give me an idea of your blog post filenames + their frontmatter please? Do you see any post with a potentially wrong date filename pattern or frontmatter?

As this is unrelated, I'd appreciate if you open a new issue instead of commenting this PR

Labirintami · 2021-06-17T11:21:26Z

Hello, is this update included in the latest public builds?

thehappybug · 2021-06-17T16:52:07Z

@Labirintami It is only available on canary right now.

See: #3372 (comment)

slorber · 2021-06-17T17:21:49Z

will be in beta.1, probably tomorrow

I've written how to use a Canary release here: https://docusaurus.io/community/canary

POC: add trailingSlash option

fd22f8e

slorber added the pr: new feature This PR adds a new API or behavior. label Jun 4, 2021

slorber requested a review from lex111 as a code owner June 4, 2021 18:05

facebook-github-bot added the CLA Signed Signed Facebook CLA label Jun 4, 2021

slorber mentioned this pull request Jun 4, 2021

Fix trailing slash issues (depend on hosting provider) #3372

Closed

slorber marked this pull request as draft June 4, 2021 18:07

integrate the preferFoldersOutput option of fork @slorber/static-site…

2907a0d

…-generator-webpack-plugin

slorber added 2 commits June 8, 2021 18:31

Fix broken links when using trailing slash => using md links is more …

73e585b

…reliable

fix TS issue

2f8627d

slorber added 6 commits June 8, 2021 18:58

minor polish

bcce4cb

fix doc page being sensitive to trailing slashes

7e2af27

Add tests for applyTrailingSlash

8cc6cad

rename test files

0b83e8a

extract and test applyRouteTrailingSlash

f829163

update snapshot

e50ebc2

slorber marked this pull request as ready for review June 8, 2021 18:02

slorber added 5 commits June 9, 2021 17:13

Merge branch 'master' into slorber/trailingSlash-config

e19ff2c

add trailing slash config to serve command

70a4261

fix getSidebar() => still sensitive to trailing slash setting

85cf36f

never apply trailing slash to an anchor link

f26d14c

Add documentation for trailingSlash setting

c17235f

slorber merged commit df8a900 into master Jun 9, 2021

This was referenced Jun 10, 2021

Link Component with or without useBaseUrl #2832

Closed

fix(v2): sitemap plugin should handle siteConfig.trailingSlash automatically #4950

Merged

slorber mentioned this pull request Jun 21, 2021

Links to other docs pages are broken in github pages due to additional / #5026

Closed

5 tasks

slorber deleted the slorber/trailingSlash-config branch August 17, 2021 17:49

rdlrt mentioned this pull request Sep 22, 2021

fix broken faucet link cardano-foundation/developer-portal#312

Merged

IanVS mentioned this pull request Dec 12, 2022

Use trailing slashes in links DefinedNet/nebula-docs#79

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): add trailingSlash config option #4908

feat(v2): add trailingSlash config option #4908

slorber commented Jun 4, 2021 •

edited

netlify bot commented Jun 4, 2021 •

edited

github-actions bot commented Jun 8, 2021 •

edited

netlify bot commented Jun 8, 2021 •

edited

github-actions bot commented Jun 8, 2021 •

edited

thehappybug commented Jun 9, 2021

slorber commented Jun 9, 2021

thehappybug commented Jun 15, 2021

slorber commented Jun 15, 2021 •

edited

Labirintami commented Jun 17, 2021

thehappybug commented Jun 17, 2021

slorber commented Jun 17, 2021

feat(v2): add trailingSlash config option #4908

feat(v2): add trailingSlash config option #4908

Conversation

slorber commented Jun 4, 2021 • edited

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

netlify bot commented Jun 4, 2021 • edited

github-actions bot commented Jun 8, 2021 • edited

netlify bot commented Jun 8, 2021 • edited

github-actions bot commented Jun 8, 2021 • edited

thehappybug commented Jun 9, 2021

slorber commented Jun 9, 2021

thehappybug commented Jun 15, 2021

slorber commented Jun 15, 2021 • edited

Labirintami commented Jun 17, 2021

thehappybug commented Jun 17, 2021

slorber commented Jun 17, 2021

slorber commented Jun 4, 2021 •

edited

netlify bot commented Jun 4, 2021 •

edited

github-actions bot commented Jun 8, 2021 •

edited

netlify bot commented Jun 8, 2021 •

edited

github-actions bot commented Jun 8, 2021 •

edited

slorber commented Jun 15, 2021 •

edited