Add human readable IDs to individual examples of the spec

Spec
1

Possible syntax:

.
unordered-list
.
- `one
- two`
.
<ul>
<li>`one</li>
<li>two`</li>
</ul>
.

where unordered-list would be the ID. We could then render this on the spec with a prefix: Example XXX: unordered-list, and make the HTML ID for the example be #unordered-list.

It is currently already possible to refer to example by version / number pair but human readable IDs have the following advantages:

  • People can more easily remember what example is being talked about from the ID (unordered-list) rather than a number. (123).

    So on a discussion, if you use the human readable ID, it is much more likely that people will have to look it up on the spec many times.

    Would also be useful with: https://github.com/jgm/CommonMark/pull/247 for command line usage

  • They may cross versions: if you refer to the example on an specific version, it is easier to find it later on the most recent one

  • When you have the spec open in your editor, you can easily search an ID to go to it, which is much easier than finding the example’s code.

2

The specs are versioned, and the links on the IDs will take you to a particular version of the spec. So there shouldn’t be a problem referring to particular examples.

+++ Ciro Santilli [Dec 21 14 13:27 ]:

3

Advantages of having human readable IDs:

  • People can more easily remember what example is being talked about from the ID (unordered-list) rather than a number. (123).

    So on a discussion, if you use the human readable ID, it is much more likely that people will have to look it up on the spec many times.

    Would also be useful with: https://github.com/jgm/CommonMark/pull/247 for command line usage

  • They may cross versions: if you refer to the example on an specific version, it is easier to find it later on the most recent one

4

I doubt, that it’s possible to make short, informative and different hr ids for 400+ links :slight_smile:

5

That is a reasonable objection :wink:

karlcow did come up with 100 reasonable names at: https://github.com/karlcow/markdown-testsuite/tree/master/tests

I might give it a quick shot and report back later.