redhat-documentation / asciidoc-markup-conventions

How to use AsciiDoc mark-up to properly style elements in Red Hat documentation
https://access.redhat.com/documentation/
17 stars 16 forks source link

Update the 'Anchor' example #37

Closed yetanothertw closed 2 years ago

yetanothertw commented 3 years ago

The example must be update to reflect the latest Mod docs conventions as per the Modular Documentation Reference Guide: https://redhat-documentation.github.io/modular-docs/

From: [id="section-header_{context}"]

To: [id="proc-section-header{context}"] or [id="ref-section-header{context}"] or [id="con-section-header{context}"] or even [id="assembly-section-header{context}"]

bergerhoffer commented 3 years ago

If I understand the mod docs guidance correctly, the anchor names are supposed to match the file names, per the description from https://github.com/redhat-documentation/modular-docs/pull/121:

Anchor names should match files names without the .adoc extension, and with the addition of _{context}.

And it is optional to use proc or con or ref as a prefix in your file names. Teams can alternatively use the option to define the :_module-type: variable in the file. So I don't think that we'd necessarily want to require this here in the general anchor format.

yetanothertw commented 3 years ago

Fair point @bergerhoffer I only became aware of the :_module-type: variable last week. I hadn't realised that using proc, con, ref or assembly is optional. Thanks for pointing this out! :)

bergerhoffer commented 2 years ago

@yetanothertw I'm closing this issue because I don't think there is any required action, but feel free to reopen if there is!