Readme heading ids

[tynanbe]

Every readme heading should be generated with an id, such that links pointing to those headings work properly, e.g. on hexdocs (GitHub automatically does this).

Example

## Advanced Usage

### Another Example

Should generate something like

<h2 id="advanced-usage">
  <a href="#advanced-usage" class="anchor" aria-hidden="true"><svg class="icon icon-star"><use xlink:href="#icon-star"></use></svg></a>
  Advanced Usage
</h2>

<h3 id="another-example">
  <a href="#another-example" class="anchor" aria-hidden="true"><svg class="icon icon-star"><use xlink:href="#icon-star"></use></svg></a>
  Another Example
</h2>

Suggested CSS

.anchor {
  float: left;
  font-size: .75em;
  line-height: 2;
  margin-left: -1.125em;
  padding-right: .125em;
  visibility: hidden;
}
h1:hover .anchor,
h2:hover .anchor,
h3:hover .anchor,
h4:hover .anchor,
h5:hover .anchor,
h6:hover .anchor {
  visibility: visible;
}

Note that the same heading title might be used multiple times, so perhaps a number should be appended to the id in those cases.

Note that the same heading title might be used multiple times, so perhaps a number should be appended to the id in those cases.Note that the same heading title might be used multiple times, so perhaps a number should be appended to the id in those cases.

Mockup

Here's a screenshot of two sets of h2 and h3 tags, top on :hover and bottom normal.

[inoas]

The star would make me think it is a bookmark function.
What about:

Character (¶) used to denote a paragraph

[lpil]

Sounds good. I think we would need to be a bit clever with how we handle markdown. Currently we just render it but we would need to customise that in some fashion

[giacomocavalieri]

I was having a brief look at this and it seems to be a big amount of work for not that big of a gain. I'll report a bit of what I've found.
The parser we're using is an efficient event based parser, meaning that as it parses the markdown document it produces an iterator of events like this: TagOpen(Heading{ id, ... }), Text(...), TagClose(Heading(...)).

The problem with changing the heading id is that we would need to see the textual content of the node until a closing tag is reached, only then we could generate an id. However the way this works we can't really hold a mutable reference to the first id, that is gone already when we reach the closed tag!

One way to update it would be to write a wrapper iterator that holds onto the opening tag and all intermediate events until it find the closed tag and then emits all those events:

// very pseudo rust!
struct ParserWithHeadingIds<'a> {
    // v wraps the library's parser (that's just an iterator)
    parser: pulldown_cmark::Parser<'a>,
    event_queue: Vec<pulldown_cmark::Event<'a>>
}

impl<'a> Iterator for ParserWithHeadingIds<'a> {
    type Item = pulldown_cmark::Event<'a>;
    
    fn next(&mut self) -> Option<Self::Item> {
        let event = self.parser.next();
        if event.is_start_header_event() {
          // Hold onto all the events until we find a closed
          // header event, come up with the id, and start
          // emitting all the events we held onto
          loop {
            let next = self.parser.next();
            if next.is_close_header_event() {
              let id = todo!(); // come_up_with_id_having_seen_all_other_events
              return start_header_event_with_id(id);
            } else {
              event_queue.push(next);
            }
          }
        } else {
          // Otherwise the event is just emitted regularly
          event
        }
    }
}

This will probably require a bit more bookkeeping. Do you think this level of complexity would be acceptable for the feature? Another approach would be to edit the html after it is produced, but that would require also having an html parser, sounds even more involved...

Also worth pointing out that one can already add an id themselves if they need to for custom pages!

# Wibble {#wibble-id}

[lpil]

That iterator doesn't seem too bad too me, providing we have sufficient tests.

The bit I'm mostly concerned about is how we would ensure that duplicate ids don't get produced, avoiding collisions with replicated headings and with ids we generate from the code. Whatever system we use for this would likely make it challenging for the writer to know what they will be in the HTML...

[giacomocavalieri]

I think it would be fine to just add a numeric suffix. I think the real value in those is just being able to copy-paste a link to that section and it doesn't really matter what exact id that is (as long as it's human readable). What kind of drawbacks could that have given we're talking about static markdown files?