Add Table of Contents block (dynamic rendering + hooks version) #21234
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
ZebulanStanphill
changed the title
ZebulanStanphill
added
the
[Type] Technical Prototype
|
Size Change: +1.65 kB (0%) Total Size: 1.38 MB
ℹ️ View Unchanged
|
ZebulanStanphill
force-pushed
the
add/table-of-contents-hooks-version
branch
6 times, most recently
from
41a5891 to
16b9988
Compare
ZebulanStanphill
removed
the
[Type] Technical Prototype
ZebulanStanphill
changed the title
ZebulanStanphill
added
Needs Technical Feedback
ZebulanStanphill
force-pushed
the
add/table-of-contents-hooks-version
branch
from
16b9988 to
b5a277b
Compare
ZebulanStanphill
requested review from
ajitbohra,
jorgefilipecosta,
nerrad,
ntwb,
Soean and
talldan
as code owners
5 tasks
ZebulanStanphill
force-pushed
the
add/table-of-contents-hooks-version
branch
2 times, most recently
from
4147d65 to
27ce31b
Compare
|
I have no idea what's causing the test failure. |
|
Looks like undo doesn't work. I set up a hierarchy of headers and then deleted one, saw the contents update, then pressed undo and it didn't come back again (it seems to quickly appear then get deleted again). Maybe the BTW your test failure may be related to this. |
ZebulanStanphill
force-pushed
the
add/table-of-contents-hooks-version
branch
from
b3f796a to
e7b7c84
Compare
Co-authored-by: Joen A <[email protected]>
ZebulanStanphill
force-pushed
the
add/table-of-contents-hooks-version
branch
from
4eebd78 to
e28b150
Compare
ZebulanStanphill
removed
Needs Design Feedback
Yes, a pretty old one even: #6182. I decided to make 2 last-minute changes before merge. First, I changed one of the search keywords from "outline" to "document outline" to ensure that searching that full term will bring up this block. Second, I added @jrtashjian to the initial commit author list, since he worked on the original Guidepost plugin that served as the basis for @ashwin-pc's PR, which in turn served as the basis for @SeanDS's PR, which served as the basis for mine. And so, after two and a half years of development, the Gutenberg block editor finally has a core Table of Contents block. To everyone who helped make this possible: thank you. ❤️ |
|
Thank you to everyone involved! |
|
Two and half years of waiting! I'm looking forward to Gutenberg 10.2 🎉 |
|
I'm happy to see this get added into core and appreciate the kudos! Thanks all who were involved 🚀 |
|
Amazing work @ZebulanStanphill! I had no idea it would take so much effort to get this working, and there's no way I could have pulled it off the way you did here so I'm really happy you adopted it. Looking forward to this landing in core! |
|
I am using the YOAST TOC block. It is great to see it is arriving at the Core. I encountered an issue with the YOAST block that might affect your implementation as well. I thought I might mention it: Example: I guess that the best solution is: when the TOC block displays on an archive page - make its links absolute? |
|
Thanks @ZebulanStanphill ! Looking forward to the feature. |
mcsf
added
the
[Block] Table of contents (experimental)
|
thanks everyone |
|
It would be nice if it also supported numbered list, in addition to the bulleted list. :) |
|
When will this feature hit the mainline wordpress release? Do we need to wait for a new wordpress version or can we install 10.2 earlier? The milestone is 9 days overdue, so I expect a release soon? |
|
I've got a refactor PR for the Table of Contents block (#29739), but I'm running into some infinite-loop issues and I need some help to fix them. |
|
Has any further work been done on this? |
Merged
5 tasks
adamziel
pushed a commit
that referenced
this pull request
May 6, 2022
…g and Page Break blocks (#29739) Re-enables the Table of Contents block, which was first merged over a year ago in #21234. The block is using static markup and only supports the core Heading and Page Break blocks, using a much cleaner and performant implementation. It is also using <ol> for the lists. Co-authored-by: Miguel Fonseca <[email protected]>
|
WordPress version 6.5.3 does not have a table of contents block, I recommend adding a Table of Contents block to WordPress 6.6 core to quickly create a table of contents based on all the headings on a page. From then on I won't need to install the Table of Contents Plugin anymore. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Description
Closes #11047. Related: #22874.
This is a derivative of #21040 (which itself is a derivative of #15426) that has been massively refactored to support h1-h6 elements anywhere in the content (not just core Heading blocks), as well as paginated posts.
Big props to @SeanDS, @ashwin-pc, sorta brilliant, and everyone else who has helped make this block a reality! 😄
Screenshots
Implementation notes
There are some notable quirks about the implementation I should point out:
First, both the front-end and editor implementations creates temporary HTML documents (or unattached
<div>s in the case of the editor) in memory during the render process, just so they can be filled with the current post's content and parsed using DOM APIs to determine how manyh1-h6tags and<!--nextpage-->comments there are in the current post. This feels hacky and sounds like it could be a performance issue, but in practice I haven't noticed any serious performance impact, and I am not aware of a better solution.Second, when using the "Only include current page" option with a paginated post, the editor implementation is technically not able to determine which page a Table of Contents block will appear on with 100% accuracy. It only accounts for
<!--nextpage-->comments that occur in a Page Break or Classic block. The front-end implementation does not have this imperfection.To fix this using the currently available APIs would require searching the content of every block preceding the Table of Contents block every time the editor content changes. As it is, it currently only scans the content of Classic blocks, and the content of Page Break blocks don't have to be scanned since, well, just knowing they are a Page Break block already tells you all you need to know.
However, I doubt this slight inconsistency would be an issue in practice. I can't think of a situation where someone wouldn't just use the Page Break block when creating new content, and old content will all be in the Classic block. It would be trivial to add support for page breaks within Custom HTML blocks, but that seems like an anti-pattern to me.
It's also worth noting that I scan the Classic block's content for page breaks by reading its
contentattribute. It's not possible to support every block through this method since 3rd party blocks could use a differently-named attribute to store their text/html content, and I can't predict what the content attribute will be called. To support any given block would require getting the blocks' inner HTML... and I'm not aware of any API to do that from the editor.Technical feedback on any of this is very welcome. There has been some discussion in #22874 about a document-outline/headings API to provide a method of getting the required data without constantly scanning raw HTML for different elements/comments, but I think this PR in its current state may be good enough as-is.
Todo