Skip to content

Commit 4d48e6b

Browse files
committed
Clarify subsection ID syntax in assemblies
1 parent 66d2074 commit 4d48e6b

File tree

1 file changed

+83
-55
lines changed

1 file changed

+83
-55
lines changed

contributing_to_docs/doc_guidelines.adoc

Lines changed: 83 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ link:https://redhat-documentation.github.io/modular-docs/[_Red Hat modular docs
99

1010
[NOTE]
1111
====
12-
These _Documentation guidelines_ are primarily concerned with the modular structure and AsciiDoc / AsciiBinder requirements for building OpenShift documentation. For general style guidelines in OpenShift docs, see the following:
12+
These _Documentation guidelines_ are primarily concerned with the modular structure and AsciiDoc/AsciiBinder requirements for building OpenShift documentation. For general style guidelines in OpenShift docs, see the following:
1313
1414
* Primary source: link:https://www.ibm.com/docs/en/ibm-style[_IBM Style_]
1515
* Supplementary source: link:https://redhat-documentation.github.io/supplementary-style-guide/[_Red Hat supplementary style guide for product documentation_]
@@ -36,17 +36,17 @@ In the Pulsar editor, you can use `Ctrl`+`J` to undo hard wrapping on a paragrap
3636
Every assembly file should contain the following metadata at the top, with no line spacing in between, except where noted:
3737

3838
----
39-
:_mod-docs-content-type: ASSEMBLY <1>
40-
[id="<unique-heading-for-assembly>"] <2>
39+
:_mod-docs-content-type: ASSEMBLY <1>
40+
[id="<unique_heading_for_assembly>"] <2>
4141
= Assembly title <3>
4242
include::_attributes/common-attributes.adoc[] <4>
43-
:context: <unique-context-for-assembly> <5>
43+
:context: <unique_context_for_assembly> <5>
4444
<6>
4545
toc::[] <7>
4646
----
4747
<1> The content type for the file. For assemblies, always use `:_mod-docs-content-type: ASSEMBLY`. Place this attribute before the anchor ID or, if present, the conditional that contains the anchor ID.
48-
<2> A unique (within OpenShift docs) anchor ID for this assembly. Use lowercase. Example: cli-developer-commands
49-
<3> Human readable title (notice the `=` top-level header)
48+
<2> A unique (within OpenShift docs) anchor ID for this assembly. Use lowercase and hyphens, for example: `cli-developer-commands`.
49+
<3> Human readable title (notice the `=` top-level header).
5050
<4> Includes attributes common to OpenShift docs.
5151
+
5252
[NOTE]
@@ -66,8 +66,8 @@ toc::[]
6666
----
6767
====
6868
+
69-
<5> Context used for identifying headers in modules that is the same as the anchor ID. Example: cli-developer-commands.
70-
<6> A blank line. You *must* have a blank line here before the toc.
69+
<5> Context used for identifying headers in modules that is the same as the anchor ID. Use lowercase and hyphens, for example `cli-developer-commands`.
70+
<6> A blank line. You *must* have a blank line here before the `toc::[]`.
7171
<7> The table of contents for the current assembly.
7272

7373
[NOTE]
@@ -269,7 +269,7 @@ If you accidentally create an incorrect symbolic link, you can remove that link
269269
[openshift_cli ~]$ unlink images
270270
----
271271

272-
== Assembly/Module titles and section headings
272+
== Assembly/module titles and section headings
273273

274274
Use sentence case in all titles and section headings. See http://www.titlecase.com/ or https://convertcase.net/ for a conversion tool.
275275

@@ -287,98 +287,126 @@ Do not use backticks or other markup in assembly or module headings.
287287

288288
Do not use special characters or symbols in titles. Symbols and special characters in titles can cause rendering errors in the HTML output.
289289

290-
Use only one level 1 heading (`=`) in any file.
290+
Use only one link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] heading (`=`) in any file.
291291

292-
=== Discrete headings
292+
=== Anchoring titles and section headings
293293

294-
If you have a section heading that you do not want to appear in the TOC (like if you think that some section is not worth showing up or if there are already too many nested levels), you can use a discrete (or floating) heading:
294+
All titles and section headings must have an anchor ID. The anchor ID must be similar to the title or section heading. Do not include line spaces between the anchor ID and the section title.
295295

296-
https://docs.asciidoctor.org/asciidoc/latest/blocks/discrete-headings/
296+
.Example anchor ID and heading
297+
----
298+
[id="configuring-alert-notifications"] <1>
299+
= Configuring alert notifications <2>
300+
----
301+
<1> Anchor ID
302+
<2> Title/section heading
297303

298-
A discrete heading also will not get a section number in the Customer Portal build of the doc. Previously, we would use plain bold mark-up around a heading like this, but discrete headings also allow you to ignore section nesting rules (like jumping from a `==` section level to a `====` level if you wanted for some style reason).
304+
The following anchor IDs also require use of the `_{context}` variable:
299305

300-
To use a discrete heading, just add `[discrete]` to the line before your unique ID. For example:
306+
* **All** headings in module files
307+
* **Only** subsections in assembly files (but not the link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] heading/main title)
301308

302-
----
303-
[discrete]
304-
[id="managing-authorization-policies_{context}"]
305-
== Managing authorization policies
306-
----
309+
When called, the `_{context}` variable is resolved into the value declared in the `:context:` attribute in the corresponding assembly file. This enables cross-referencing of IDs in context to a specific assembly and is useful when a module is included in multiple assemblies.
307310

308-
== Anchoring titles and section headings
311+
[NOTE]
312+
====
313+
The `{context}` variable must be preceded by an underscore (`_`) when declared in an anchor ID.
314+
====
309315

310-
All titles and section headings must have an anchor ID. The anchor ID must be similar to the title or section heading.
316+
==== Anchoring in assembly files
311317

312-
=== Anchoring in assembly files
318+
===== Assembly titles (Level 0 headings)
313319

314-
The following is an example anchor ID in an assembly file:
320+
For the single link:https://docs.asciidoctor.org/asciidoc/latest/sections/titles-and-levels/#section-level-syntax[Level 0] heading (`=`) of an assembly file, **do not** add a `_{context}` variable to the end of the anchor ID.
315321

322+
.Example anchor ID for the Level 0 heading of an assembly file
316323
----
317324
[id="configuring-alert-notifications"]
318325
= Configuring alert notifications
319326
----
320327

321328
[NOTE]
322329
====
323-
Do not include line spaces between the anchor ID and the section title.
330+
This guideline includes an exception to the link:https://redhat-documentation.github.io/modular-docs/#nesting-assemblies[_Red Hat modular docs reference guide_], which shows including the `{context}` variable for Level 0 headings of assemblies as well.
324331
====
325332

326-
=== Anchoring in module files
333+
The anchor ID for the assembly title should match the `:context:` set in the xref:assembly-file-metadata[assembly file metadata].
327334

328-
You must add the `{context}` variable to the end of each anchor ID in module files. When called, the `{context}` variable is resolved into the value declared in the `:context:` attribute in the corresponding assembly file. This enables cross-referencing to module IDs in context to a specific assembly and is useful when a module is included in multiple assemblies.
335+
===== Assembly subsections (Level 1 and lower headings)
329336

330-
[NOTE]
331-
====
332-
The `{context}` variable must be preceded by an underscore (`_`) when declared in an anchor ID.
333-
====
337+
For any Level 1 or lower _subsections_ in an assembly (for example, `==`, `===`, etc.), add a `_{context}` variable to the end of anchor IDs:
334338

335-
The following is an example of an anchor ID for a module file title:
339+
.Example anchor ID for a Level 1 heading (subsection) of an assembly file
340+
----
341+
[id="editing-alerts_{context}"]
342+
== Editing alerts
343+
----
336344

345+
This ensures a unique anchor ID across the repo.
346+
347+
==== Anchoring in module files
348+
349+
You must add the `_{context}` variable to the end of each anchor ID in module files, for any section level:
350+
351+
.Example anchor ID for a module file Level 0 (`=`) heading/main title
337352
----
338353
[id="sending-notifications-to-external-systems_{context}"]
339354
= Sending notifications to external systems
340355
----
341356

342-
The following is an example of an anchor ID for a second level (`==`) heading:
343-
357+
.Example anchor ID for a Level 1 (`==`) subsection heading
344358
----
345359
[id="deployment-scaling-benefits_{context}"]
346360
== Deployment and scaling benefits
347361
----
348362

349363
=== Anchoring "Prerequisites", "Additional resources", and "Next steps" titles in assemblies
350364

351-
Use unique IDs for "Prerequisites", "Additional resources", and "Next steps" titles in assemblies. You can add the prefixes `prerequisites_`, `additional-resources_`, or `next-steps_` to a unique string that describes the assembly topic. The unique string can match the value assigned to the `:context:` attribute in the assembly.
352-
353-
[NOTE]
354-
====
355-
The `prerequisites_`, `additional-resources_`, and `next-steps_` prefixes must end with an underscore (`_`) when declared in an anchor ID in an assembly.
356-
====
357-
358-
The following examples include IDs that are unique to the "Configuring alert notifications" assembly:
359-
360-
*Example unique ID for a "Prerequisites" title*
365+
For anchor IDs of "Prerequisites", "Additional resources", and "Next steps" titles in assemblies, use the prefixes `prerequisites_`, `additional-resources_`, or `next-steps_` followed by the `{context}` variable. Using this variable automatically matches the value assigned to the `:context:` attribute in the assembly, which ensures a unique ID across the repo. Use an underscore (`_`) between the prefix and `{context}` variable.
361366

367+
.Example unique anchor ID for a "Prerequisites" title
362368
----
363-
[id="prerequisites_configuring-alert-notifications"]
369+
[id="prerequisites_{context}"]
364370
== Prerequisites
365371
----
366372

367-
*Example unique ID for an "Additional resources" title*
368-
373+
.Example unique anchor ID for an "Additional resources" title
369374
----
370375
[role="_additional-resources"]
371-
[id="additional-resources_configuring-alert-notifications"]
376+
[id="additional-resources_{context}"]
372377
== Additional resources
373378
----
374379

375-
*Example unique ID for a "Next steps" title*
376-
380+
.Example unique anchor ID for a "Next steps" title
377381
----
378-
[id="next-steps_configuring-alert-notifications"]
382+
[id="next-steps_{context}"]
379383
== Next steps
380384
----
381385

386+
=== Discrete headings
387+
388+
If you have a section heading that you do not want to appear in the TOC (for example, if you think that some section is not worth showing up or if there are already too many nested levels), you can use a discrete (or floating) heading:
389+
390+
https://docs.asciidoctor.org/asciidoc/latest/blocks/discrete-headings/
391+
392+
A discrete heading also will not get a section number in the Customer Portal build of the doc. Previously, we would use plain bold mark-up around a heading like this, but discrete headings also allow you to ignore section nesting rules (like jumping from a `==` section level to a `====` level if you wanted for some style reason).
393+
394+
To use a discrete heading, add `[discrete]` to the line before your unique ID:
395+
396+
.Example in a module
397+
----
398+
[discrete]
399+
[id="managing-authorization-policies_{context}"]
400+
== Managing authorization policies
401+
----
402+
403+
.Example in an assembly
404+
----
405+
[discrete]
406+
[id="olm-restricted-networks-mirroring-catalog"]
407+
== Mirroring a catalog
408+
----
409+
382410
== Writing assemblies
383411
An _assembly_ is a collection of modules that describes how to accomplish a user story. Module content is added to an assembly using the `include` directive. The `include` directive includes contents from another file in the current document. Files can be modules or snippets formatted in AsciiDoc, or another text format such as YAML.
384412

@@ -748,7 +776,7 @@ Some provider-formatted hostnames include IPv4 addresses. An OpenShift Container
748776

749777
== IP addresses
750778

751-
You may include IPv4 addresses from test clusters in examples in the documentation, as long as they are private. Private IPv4 addresses fall into one of the following ranges:
779+
You may include IPv4 addresses from test clusters in examples in the documentation, provided that they are private. Private IPv4 addresses fall into one of the following ranges:
752780

753781
* 10.0.0.0 to 10.255.255.255 (class A address block 10.0.0.0/8)
754782
* 172.16.0.0 to 172.31.255.255 (class B address block 172.16.0.0/12)
@@ -1173,7 +1201,7 @@ docker-registry <none> name=registrypod
11731201
....
11741202
+
11751203
This renders as:
1176-
1204+
+
11771205
> In the following example, the `oc get` operation returns a complete list of services that are currently defined:
11781206
>
11791207
> ----
@@ -1886,7 +1914,7 @@ Additionally, in an assembly, use `==` formatting for the section heading (`== A
18861914

18871915
----
18881916
[role="_additional-resources"]
1889-
[id="additional-resources_configuring-alert-notifications"]
1917+
[id="additional-resources_{context}"]
18901918
== Additional resources
18911919
* link:example.com[IANA example domain for documentation]
18921920
* xref:../installation/installing-the-product.adoc#installing-the-product[Installing the product]
@@ -2202,7 +2230,7 @@ a|
22022230
>
22032231
> `oc apply -f <path_to_configuration_file>/<filename>.yaml`
22042232

2205-
|Use single asterisks for web console / GUI items (menus, buttons, page titles, etc.).
2233+
|Use single asterisks for web console/GUI items (menus, buttons, page titles, etc.).
22062234
Use two characters to form the arrow in a series of menu items (`$$->$$`).
22072235

22082236
a|

0 commit comments

Comments
 (0)