Tracked in #1899.
Background
PR #1898 introduces a new opt-in option linkIndexAutotitle for the generic includer. When enabled together with linkIndex, the directory entry's title is taken from the H1 heading of the nested index.md (via the existing autotitle pipeline), instead of the folder name.
The flag defaults to false in v5 to preserve backward compatibility for existing linkIndex consumers (added in PR #1784) that rely on folder names for directory titles.
Proposal for v6
- Make the index.md autotitle behavior the default when
linkIndex is enabled and autotitle is not disabled.
- Either remove the
linkIndexAutotitle option entirely, or invert its meaning (e.g. useFolderNameForLinkIndex) — to be decided.
Why this is breaking
Existing linkIndex users would see their toc directory titles change from folder names to whatever the H1 of the linked index.md says. Without an explicit migration step, this is a visible behavior change.
Migration notes
- Document the behavior change in the v6 release notes.
- Suggest setting
linkIndexAutotitle: false (or equivalent) in v5.x ahead of the upgrade for users who want to keep folder names.
Tracked in #1899.
Background
PR #1898 introduces a new opt-in option
linkIndexAutotitlefor thegenericincluder. When enabled together withlinkIndex, the directory entry's title is taken from the H1 heading of the nestedindex.md(via the existing autotitle pipeline), instead of the folder name.The flag defaults to
falsein v5 to preserve backward compatibility for existinglinkIndexconsumers (added in PR #1784) that rely on folder names for directory titles.Proposal for v6
linkIndexis enabled andautotitleis not disabled.linkIndexAutotitleoption entirely, or invert its meaning (e.g.useFolderNameForLinkIndex) — to be decided.Why this is breaking
Existing
linkIndexusers would see their toc directory titles change from folder names to whatever the H1 of the linkedindex.mdsays. Without an explicit migration step, this is a visible behavior change.Migration notes
linkIndexAutotitle: false(or equivalent) in v5.x ahead of the upgrade for users who want to keep folder names.