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.

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

Use unique anchors in ToC links #164

Open
traut opened this issue Apr 23, 2024 · 2 comments
Open

Use unique anchors in ToC links #164

traut opened this issue Apr 23, 2024 · 2 comments
Labels
bug Something isn't working
Milestone

Comments

@traut
Copy link
Member

traut commented Apr 23, 2024

ToC is rendered with local markdown links. At the moment, the anchors (hash in the URL) are derived from the title, which creates an issue when similar titles are used:

- [192.168.XX.201](#192.168.xx.201)
   - [Screenshots](#screenshots)
   - [Steps](#steps)
- [192.168.XX.240](#192.168.xx.240)
   - [PoC Code](#poc-code)
   - [Screenshots](#screenshots)
   - [Steps](#steps)

The anchors should be suffixed with -<number> if there if there are duplicates, for example:

- [192.168.XX.201](#192.168.xx.201)
   - [Screenshots](#screenshots)
   - [Steps](#steps)
- [192.168.XX.240](#192.168.xx.240)
   - [PoC Code](#poc-code)
   - [Screenshots](#screenshots-1)
   - [Steps](#steps-1)

Uniqueness

First iteration

The problem is that we can not be sure that the user's Markdown rendered will de-duplicate links similarly - by adding -<num> -- as the Github Markdown renderer does. This is ok for the first iteration.

Proper fix

Since generic Markdown schema does not allow custom anchors on titles, another way to enable uniqueness here is to reformat the duplicate titles as HTML tags:
instead of

## Steps

create

<h2 id="steps-1">Steps</h2>

This complicates the logic—the ToC plugin would need to reprocess already produced Markdown strings to rewrite the headers. This is a good second iteration

References

@traut traut added the bug Something isn't working label Apr 23, 2024
@traut traut added this to the v0.4 milestone Apr 23, 2024
@traut traut changed the title Create unique anchors in ToC links Use unique anchors in ToC links Apr 23, 2024
@traut
Copy link
Member Author

traut commented Apr 23, 2024

in addition, # breaks the anchor:

[Target #1 - 192.168.x.1](#target-#1---192.168.x.1)

We should follow GitHub Markdown schema here and skip # character

@traut
Copy link
Member Author

traut commented May 12, 2024

moved to milestone 0.5 to wait for #159 as it is an enabler for this issue

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Something isn't working
Projects
None yet
Development

No branches or pull requests

1 participant