feat(blog): slug/pathname aliases for blog posts

[johnnyreilly]

Pre-flight checklist

• I have read the Contributing Guidelines on pull requests.
• If this is a code change: I have written unit tests and/or added dogfooding pages to fully verify the new behavior.
• If this is a new API or substantial change: the PR has an accompanying issue (closes Can we deactivate /page/ functionality from blog functionality? #8311) and the maintainers have approved on my working plan.

Motivation

It would be great to have alias URLs for blog posts, so as well as /my-blog-post you could have /my-other-url-for-blog-post.

Ideally the canonical link remains pointing to the permalink. HOWEVER I'M NOT SURE HOW BEST TO IMPLEMENT THIS PART

Consider:

docusaurus/packages/docusaurus-theme-classic/src/theme/SiteMetadata/index.tsx

Lines 58 to 65 in ca3dba5

	// Default canonical url inferred from current page location pathname
	function useDefaultCanonicalUrl() {
	const {
	siteConfig: {url: siteUrl},
	} = useDocusaurusContext();
	const {pathname} = useLocation();
	return siteUrl + useBaseUrl(pathname);
	}

The canonical URL is driven just by the pathname of the page. There's not an obvious way to provide a canonical URL to this without serious code changes. Rather than do this unsupervised, I wanted to ask if there was an approach that might be good approach to take?

Test Plan

Please see the new tests / amended tests.

Test links

Deploy preview: https://deploy-preview-8356--docusaurus-2.netlify.app/

Related issues/PRs

#8311

[Josh-Cena]

IIUC, this would create two pages with the same content? Isn't it simpler to set up redirects instead?

[johnnyreilly]

Hey @Josh-Cena,

The context for this is in @slorber's comment here: #8311 (reply in thread)

---
slug: /2022/11/17/azure-ad-claims-static-web-apps-azure-functions
aliases: ["/"] # NEW FEATURE
---

# Azure AD Claims with Static Web Apps and Azure Functions

Text

The aliasing feature would create extra pages for another slug (that can be /)

It gives the ability to keep a shared canonical URL for both pages and avoid SEO content being flagged as duplicate.

Does this make sense?

[slorber]

yes that makes sense to me, and we'll likely want to add something similar to individual docs for consistency

[netlify]

✅ [V2]

Built without sensitive environment variables

Name	Link
🔨 Latest commit	ab1cf60
🔍 Latest deploy log	https://app.netlify.com/sites/docusaurus-2/deploys/6584653b2298f500087302ce
😎 Deploy Preview	https://deploy-preview-8356--docusaurus-2.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

⚡️ Lighthouse report for the deploy preview of this PR

URL	Performance	Accessibility	Best Practices	SEO	PWA	Report
/	🟠 73	🟢 98	🟢 100	🟢 100	🟠 89	Report
/docs/installation	🟠 68	🟢 98	🟢 100	🟢 100	🟠 89	Report
/docs/category/getting-started	🟠 76	🟢 100	🟢 100	🟢 90	🟠 89	Report
/blog	🟠 75	🟢 100	🟢 100	🟢 90	🟠 89	Report
/blog/preparing-your-site-for-docusaurus-v3	🟠 61	🟢 97	🟢 100	🟢 100	🟠 89	Report
/blog/tags/release	🟠 76	🟢 100	🟢 100	🟠 80	🟠 89	Report
/blog/tags	🟠 78	🟢 100	🟢 100	🟢 90	🟠 89	Report

[slorber]

Thanks, added some comments

We should rather have some dogfood cases to see it in action.

---

Note that we should also take care of the UI aspect.

For example, suppose the blog sidebar highlights the currently browsed blog post. In that case, it should probably keep being highlighted if we browse it from the permalink URL or any of the aliases. The theme code probably doesn't account for this yet. There are also things to consider like navbar items highlighting, although people rarely link to blog post URLs from the navbar and can use the regexp active fn.

---

An alternative implementation that is likely faster than rendering twice the same blog post could be to just copy the static file in the build output, inside the postBuild hook?

cp build/blog/folder/myBlogPost.html build/blog/another-folder/myBlogPostAlias.html

Pro: much faster if there are many aliases (unlikely? 🤔 )
Cons: worst DX, aliases not working in dev unless we implement something. A Hybrid solution could also make sense.

We can probably think about perf later, and current implementation is likely good enough.

[slorber]

I'm not sure we should accept such value 😅

This code is unlikely to yield a great pathname

normalizeUrl([baseUrl, routeBasePath, alias])

and the tests do not cover these edge cases.

---

The question to me is: do we want to support relative aliases?

Is this really useful? I mean, you create a relative alias, then update the slug, and then you end up with a different alias. That might be a source of bug/confusion?

If we do want relative aliases, there's a resolvePathname util that could probably be applied to compute the final non-relative pathname of the alias.

But I would suggest to keep it simple for now and only accept absolute pathname aliases in validation? If someone wants a relative alias someday and has great reason to add it, we'll do an update.

[johnnyreilly]

The question to me is: do we want to support relative aliases?

Probably not - will amend

[slorber]

yes that makes sense to me, and we'll likely want to add something similar to individual docs for consistency

[johnnyreilly]

Thanks for the comments - I'll take a look at them. But before doing I wanted to get your thoughts on the below: (copied from the motivation section up top). Given that this will likely change implementation somewhat, I wanted to tackle that before the code comments. Hope this makes sense!

Motivation

It would be great to have alias URLs for blog posts, so as well as /my-blog-post you could have /my-other-url-for-blog-post.

Ideally the canonical link remains pointing to the permalink. HOWEVER I'M NOT SURE HOW BEST TO IMPLEMENT THIS PART

Consider:

docusaurus/packages/docusaurus-theme-classic/src/theme/SiteMetadata/index.tsx

Lines 58 to 65 in ca3dba5

	// Default canonical url inferred from current page location pathname
	function useDefaultCanonicalUrl() {
	const {
	siteConfig: {url: siteUrl},
	} = useDocusaurusContext();
	const {pathname} = useLocation();
	return siteUrl + useBaseUrl(pathname);
	}

The canonical URL is driven just by the pathname of the page. There's not an obvious way to provide a canonical URL to this without serious code changes. Rather than do this unsupervised, I wanted to ask if there was an approach that might be good approach to take?

[slorber]

I guess this logic should only be used for as a fallback for pages that do not define an explicit canonical URL (which is likely the case for user-created standalone pages)

If a content-plugin supports the aliasing feature then it probably needs to declare the canonical url deeper in the tree, to override this fallback value.

That probably makes sense to add it to the PageMetadata helper considering it sets 2 meta at once and could be reused in the future

It is ok to declare the same meta multiple times in the tree, Head is supposed to deduplicate it.