Table of Contents formatter can conflict with Prettier

[dylankerr-bis]

This is somewhere between a bug and a feature request - I'll explain how to reproduce the issue before talking about possible solutions.

Problem

With certain settings (specifically, Prettier set to use 4-space indentation and toc.updateOnSave enabled), the Table of Contents formatter/updater and Prettier conflict and attempt to format the list in different ways.

How to reproduce

If I create the Markdown file below:

# Heading

- [Heading](#heading)
    - [Subheading](#subheading)

## Subheading

Content.

... and then save the file, Prettier will re-format the file as follows (which is my desired format):

# Heading

-   [Heading](#heading)
    -   [Subheading](#subheading)

## Subheading

Content.

... and the Table of Contents formatter will then immediately set it back to the original state.

Configuration

settings.json:

{
    "editor.formatOnSave": true,
    "markdown.extension.italic.indicator": "_",
    "markdown.extension.list.indentationSize": "inherit",
    "markdown.extension.orderedList.marker": "one",
    "[markdown]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    }
}

.prettierrc:

{
    "singleQuote": true,
    "trailingComma": "es5",
    "printWidth": 100,
    "tabWidth": 4,
    "endOfLine": "auto",
    "proseWrap": "always"
}

Proposal

I think in general, the Table of Contents updater is more concerned with the content (making the ToC correct) than the formatting, so it might make sense to move the update process before VSCode's formatOnSave runs, thereby allowing the user (through their choice of formatter) to control the format.

If this is not possible or practical, more configuration in the ToC formatting would allow me to generate a ToC that Prettier does not need to modify.

References

[yzhang-gh]

Have you tried to change markdown.extension.toc.updateOnSave?

[Lemmingh]

This is a quite complex topic.

Our TOC template is hard-coded

the Table of Contents formatter/updater and Prettier conflict and attempt to format the list in different ways.

allow me to generate a ToC that Prettier does not need to modify.

We code the template mainly for accuracy and reliability.

vscode-markdown/src/toc.ts

Line 303 in cea94a7

async function detectTocRanges(doc: TextDocument): Promise<[Array<Range>, string]> {

vscode-markdown/src/toc.ts

Lines 279 to 283 in cea94a7

	const row = [
	docConfig.tab.repeat(relativeLevel) + indentationFix,
	(tocConfig.orderedList ? (orderedListMarkerIsOne ? '1' : currHeadingOrder) + '.' : tocConfig.listMarker) + ' ',
	tocConfig.plaintext ? entry.visibleText : `[${entry.visibleText}](#${entry.slug})`
	];

As for changing it, @yzhang-gh is hesitant, and I'm not motivated.

• Customize TOC style and template #403

The internal of the onWillSaveTextDocument event is out of our control

move the update process before VSCode's formatOnSave runs

The toc.updateOnSave feature is just a listener on the event.

vscode-markdown/src/toc.ts

Line 68 in cea94a7

workspace.onWillSaveTextDocument(onWillSave),

I remember a maintainer of esbenp.prettier-vscode opened an issue at VS Code to discuss the on-save behavior long time ago, but cannot find it now.

[dylankerr-bis]

Ok, thanks for the detail.

For now I will work around this by changing my indent width in Markdown files to 2 spaces, as that makes the ToC generator and Prettier agree.

I agree that too much flexibility in the ToC format would be impractical. If I really want to get 4-space indentation working with this I'll start a discussion on the VSCode side about formatOnSave vs. onWillSaveTextDocument ordering (there might be other use cases for configuring the order of those events).