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

Auto-generated header links ignore mis-anchor headers that start with a number #527

Open
choldgraf opened this issue Feb 24, 2022 · 4 comments
Labels
bug Something isn't working

Comments

@choldgraf
Copy link
Member

Describe the bug

When section headers start with a number, they are labeled in a confusing way by the auto-header anchor generator. They simply have the structure id<num>.

For example, a document like this:

## v2.0

## 2.0

Will generate anchors like:

<a class="headerlink" href="#v2-0" title="Permalink to this headline">
<a class="headerlink" href="#id1" title="Permalink to this headline">

I think users would instead expect the ID of the second element to be 2-0

Since we describe the behavior as based on the GitHub sluggify, I also quickly checked and it looks like they do support IDs that start with numbers (that's why I'm labeling this as a bug since I think it breaks from expected behavior based on that criteria).

I think the relevant code for this might be here:

https://github.com/executablebooks/mdit-py-plugins/blob/master/mdit_py_plugins/anchors/index.py#L119-L120

originally reported in: jupyterhub/kubespawner#575

Reproduce the bug

  1. Set myst_heading_anchors = 2

  2. Create a page like

    # Test
    ## v2.0
    
    ## 2.0
  3. Render it and note the heading IDs

List your environment

No response

@choldgraf
Copy link
Member Author

Just realized another problem this surfaces - if people have multiple numbered sections (e.g. in a changelog, 3.0, 3.1, 3.2) then adding a new section at the top (e.g, 4.0) will bump the id# of all subsequent labels, making links to them valid links, but not to the correct section.

@chrisjsewell
Copy link
Member

This may be similar to #195, whereby docutils/sphinx seems to treat such references differently.
Should probably track down in the code exactly where/why it is doing this

@chrisjsewell
Copy link
Member

I think its treating them as "auto-targets", similar to autofootnote; the only fix may be to stick a prefix onto such slugs e.g. `if target.isdigit(): target = "-" + target"
this would not be in keeping with github slug rules, but may be the only way

@choldgraf
Copy link
Member Author

maybe they could just be prefixed with num- or even n- if they started with a number?

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

2 participants