diplodoc-platform / diplodoc-platform/cli

v6: make GenericIncluder linkIndexAutotitle behavior the default

Open
#1,900 0 comments 0 reactions 0 assignees View on GitHub
major
Dominant language
TypeScript
Stars
123
Forks
51
Avg merge
10h 50m
Merged PRs (30d)
38

Description

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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.