feat(v2): add ability to set custom heading id #4222

lex111 · 2021-02-13T01:25:16Z

Motivation

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

Tests and preview https://deploy-preview-4222--docusaurus-2.netlify.app/classic/examples/markdownPageExample#custom

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

netlify · 2021-02-13T01:30:30Z

[V1] Deploy preview success

Built with commit c8baed6

https://deploy-preview-4222--docusaurus-1.netlify.app

github-actions · 2021-02-13T01:33:14Z

Size Change: +543 B (0%)

Total Size: 533 kB

Filename	Size	Change
`website/build/assets/css/styles.********.css`	87.4 kB	+51 B (0%)
`website/build/assets/js/main.********.js`	359 kB	+492 B (0%)

ℹ️ View Unchanged

Filename	Size	Change
`website/build/blog/2017/12/14/introducing-docusaurus/index.html`	60.3 kB	0 B
`website/build/docs/introduction/index.html`	235 B	0 B
`website/build/index.html`	25.4 kB	0 B

_{compressed-size-action}

netlify · 2021-02-13T01:33:52Z

Deploy preview for docusaurus-2 ready!

Built with commit c8baed6

https://deploy-preview-4222--docusaurus-2.netlify.app

github-actions · 2021-02-13T01:34:02Z

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	92
🟢 Accessibility	96
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

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

netlify · 2021-02-13T01:36:05Z

[V1] Deploy preview success

Built with commit 728d262

https://deploy-preview-4222--docusaurus-1.netlify.app

netlify · 2021-02-13T01:43:07Z

Deploy preview for docusaurus-2 ready!

Built with commit 728d262

https://deploy-preview-4222--docusaurus-2.netlify.app

lex111 · 2021-02-13T01:45:49Z

packages/docusaurus-mdx-loader/src/remark/headings/index.js

+        // Support explicit heading IDs
+        const customHeadingIdMatches = customHeadingIdRegex.exec(heading);
+
+        if (customHeadingIdMatches) {


Curious if this feature will have to be configurable? How much of an impact on performance would it have if it were always enabled by default? Or does it make sense to create a separate plugin for this feature? For now I have combined it into the existing slug plugin because they essentially do the same thing (create headings id).

I think it's fine to enable by default and put in mdx loader.
We likely want to encourage users to have stable anchor ids and this should work consistently for docs, blog and pages.

I just thought that having new plugin might be better for this. Since this feature is mainly needed when using the i18n. Moreover, I think to add a cli command to automatically create explicit ids for existing headers (we have extendCli hook in plugin lifecycle). Because currently I do not understand how I can add a new cli command inside the mdx-loader package. WDYT?

Having a way to "lock" the ids at a given time looks like a nice idea.

Not sure how to build that easily, how would the plugin know where to look for markdown files, as the paths are provided as options to the docs, blog, page plugin?

The only thing I'm thinking of is having this cli in core, and getting all the relevant paths from getPathsToWatch (as you basically watch the md files, it will work but feel a bit hacky at the same time)

Since this feature is mainly needed when using the i18n.

I think it's actually useful in all cases. If you want to link to some heading, we'd rather ensure that link does not break when the heading is updated.

Fixing heading ids you want to link to should rather be the norm, and we could even add a warning someday to tell the user that he's linking to an anchor that has not been fixed?

Currently it's too easy to have broken anchor links in a Docusaurus site.

I lost sight of that it is currently not possible to add new Remark plugin from the custom Docusaurus plugin. Maybe we should create new hook for this purpose?

I decided to add new command to write heading ids to the docusaurus core (eg. yarn docusaurus write-heading-ids community). Its implementation is very simple, so it might be worth improving it.

slorber

Thanks for working on this, that will be really useful for i18n!

slorber · 2021-02-15T18:30:03Z

packages/docusaurus-mdx-loader/src/remark/headings/index.js


 const visit = require('unist-util-visit');
 const toString = require('mdast-util-to-string');
 const slugs = require('github-slugger')();

+const customHeadingIdRegex = /^(.*?)\s*\{#([\w-]+)\}$/;


What about extracting customHeadingIdRegex.exec(heading); in a separate function const {heading,id} = extractHeadingId(rawHeading) and adding tests?

That would simplify the testing of Regepx edge cases.

Hmm, but we have separate test that with different cases, so it seems to me redundant extract new function (and its test), because in many ways it will duplicate this test.

slorber · 2021-02-15T18:41:59Z

packages/docusaurus-mdx-loader/src/remark/headings/index.js

+        // Support explicit heading IDs
+        const customHeadingIdMatches = customHeadingIdRegex.exec(heading);
+
+        if (customHeadingIdMatches) {


I think it's fine to enable by default and put in mdx loader.
We likely want to encourage users to have stable anchor ids and this should work consistently for docs, blog and pages.

slorber · 2021-02-15T18:45:08Z

website/docs/guides/docs/docs-create-doc.mdx

+
+### Custom id headers {#custom-id}
+
+With `{#custom-id}` syntax you can set your own header id.


Probably worth creating a page dedicated to anchor links in markdown features category?

I'd also document this in the i18n section but I can do it in another PR?

…act/useless

krillboi · 2021-03-10T12:12:17Z

@slorber I just tried this out by calling ./yarn --cwd ../../../documentation/docusaurus-site docusaurus write-heading-ids but nothing seems to happen and I just get a 0 markdown files already have explicit heading ids message. Am I using this incorrectly?

slorber · 2021-03-10T12:43:52Z

@krillboi can you try on the doc site folder directly instead of using --cwd ?
Are you using Yarn2?

krillboi · 2021-03-10T12:46:49Z

@slorber I can try that. I am currently using yarn v1.22.10.

krillboi · 2021-03-10T13:25:00Z

@slorber I tried this instead, executed from the site directory: ../../support/3rdparty/nodejs12140/yarn docusaurus write-heading-ids and it still does not work.

slorber · 2021-03-10T14:17:54Z

😅 I mean can you try cding into the directory and just running yarn docusaurus write-heading-ids ?

What's your site repo? a branch to inspect?

krillboi · 2021-03-10T14:40:30Z

@slorber I don't have a global installation of node. Haven't had trouble with using --cwd until now for all the other docusaurus commands like write-translations, start, build etc. I don't have a public repo I'm afraid 😅

If I write some invalid path to siteDir like: ../../support/3rdparty/nodejs12140/yarn docusaurus write-heading-ids ../ I correctly get a Error: Config file "c:\git\touchgfx.git\documentation\docusaurus.config.js" not found error, but the other command seems to find the config file fine, but does not do anything to my .mdx files:

cd documentation/docusaurus-site
../../support/3rdparty/nodejs12140/yarn docusaurus write-heading-ids
yarn run v1.22.10
$ c:\git\touchgfx.git\documentation\docusaurus-site\node_modules\.bin\docusaurus write-heading-ids
0 markdown files already have explicit heading ids
Done in 3.81s.

Is it recommended to upgrade to yarn 2?

krillboi · 2021-03-10T15:25:46Z

So I've tried logging the output of the command and

docusaurus/packages/docusaurus/src/commands/writeHeadingIds.ts

Line 110 in b7a6665

const markdownFiles = await globby(await getPathsToWatch(siteDir), {

returns an empty array, so it isn't finding my .mdx files. I'll investigate further.

krillboi · 2021-03-10T16:16:44Z

Still haven't fixed it but have a suspicion that it has something to do with: sindresorhus/globby#155

krillboi · 2021-03-10T16:59:31Z

@slorber So replacing the globby call with the following has worked for me (taking inspiration from some of your other functions):

    const markdownFiles = await globby_1.default.sync(['**/*.{md,mdx}'], {
        cwd: siteDir,
    });

It's not perfect as, for example, all the README.md files in node_modules are hit which I can see is what getPathsToWatch is trying to prevent. So I am not entirely sure what is going on, but probably Windows+globby related.

slorber · 2021-03-10T19:11:50Z

Oh, I see you are on windows, that definitively look like the reason :)

thanks for reporting

slorber · 2021-03-16T19:02:56Z

@krillboi should be fixed by #4444

Please test this on @canary release soon and let me know if it works

lex111 added the pr: new feature This PR adds a new API or behavior. label Feb 13, 2021

lex111 requested a review from slorber as a code owner February 13, 2021 01:25

facebook-github-bot added the CLA Signed Signed Facebook CLA label Feb 13, 2021

lex111 force-pushed the lex111/custom-heading-ids branch from c8baed6 to 477f43d Compare February 13, 2021 01:29

feat(v2): add ability to set custom heading id

5b6a4dc

lex111 force-pushed the lex111/custom-heading-ids branch from 477f43d to 5b6a4dc Compare February 13, 2021 01:43

lex111 commented Feb 13, 2021

View reviewed changes

slorber reviewed Feb 15, 2021

View reviewed changes

lex111 mentioned this pull request Feb 27, 2021

feat(v2): allow specifying max depth for TOC #4310

Closed

lex111 and others added 14 commits March 5, 2021 14:33

Merge remote-tracking branch 'origin' into lex111/custom-heading-ids

0e33167

Add cli command

fc13227

Fix slugger

c7a6a8e

write-heading-ids doc + add in commands/templates

3f75cf3

refactor + add tests for writeHeadingIds

d8493df

polish writeHeadingIds

07f0d03

polish writeHeadingIds

bb3eb06

remove i18n goals todo section as the remaining items are quite abstr…

d0a09af

…act/useless

fix edge case with 2 md links in heading

216696d

extract parseMarkdownHeadingId helper function

0d575de

refactor using the shared parseMarkdownHeadingId utility fn

c3ee525

change logic of edge case

870628f

Handle edge case

c69a45f

Document explicit ids feature

728d262

slorber merged commit 96e7fce into master Mar 5, 2021

dependabot bot mentioned this pull request Mar 10, 2021

Bump @docusaurus/preset-classic from 2.0.0-alpha.63 to 2.0.0-alpha.71 austinmroczek/developers.home-assistant#15

Closed

slorber mentioned this pull request Mar 16, 2021

fix(v2): Fix writeHeadingIds on Windows due to non-posix paths #4444

Merged

slorber deleted the lex111/custom-heading-ids branch August 17, 2021 17:50

fisker mentioned this pull request Sep 29, 2022

Add link id to changelog entry prettier/prettier#13549

Draft

4 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(v2): add ability to set custom heading id #4222

feat(v2): add ability to set custom heading id #4222

lex111 commented Feb 13, 2021 •

edited

netlify bot commented Feb 13, 2021

github-actions bot commented Feb 13, 2021 •

edited

netlify bot commented Feb 13, 2021

github-actions bot commented Feb 13, 2021 •

edited

netlify bot commented Feb 13, 2021 •

edited

netlify bot commented Feb 13, 2021 •

edited

lex111 Feb 13, 2021 •

edited

slorber Feb 15, 2021

lex111 Feb 15, 2021

slorber Feb 16, 2021

slorber Feb 16, 2021

lex111 Feb 16, 2021

lex111 Mar 5, 2021

slorber left a comment

slorber Feb 15, 2021

lex111 Mar 5, 2021

slorber Feb 15, 2021

slorber Feb 15, 2021

krillboi commented Mar 10, 2021

slorber commented Mar 10, 2021

krillboi commented Mar 10, 2021

krillboi commented Mar 10, 2021

slorber commented Mar 10, 2021

krillboi commented Mar 10, 2021 •

edited

krillboi commented Mar 10, 2021 •

edited

krillboi commented Mar 10, 2021

krillboi commented Mar 10, 2021

slorber commented Mar 10, 2021

slorber commented Mar 16, 2021


		### Custom id headers {#custom-id}

		With `{#custom-id}` syntax you can set your own header id.

feat(v2): add ability to set custom heading id #4222

feat(v2): add ability to set custom heading id #4222

Conversation

lex111 commented Feb 13, 2021 • edited

Motivation

Have you read the Contributing Guidelines on pull requests?

Test Plan

Related PRs

netlify bot commented Feb 13, 2021

github-actions bot commented Feb 13, 2021 • edited

netlify bot commented Feb 13, 2021

github-actions bot commented Feb 13, 2021 • edited

netlify bot commented Feb 13, 2021 • edited

netlify bot commented Feb 13, 2021 • edited

lex111 Feb 13, 2021 • edited

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

slorber left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

krillboi commented Mar 10, 2021

slorber commented Mar 10, 2021

krillboi commented Mar 10, 2021

krillboi commented Mar 10, 2021

slorber commented Mar 10, 2021

krillboi commented Mar 10, 2021 • edited

krillboi commented Mar 10, 2021 • edited

krillboi commented Mar 10, 2021

krillboi commented Mar 10, 2021

slorber commented Mar 10, 2021

slorber commented Mar 16, 2021

lex111 commented Feb 13, 2021 •

edited

github-actions bot commented Feb 13, 2021 •

edited

github-actions bot commented Feb 13, 2021 •

edited

netlify bot commented Feb 13, 2021 •

edited

netlify bot commented Feb 13, 2021 •

edited

lex111 Feb 13, 2021 •

edited

krillboi commented Mar 10, 2021 •

edited

krillboi commented Mar 10, 2021 •

edited