. unordered-list . - `one - two` . <ul> <li>`one</li> <li>two`</li> </ul> .
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
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. (
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.