32 Comments

  1. Joost de Valk

    We’ve had an automatic block in Yoast SEO for a while now, offered to port that to core and were refused… 🤷🏻‍♂️

    Report

    • Zebulan

      First I’ve heard of it. In fact, my PR was based on another PR which was based on another PR which was based off of a plugin:

      https://github.com/sortabrilliant/guidepost

      (And it still took almost a year after I created my PR for the block to become polished enough to merge. 😛)

      I never saw the Yoast SEO table of contents block mentioned in https://github.com/WordPress/gutenberg/issues/11047 or any of the Gutenberg PRs …in fact, I didn’t even know Yoast had a table of contents block.

      Report

      • Joost de Valk

        My colleague Ari told you about it here: https://github.com/WordPress/gutenberg/pull/21234#issuecomment-760060988

        You blew us off, you yourself. You didn’t come up with it so you didn’t want it, that’s how you came across to me.

        You’ve been polishing for a while, ours has been in production for months and is in use by at minimum tens of thousands, probably closer to hundreds of thousands of sites already. What you thought was too complex is the first thing everybody using this is going to ask for, we’ve already built it, we’ve offered to port it. That offer stands, but don’t pretend like we didn’t make it.

        Report

        • Zebulan

          Oh shoot. I guess I’m even more forgetful than I thought. My apologies.

          But I do stand by my assertion that a block directly modifying the attributes of other blocks is a bad idea. I think that should be implemented at the Heading block. (And speaking of which, if you think you could do that in a PR, please do so. I never wanted to be the only one working on this stuff.)

          And quite frankly, I didn’t think I had any authority over what you did and didn’t do. I’m NOT part of Automattic. I’m not even paid to work on Gutenberg. I’m just some random dude doing this because I genuinely just wanted a good table of contents block in core. If you wanted to create your own Table of Contents block PR, then why would you need my permission?

          Sorry if I came off as dismissing you, but all I did (or at least thought I did) was dismiss an implementation idea that sounded unsound to me. I didn’t think my comment would be interpreted as some prideful command from on high. Good grief.

          If you think there’s something inferior about the current implementation, then just open a PR and I’d be happy to review it and give feedback. (But remember that my feedback is only my own.) Heck, maybe your id-generation code could just be (more-or-less) copy-pasted onto the Heading block, depending on how it works.

          What makes you think I give a darn whether I invented the table of contents block or not? I don’t. I only care about making the implementation perfect, hence why I was hesitant on merging for months because of concerns over hacky PHP code that few other people seemed to care about. If I did care about being “the inventor”, I wouldn’t have based my PR on someone else’s. (And I even created my PR with the intention of it being merged into the other one before the creator of the other PR thought I was better suited to move the development forward.)

          Again, I have nothing against Yoast developing a table of contents block, and I didn’t know my comment would be taken so seriously. I commented only on the technical soundness I perceived from one dude’s comment. I thought updating Heading block ids from the Table of Contents block was a bad idea (and for good reason, considering the undo issues I’d encountered earlier with the block), and so I said I thought it was a bad idea. If anyone disagreed with that, I wish they would have provided a counter-argument. And I wish, if you thought your implementation was better, that you would have just created your own PR.

          Report

    • Herb Miller

      Maybe you’ll have more luck with a Breadcrumbs block. For my own Full Site Editing theme ( Fizzie ) I needed a breadcrumbs block. I started writing my own then realised it would be much easier to call your function if it was available. I’ve just implemented on blocks.wp-a2z.org

      Report

  2. Zebulan

    Yeah, ideally the Heading block should auto-generate an anchor id when no custom one is set. There’s a few questions surrounding how that should work and how it would be implemented, but I don’t think it will be too difficult. I don’t know if I’ll end up making a PR to implement that or if someone else will step up to the challenge. Here’s the relevant discussion on GitHub:

    https://github.com/WordPress/gutenberg/issues/6182

    Report

    • Chris

      That would be great not just for the TOC. My blog has lots of list posts and crosslinking, and while links to specific anchors on other pages are not usually the best choice, sometimes we want to do it so visitors don’t have to search around the article for what we’re referencing. We stopped bothering with it because settings ids was such a pain.

      Report

    • Jonah Brown

      What if the heading block had a checkbox setting for generating an id. It could be a toggle just like how links have toggles for nofollow or open in new tab. then if developers wanted to hook into this function for table of content blocks then it would work :)

      BTW I have no idea how to contribute this to the Github PR.

      Jonah

      Report

  3. richard Ginn

    EHHH…. The Gutenberg Block Library & Toolkit – Editor Plus plugin as default is a must

    Report

  4. Mohammad Athar

    I think there should be an option to inject TOC automatically or else we will require to literally inject this in every post which is not a practical idea particularly if we think of disabling the previous plugin.

    Report

  5. Dominique Pijnenburg

    Would be nice if you’d be able to select the depth of headings to be considered. Maybe I’d only want H2’s to be included.

    The entries in the block should be clickable to their respective locations in the article, I can see there’s a technical challenge in this but I’m fully confident that this can be solved.

    Report

    • Zebulan

      I agree that an option to choose the maximum “depth” would be good. Maybe I’ll open a PR for that later when I have some free time.

      The entries are clickable if the corresponding headings have ids. Ideally, the Heading block should auto-generate ids on insertion. But that has some technical challenges of its own. There’s some discussion about it happening in https://github.com/WordPress/gutenberg/issues/6182.

      Report

  6. Ian Pegg

    I’m generally in favour of adding more blocks to Gutenberg, but i would also like the ability to switch off blocks that aren’t wanted or that have superior plugin implementations.

    By switching off a block, I would expect Gutenberg to also suppress the related CSS and JS payloads. This would be very helpful in the age of Core Web Vitals.

    Report

  7. Giorgos Sarigiannidis

    As I built a custom TOC for a project a few months ago, I found that a nice feature, besides automatically updating the TOC, was the option to override the text of a particular entry (either because it was too big for a sidebar item or for whatever reason). To see what I mean, here’s how it works on the backend: https://www.dropbox.com/s/fi1x80zp5z6ml65/gutenberg-toc.mp4?dl=0 (wait until the end).

    Report

    • Zebulan

      I did something similar by allowing the Table of Contents block to be converted to a List block. I did consider allowing the entries to be edited in the ToC block itself, but I figured it would make things too complex and create a confusing UX where some entries would be linked to the text of their respective headings, but others wouldn’t. I figured the explicit convert-to-List button was easier for users to understand and far less complex to implement.

      Report

      • Giorgos Sarigiannidis

        That’s true, it can be hard to implement on a user-agnostic level. On my case, it was for a specific client with a very specific need, so handling it that way was easy. Having to accommodate all possible use-cases makes it much harder. The option to convert it to a list is a brilliant idea anyway.

        Report

  8. Bjarne

    I found that the https://wordpress.org/plugins/luckywp-table-of-contents/ manages to create id’s for headings automatically which is nice, and https://wordpress.org/plugins/getwid/ toc block boasts a core like block options experience, which also is nice. Both seems to output semantic html and are easy to style. I’m all for core blocks, as it assures some degree of future support, and hopefully will the core block eventually be as flexible and easy to use as the 3rd party options. Otherwise, I find it hard to understand why you’ll want to put it in there?

    Report

    • Zebulan

      I thought (and other devs seemed to agree) that it would make more sense for the Heading block to generate its own id, rather than put that behavior in the Table of Contents block. (Having the Table of Contents modify sibling blocks feels un-block-like to me. I think block functionality should generally be self-contained or at least only affecting children blocks.) There’s an open issue discussing how to implement that: https://github.com/WordPress/gutenberg/issues/6182.

      It’s also worth noting that modifying other blocks can be tricky to deal with, since it creates a ton of separate undo actions, which means that trying to undo the action becomes really janky. I just checked, and the Getwid Table of Contents block suffers from this issue. (Earlier versions of the core Table of Contents block suffered from similar issues, which is one of the reasons why it ended up being implemented the way it has been.)

      I notice that the Getwid block allows you to choose which heading levels to display. I don’t think it makes sense to have a separate toggle for each heading level, but I do think a “max heading depth” control would make sense, and I’d like to add it at some point if no one else creates a pull request for it first.

      Concerning other things like changing the list style type (numbers versus bullets) or changing text color, I think a lot of styling stuff like that belongs in the upcoming Global Styles interface, and not as something that can be changed for every individual instance of the block. So I’m a lot more hesitant to add anything like that to the core block knowing how much themes themselves will be changing over the next couple of years.

      It’s also worth noting that the Table of Contents can be converted to a static List block (there’s a button to do so in the toolbar). This allows for a whole lot more customization such as changing the wording of each link, and whatever else you can do with a List block.

      Everything that gets added to core has to be supported for a long time, and I’ve already seen too many cases where something was implemented in a less-than-ideal way, and then changing it later on became twice as hard due to the need for some level of backward compatibility.

      And note that in some cases, it makes more sense for plugins to extend core blocks rather than add entirely new ones. In fact, something like adding ids to all Heading blocks on the page could be implemented in a plugin without even having to modify the core Table of Contents block.

      Report

  9. Peter Shaw

    Please, please stop adding features to Gutenberg. There are already far too many block types.

    If I want these “features” I’ll install a plug-in.

    The approach from core should always be about providing a BASIc product, and robust apis to add enhancements if required. Especially as there are so many vital apis missing from core
    eg user taxonomies, custom post status, and object relationships

    Report

    • Gilzow

      Agree 100%. Keep the default collection simple and only include the items that 80% of users need. Allow others to fill the need for the remaining 20%.

      Report

  10. Kingsley Felix

    Does it work on AMP pages?
    currently, this plugin https://wordpress.org/plugins/simpletoc/ works for both AMP and NON AMP

    Report

  11. Helpful Colin

    I’ve tried using two TOC blocs from plugins and they were both very good and get improved when problems appear. They are:
    1. The TOC block from Ultimate Addons for Gutenberg,
    2. The TOC block from Kadence Blocks.
    They both have a lot of settings for colours, fonts and sizes.
    I’m currently using the Kadence TOC block after there was a bit of a hiccup with the UAG TOC block. I suspect UAG have made improvements by now so I must take another look at it.
    Both versions automatically insert anchors linked to headings and process editing of headings.
    More than one TOC can be entered in any post. You can set a TOC to work with H1, H2 and H5 say and another TOC to work with H3, H4 and H6 say. (Each heading can be turned on or off in each TOC.) Why would you want to do that? Well one might list sections in a document while the other lists pictures (by giving each picture a heading immediately before it using H4 say.)
    Another question is, “Where to insert a TOC?” Well I put them after the “Introduction”. I start each post with an “Introduction” H2 heading followed by a few paragraphs. The first paragraph has to include the Focus Keyphrase for SEO reasons. This is why the TOC can’t be at the beginning of the post.
    I think anyone wanting to put a TOC in core should look at the facilities and settings offered by TOCs in plugins, such as those I’ve mentioned, to get ideas about what can be done.

    Report

  12. gilzow

    Are there really that many people who need this block type to justify adding it to the gutenberg plugin (which of course later gets pushed into WordPress core)? As an add-in block, sure. I don’t see any issue with that, but is it really in such high demand that every WordPress site needs it in the default collection?

    Report

    • Justin Tadlock

      Adding TOCs is a common feature of writing/publishing software. Therefore, I would argue that it should be pre-packaged with WordPress.

      Report

      • Gilzow

        since when did WordPress become “writing/publishing software”? Last I checked it was a CMS that “you can use to create a beautiful website, blog, or app”. And I’ll have to respectfully disagree with you on your analysis. I manage a fleet of 300+ WordPress sites, and the number of them that need ToC on a page I can count on one hand. Now, that is anecdotal “evidence” hence my question of: are there that many sites that need this block in default? Given my 10+ years of experience with WordPress, I’d say “no”.

        Report

        • Justin Tadlock

          WordPress has been writing/publishing software since Day 1. It has evolved into a larger CMS over the years that allows you to do far more, but the process of writing and publishing content has always been central to the platform.

          I could throw out my anecdotal numbers too, but I don’t think that would be conducive to the discussion.

          Report

  13. Alvaro Gomez

    On the web, a TOC needs to link to those headings so that readers can jump to the section they want to view. Right now, this does not happen automatically. Perhaps it will do so in the future.

    This makes the block fall very short of its purpose. I reviewed half a dozen such blocks in mid 2019 and every single one of them did this 😕

    https://gu10.blog/2019/08/15/table-of-contents-summary-blocks-a-comparison/

    Report

Comments are closed.

%d bloggers like this: