Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Way to disable slugifying headings #1232

Closed
damieng opened this issue Feb 4, 2023 · 7 comments
Closed

Way to disable slugifying headings #1232

damieng opened this issue Feb 4, 2023 · 7 comments
Labels
Area: Table of contents Pertaining to table of contents (TOC generation and detection, related heading operations). Needs Discussion We haven't decided what to do.

Comments

@damieng
Copy link

damieng commented Feb 4, 2023 •
edited

Proposal

Please consider a way to disable slugifying headings.

Right now even if you use the <!-- no toc --> or set the toc contents to only be level 1 this extension still slugifies all your headings by adding <a id="slugified-version-of-your-heading"></a> to all headings.

This is especially problematic where the same heading is repeated as it generates the same ID and will also collide with id's you set yourself.

Other information

Some possibilities might be

  • An option under slugify style like "None"
  • A global disable slugify tag like <!-- no slugify -->
  • Improving the existing slugify code to only slugify headings that will be in the toc

Workarounds

I have reverted to v3.4.0 to allow my document to be generated again but then I lose newer features.
@damieng damieng changed the title Option to disable slugify Way to disable slugifying headings Feb 4, 2023
@yzhang-gh
Copy link
Owner

yzhang-gh commented Feb 4, 2023 •
edited

Thanks for reaching out.

It is doable, e.g., a slugify option none as you suggested. (As a result, the TOC will become plain text, i.e. toc.plaintext: true)

Just a bit curious in which cases the heading IDs will collide with those that are manually set. And to avoid this, either you can choose a slugify function (e.g. bitbucket-cloud) which adds markdown-header- prefix to all the heading IDs, or you can add some prefix to those manually set id, e.g., df- (definition), fig-, table-.

I was also wondering why v3.4.0 works for you but v3.5.0 does not.

@yzhang-gh yzhang-gh added Needs Discussion We haven't decided what to do. Area: Table of contents Pertaining to table of contents (TOC generation and detection, related heading operations). labels Feb 4, 2023
@damieng
Copy link
Author

damieng commented Feb 4, 2023 •
edited

Thanks for such a quick response.

The markdown I am editing is at https://github.com/ZXSpectrumVault/Manuals/tree/master/Hardware and I used your excellent extension to create the HTML there too using the "Print document to HTML function".

Because I am reproducing an old computer manual I want very specific control over the TOC and there are many duplicate sub-headings. So I created a TOC by hand and put the appropriate id's in by hand as <a name="id"></a> inside the headings.

In 3.4.0 two things were happening:

  1. In the case of headings getting ids (slugifying) all the generated ones were prefixed with - and so did not conflict - possibly because there was a space between the # and the heading text?
  2. Duplicate headings got a -n postfix where n was a number counting up

So things worked fine.

In 3.5.0 however the prefix is missing so it collides with mine which I can work around as you said by choosing a different slugify format - but also in the case of ##### EXIT CONDITIONS where that would have resulted in exit-conditions-2 etc. now it generates multiple exit-conditions ids

A simpler fix I guess might be to not slugify headings unless a TOC is being generated. Right now turning off the TOC still slugifies the headings unnecessarily.

@yzhang-gh
Copy link
Owner

yzhang-gh commented Feb 4, 2023 •
edited

I see.

  1. In the case of headings getting ids (slugifying) all the generated ones were prefixed with - and so did not conflict - possibly because there was a space between the # and the heading text?

That's because we changed how we handle HTML in the heading. Personally I think the current behavior is "correct".

  1. Duplicate headings got a -n postfix where n was a number counting up

This might be a bug. But I cannot reproduce it with a simple document. Could you try to find out a piece of short text which has this issue?

A simpler fix I guess might be to not slugify headings unless a TOC is being generated. Right now turning off the TOC still slugifies the headings unnecessarily.

It isn't easy under the current implementation which changes the markdown-it rendering (MD to HTML) directly. (i.e., it is not post-process)

@damieng
Copy link
Author

damieng commented Feb 4, 2023 •
edited

If I just do this:

# Hello

## Hello there

## Hello there

Then it is generating in 3.4.0:

<!-- head etc -->
<body class="vscode-body vscode-light">
<h1 id="hello">Hello</h1>
<h2 id="hello-there">Hello there</h2>
<h2 id="hello-there-1">Hello there</h2>
</body>

But in 3.5.0 it generates:

<body class="vscode-body vscode-light">
<h1 id="hello">Hello</h1>
<h2 id="hello-there">Hello there</h2>
<h2 id="hello-there">Hello there</h2>

In both cases it is not actually writing a table of contents (TOC) which is great... but I don't understand why it adds IDs to all the headings if it doesn't need them in both versions.

Ideally it would just be:

<body class="vscode-body vscode-light">
<h1>Hello</h1>
<h2>Hello there</h2>
<h2>Hello there</h2>

I really want to be able to use 3.5.0+ so I can set the document title and not have the KaTeX in the output.

yzhang-gh added a commit that referenced this issue Feb 5, 2023
@yzhang-gh
🐛 #1232 regression: duplicated heading ids
ddb7126
@yzhang-gh
Copy link
Owner

But in 3.5.0 it generates:

<body class="vscode-body vscode-light">
<h1 id="hello">Hello</h1>
<h2 id="hello-there">Hello there</h2>
<h2 id="hello-there">Hello there</h2>

Thanks for catching this bug. It has been fixed now.

I have also packaged a standalone version that disables all heading IDs. You can try it out.

@damieng
Copy link
Author

damieng commented Feb 5, 2023

Awesome, that standalone version did not generate any ids! :)

@yzhang-gh
Copy link
Owner

Nice to hear that. (And thanks for your coffee 😉)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Area: Table of contents Pertaining to table of contents (TOC generation and detection, related heading operations). Needs Discussion We haven't decided what to do.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@damieng @yzhang-gh