Disable the auto-generation of section IDs ?

[lcawl]

While reviewing the differences between the old and new (Asciidoctor) output for #666, we noticed that there are a lot of autogenerated section IDs. For example:
<a id="_fix_split_brain_can_occur_even_with_minimum_master_nodes_status_done_v1_4_0_beta1">
<a id="_using_lucene_checksums_to_verify_shards_during_snapshot_restore_status_done_v1_3_3">

Per https://asciidoctor.org/docs/user-manual/#auto-generated-ids, you can disable the auto-generation of section IDs, by unsetting the sectids attribute.

Should we consider doing this? It would mean that if we want to be able to link to a section, we'd have to explicitly add an anchor, which is what we had discussed as a best practice anyway.

If we do want to do this, would then want to consider whether we do it for all books or a subset.

Related to #647

[nik9000]

I had a thought on this topic this morning. I wonder if we should keep generating the ID but detect when someone is linking to them and float some text on the screen explaining that the ID isn't permanent but that they can open a PR to make a permanent ID. Since most of our docs are public this is a thing that folks outside of Elastic the company can do. That way we can know that any non-auto-generated IDs are there for some reason. We can even git blame to figure out who made them.

[lcawl]

If that's feasible, it sounds pretty magical

[nik9000]

If that's feasible, it sounds pretty magical

We'd have to use a heuristic to detect if an ID was auto-generated or not. So long as the heuristic is good I think we can do it. And I think "does it start with _ is a good heuristic. We could also fail the docs build if you declare any IDs that start with _ and tell you that those look too much like auto-generated-ids. At least, we can do that in Asciidoctor.

[nik9000]

@dedemorton mentioned today that page names also come from the IDs. I hadn't really thought of that for #668 (comment) . My point in that issue was about the ids on the page, not the ids that turn into the page's name. I think we 100% should make folks specify the name of every page.

Another point from @nrichers an @kellyemurphy: some of our docs won't have an edit link because they are private. They'll need different language about how to ask to make the link real. Assuming we do want to generate these at all.

[debadair]

We absolutely should avoid generating pages with automatically generated IDs. Magic would be nice, but disabling them would at least keep from perpetuating the problem.

[nik9000]

The real reason I haven't picked this up is because I haven't had time yet. I think soon we should do some prioritizing. I see the light at the end of both of my current projects so it'll soon be time to start in on these.

…

On Tue, Sep 24, 2019 at 7:56 PM debadair ***@***.***> wrote: We absolutely should avoid generating pages with automatically generated IDs. Magic would be nice, but disabling them would at least keep from perpetuating the problem. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#668?email_source=notifications&email_token=AABUXISQDXP4PHERS6GBHGLQLKSMRA5CNFSM4G36O63KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7QETCY#issuecomment-534792587>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABUXISERCVKUWKF7PNQCYLQLKSMRANCNFSM4G36O63A> .

[dedemorton]

We absolutely should avoid generating pages with automatically generated IDs.

Agreed. I suspect that most of these were fixed during the migration to asciidoctor. I think we should allow auto-generated section IDs, though, unless Nik can create a script that we can run against the docs...or hire an intern. I never want to have to backport to 25 branches ever again.

[nik9000]

I think it'd be a "from here on out" thing.

…

On Tue, Sep 24, 2019, 21:48 DeDe Morton ***@***.***> wrote: We absolutely should avoid generating pages with automatically generated IDs. Agreed. I suspect that most of these were fixed during the migration to asciidoctor. I think we should allow auto-generated section IDs, though, unless Nik can create a script that we can run against the docs...or hire an intern. I never want to have to backport to 25 branches ever again. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#668?email_source=notifications&email_token=AABUXIRSV3DUDSZGGDOHH2DQLK7OTA5CNFSM4G36O63KYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD7QKFSQ#issuecomment-534815434>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABUXIT6B4GARVL6GIWUCXLQLK7OTANCNFSM4G36O63A> .