Auto fill HTML Anchor (IDs)

[JeroenSormani]

Feature request/suggestion

In #1734 (#2394 PR) the ability to configure the HTML Anchor of a heading was added. I'd propose to auto-fill this value so users don't have to manually configure these. I think only auto-filling them, but still allowing edits would be preferable.

[noisysocks]

There was some previous discussion about something similar in #2394 (comment). It looks like there was some consensus but that we decided to punt on it.

I'm into the idea. My only reservation is that we'd have to figure out a way to avoid duplicate IDs from being accidentally inserted into the page.

cc. @mtias @youknowriad @jasmussen

[pento]

This would help for #1760, too.

[jasmussen]

No strong opinion against it, and it seems like a valid use case. We just want to think through the edgecases and complexity it might bring. Do we look to make sure a user doesn't use the same ID twice? What if an auto-ID conflicts with an existing ID used in the HTML code?

If we only suggest an ID to auto-fill, does it really add any value compared to doing nothing at all? Could we do with a button that says something like "Copy heading" or something?

[pento]

Prefixing the IDs with the post slug would make it reasonably unique, particularly if the pattern is continued into the customisation focus. (Sidebars could be prefixed with the sidebar slug, etc.)

Also, we'd want to only auto-fill it once, then the author can modify it if they need to.

[heyakyra]

I would love this. Requiring converting the block into custom HTML is not a nice experience towards this end. A duplicate checker shouldn't be too hard, and a default ID setting of a slug of the header text (plus a number if there are multiple with the same text) hopefully isn't too complex to implement

[LukaszJaro]

This would be great, I'm trying to implement something like this now but also with the ability to copy the anchor for sharing using clipboard.js

First step is getting headings to auto-generate an ID, right now my solution would be using PHP preg functions.

I thought of extending the gutenberg blocks, anchor attribute, to auto-fill with the heading title, but my skill level isn't there yet to make those kind of customizations.

For the duplicate ID issue, you can handle it like WordPress does with Permalinks by appending a sequenced number to the end of the ID, i.e., id="page", id="page-2"

Another option could require user intervention, a warning that there is duplicate ID's present with fix suggestions?

[seantjohnson-dev]

Is this feature making any movement? I personally would love this feature. I have a pattern of building pages using 'sections' at the top level of the page blocks which then use innerBlocks to customize the layout/look of the section content. The ability to generate a unique ID for these top-level block anchors would be a great convenience. I often need to build a navigation of some sort that has scroll link anchors somewhere on the site and I can't count on the client to remember to input an ID for each section, not to mention making it unique across the whole page.

[LukaszJaro]

Will mention this issue in the weekly editor slack meeting..

[mahnunchik]

@LukaszJaro @ZebulanStanphill It may be helpful for Table of Contents #21234

[LukaszJaro]

@mahnunchik, that is my current use case, need it for table of contents. Would be a very nice addition to have a core table of contents block with pre-filled anchors.

Also the heading level checker #22650 is a good idea, would be useful for something similar for anchors, check if duplicate anchor is present.

[mahnunchik]

It is pretty awesome! I'm looking forward to have it merged 😃

[mtias]

Happy to move this forward, but the details need to be figured out: how to name the ids to avoid issues with duplicates; handling updating the content of a heading, which is tricky, because it could break existing links, etc.

[getdave]

how to name the ids to avoid issues with duplicates

To avoid duplicate IDs due to x2 Heading blocks with the same text, could we check the document for these duplicates and if found then append an integer to the end of the duplicates' anchor? eg: my-heading, my-heading-1, my-heading-2...etc

handling updating the content of a heading

I'd say we mirror the permalink behaviour for Posts, which I believe is to leave the reference intact when the title changes. We could apply the same for Heading anchors because as you say to do otherwise could break existing hyperlinks out there in the wild.

[chrisvanpatten]

Might also be worth looking at how GitHub handles this, as they auto-link headers in readmes.

[LukaszJaro]

Here's a update from the slack discussion, basically it's very complicated!

Zeb:That seems like a feature for the Heading block, not the Table of Contents block. Auto-adding anchors to other blocks from another block would be a bit of a weird behavior. (In fact, an earlier implementation of the Table of Contents block did just this, but it caused all sorts of issues with undo/redo.)

Zeb:computer: 10:29 AM
How do we go about counting things like headings and nextpage tags that aren’t in blocks? And how do we figure out how many of those precede the current block? Solving this is essential to completing the Table of Contents block and fixing edge-cases with the heading level checker I’m trying to add as well as the existing content structure tool in the top toolbar.
10:30
Counting Heading blocks is relatively easy, but counting all headings in the HTML is more difficult, and counting all headings in the HTML preceding the current block seems almost impossible in some situations.
10:30
It also seems really HTML-specific, which is concerning.

youknowriad 10:31 AM
I don’t think it’s easy, what if the headings are in a dynamic block. I wonder if we should not support this personally

Zeb:computer: 10:31 AM
Should we only support Heading blocks? What about 3rd-party heading blocks?
10:32
Should there be some kind of generic "headings" API for blocks to hook into that is abstracted away from HTML or something?

youknowriad 10:32 AM
I think we should start with Core heading blocks, 3rd-party heading support is an interesting case and it would require a dedicated block API but I’d rather start with just the heading blocks personally

matias 10:32 AM
Probably only support core heading blocks and allow third-parties to opt-in to outline

Zeb:computer: 10:33 AM
But how exactly do you add support for 3rd-party blocks to the Table of Contents block?

michaelarestad:yolo: 10:34 AM
I think we can likely work the details of implementation out in a PR/issue. I do think table of content functionality (and heading IDs) is something we should absolutely work on.

Zeb:computer: 10:35 AM
Well, as posted above, I have a Table of Contents block PR. It's just been stuck for a month on that exact issue.

matias 10:35 AM
Something like allowing a block to declare one of its attributes as contributing to the outline of a document and abstracting away outline / table of contents in a getOutline rather than just getting core/heading

[ZebulanStanphill]

The Table of Contents block ended up being merged without any dedicated headings API.

It seems the obvious next step is to implement automatic id generation at the Heading block. Here's my suggestion for how it should work:

• The "HTML anchor" input should be renamed to "Custom HTML anchor".
• Upon insertion, a Heading block should automatically set its anchor attribute to an id in the following format: wp-block-heading-{id}, where {id} is a randomly generated string of alphanumeric characters.
• The user can view this id in the "HTML anchor" input, and can replace it with their own. If the user empties the field, it will remain empty and the block will have no anchor.
• The user can press a Generate id button to fill the field with a new auto-generated id.

How does this sound? Once we determine how this feature should behave, it shouldn't be difficult to implement in a PR.

[mahnunchik]

I've some ideas about generated anchor. If we use text from the header itself when it would be more user friendly to have awesome-header-123 instead of wp-block-heading-123.

I know and use in my project the slug module: https://github.com/Trott/slug

It allows to slugify not only latin strings but cyrillic, arabian or even emoji. In this case I will not use "Custom HTML anchor" at all because almost all anchors will be human understandable.

[AbhijitNage123]

I think we should fetch heading in run time in the backend as well as front-end if we don't want to fetch only core headings.

We can search heading present on page using $( 'div.entry-content' ).find('h1, h2, h3, h4, h5, h6' ) for front-end.

And then we can auto-generated HTML anchor (generated from the heading ) like this

var TOC = '';

let header_array = $( 'div.entry-content' ).find('h1, h2, h3, h4, h5, h6' )

header_array.each( function (index,value){

			let header = $( this );

                            let header_text = parseTocSlug(header.text()) //create anchar for toc.

                            let titleText = header.text();

            TOC += "<li><a href='#" + header_text + "'>" + titleText + "</a></li>"

});

Like this.

[mtias]

Closing in favor of #29561 which is more up to date and has an attached pull request.