Discuss: AsciiDoc vs Asciidoctor auto-generated ids

[nik9000]

Yesterday we discovered that AsciiDoc's autogenerated ids don't quite line up with Asciidoctor's autogenerated ids. Changing IDs can be a huge pain because everyone's links have to be updated. So if we can avoid it we'd prefer not to change the ids. but it looks like Asciidoctor's ids mostly differ in ways that make them better. Specifically, they remove html entities before building the id. Compare auto generated ids:

Title	Asciidoc	AsciiDoctor
What's Next	_what_8217_s_next	_whats_next

The ' gets converted into a RIGHT SINGLE QUOTATION MARK which has the decimal html escape ’. That is where the 8217 number comes from. Asciidoctor removes it before generating the id. AsciiDoc keeps it. In this case I think we'd prefer Asciidoctor's result.

There is a separate question around whether or not we should ever use autogenerated ids. Asciidoctor allows us to turn them off if we'd like, but I don't want to get that discussion tangled up in the asciidoctor migraiton.

[lcawl]

It might help to understand how heavily we rely on auto-generated IDs (i.e. how many links would be broken if we use the new format). If the volume isn't insurmountable, I think we should go with what AsciiDoctor gives us (and ideally fix the root problem by explicitly defining an anchor ID).

[nik9000]

I'm fairly sure we generate a ton of IDs via autogeneration. But I don't know how often we link to them. I don't know if it is the number of IDs that matters or the linking. And, because they exist, folks can link to them even if we don't. At least they are just IDs so if they are missing folks will end up on the page. It isn't great but it is probably better than a 404. Most of the time.

[debadair]

Closing this since we've completed the migration. The separate issue about disabling auto-IDs should remain open.