SwarmLab-HowTos/labs/Howtos/asciidoc/_includes/sections.adoc

////
Sections
Introduction
Titles as HTML headings
Auto-generated IDs
Custom IDs
Links
Anchors
Numbering
Numbering Depth

Included in:

- user-manual
////

// tag::intro[]
Sections partition the document into a content hierarchy.
In AsciiDoc, sections are defined using section titles.

A section title represents the heading for a section.
Section title levels are specified by two to six equal signs.
The number of equal signs in front of the title represents the nesting level (using a 0-based index) of the section.

.Section titles available in an article doctype
[source]
----
include::ex-section.adoc[tag=base]
----

.Render section titles
====
include::ex-section.adoc[tag=b-base]
====

TIP: In addition to the equals sign marker used for defining single-line section titles, Asciidoctor recognizes the hash symbol (`#`) from Markdown.
That means the outline of a Markdown document will be converted just fine as an AsciiDoc document.

Section levels must be nested logically.
There are two rules you must follow:

. A document can only have multiple level 0 sections if the `doctype` is set to `book`.
 ** The first level 0 section is the document title; subsequent level 0 sections represent parts.
. Section levels cannot be skipped when nesting sections (e.g., you can't nest a level 5 section directly inside a level 3 section; an intermediary level 4 section is required).

For example, the following syntax is illegal:

[source]
----
include::ex-section.adoc[tag=bad]
----

Content above the first section title is designated as the document's preamble.
Once the first section title is reached, content is associated with the section it is nested in.

[source]
----
include::ex-section.adoc[tag=content]
----

// end::intro[]

=== Titles as HTML headings
// tag::heading[]
When the document is converted to HTML 5 (using the built-in `html5` backend), each section title becomes a heading element where the heading level matches the number of equal signs.
For example, a level 1 section (`==`) maps to an `<h2>` element.
// end::heading[]

=== Auto-generated IDs
// tag::autoid[]
If you don't specify a custom ID for a section, the processor automatically generates an ID from the section's title and assigns it to the section by default.

The ID is derived from the section title as follows:

* Inline formatting is applied (in title substitution order).
* All characters are converted to lowercase.
* The value of the `idprefix` attribute (`+_+` by default) is prepended.
* Character references, HTML/XML tags, and invalid ID characters are removed.
 ** Refer to the https://www.w3.org/TR/REC-xml/#NT-Name[NT-Name] section of the XML specification for a list of valid ID characters.
 ** Prior to 1.5.7, HTML/XML tags were not removed and character references and invalid ID characters were replaced with the value of the `idseparator` attribute (`+_+` by default).
* Spaces, hyphens, and periods are replaced with the value of the `idseparator` attribute (`+_+` by default)
* Repeating separator characters are condensed.
* If necessary, a sequence number is appended until the ID is unique within the document.

For example, the section title `Wiley & Sons, Inc.` produces the ID `_wiley_sons_inc`.
You can customize the replacement characters or toggle ID auto-generation using document attributes.

You can change the ID prefix by setting the `idprefix` attribute.
The value of the `idprefix` attribute must begin with a valid ID start character and can have any number of additional valid ID characters.

[source]
----
:idprefix: id_
----

If you want to remove the prefix, set the attribute to an empty value.

[source]
----
:idprefix:
----

WARNING: If you set the `idprefix` to blank, you could end up generating IDs that are invalid in DocBook output (e.g., an ID that begins with a number) or that match a built-in ID in the HTML output (e.g., `header`).
In this case, we recommend either using a non-empty value of `idprefix` or assigning explicit IDs to your sections.

You can change the word separator using the `idseparator` attribute.
Unless empty, the value of the `idseparator` must be _exactly one valid ID character._

[source]
----
:idseparator: -
----

If you don't want to use a separator, set the attribute to an empty value.

[source]
----
:idseparator:
----

NOTE: When a document is rendered on GitHub, the `idprefix` is set to an empty value and the `idseparator` is set to `-`.
These settings are used to ensure that the IDs generated by GitHub match the IDs generated by Asciidoctor.

To disable the auto-generation of section IDs, unset the `sectids` attribute.

[source]
----
:sectids!:
----

Custom IDs, covered next, are used even if auto-generation of section IDs is disabled.

WARNING: If you disable auto-generated section IDs, and you don't assign a custom ID to a section, you won't be able to link to (i.e., reference) that section.
// end::autoid[]

=== Custom IDs
// tag::custom-id[]
You can assign a custom ID and optional reference text (i.e., label) to a section (see <<anchordef>>).
The custom ID is used in place of the auto-generated ID.
This can be useful when you want to define a stable anchor for linking to a section using a cross reference.
The reference text is used when referencing the ID without specifying explicit text.
This is a good way to centrally manage the automatic reference text that is used to refer to a section.

Here's an example of a section with a custom ID:

[source]
----
include::ex-section.adoc[tag=with-anchor-shorthand]
----

Here's an example of a section with a custom ID and reference text:

[source]
----
include::ex-section.adoc[tag=with-anchor-and-reftext]
----

The ID can be written using the following shorthand (though there's no shorthand yet for the reference text):

[source]
----
include::ex-section.adoc[tag=with-anchor-and-reftext-shorthand]
----

The value of the reftext attribute must be quoted if it contains spaces or commas.

IMPORTANT: Asciidoctor recognizes all valid UTF-8 characters in section IDs.
When using the double square bracket form, the ID must conform to the https://www.w3.org/TR/REC-xml/#NT-Name[XML Name] rules, which means the ID must start with a letter, an underscore, or a colon.
If you're generating a PDF from AsciiDoc using a2x and dblatex, see https://aerostitch.github.io/misc/asciidoc/asciidoc-title_uft8.html[Using UTF-8 titles with a2x] to learn about the required `latex.encoding=utf8` switch to activate this portability.
// end::custom-id[]

=== Multiple Anchors
// tag::multiple-anchors[]

While a section title can only have a single primary ID, as of Asciidoctor 1.5.7, it's possible to register additional anchor points on a section title using inline anchors.
This feature works regardless of whether you assign a custom ID.

Here's how to register additional anchor points when using an auto-generated ID:

.Register additional leading anchor points
[source]
----
== [[secondary-id]][[tertiary-id]]Section Title
----

.Register additional trailing anchor points
[source]
----
== Section Title[[secondary-id]][[tertiary-id]]
----

You can place the anchors anywhere you want within the section title line.
Where you place them is where the anchor will end up in the output, so it's best to put them either at the beginning or the end.
The beginning is the preferred location.

These additional anchor points don't interfere with defining a custom ID.

.Register additional leading anchor points on a section title with a custom ID
[source]
----
[#primary-id]
== [[secondary-id]][[tertiary-id]]Section Title
----

Alternately, you can move the primary ID inline by placing it after the section title, offset by a single space.

.Set the custom ID within the section title
[source]
----
== Section Title[[secondary-id]][[tertiary-id]] [[primary-id]]
----

However, we don't recommend defining the primary ID inline as it's more difficult to read.
// end::multiple-anchors[]

=== Links
// tag::link[]
To turn section titles into links, enable the `sectlinks` attribute.
The default Asciidoctor stylesheet displays linked section titles with the same color and styles as unlinked section titles.
// end::link[]

=== Anchors
// tag::anchor[]
When the `sectanchors` attribute is enabled on a document, an anchor (empty link) is added before the section title.
The default Asciidoctor stylesheet renders the anchor as a section entity (`&sect;`) that floats to the left of the section title.
// end::anchor[]

=== Numbering
// tag::number[]
Asciidoctor allows section numbering to be toggled on and off throughout a document.
You can enable section numbers using the `sectnums` attribute.

[source]
----
:sectnums:
----

NOTE: Asciidoctor still supports the attribute name `numbered` to number sections for backward compatibility with AsciiDoc Python, but the name `sectnums` is preferred.

You can also use this attribute entry above any section title in the document to toggle the auto-numbering setting.
When you want to turn off the numbering, add an exclamation point to the end of the attribute name:

[source]
----
include::ex-section.adoc[tag=num-off]
----

For regions of the document where section numbering is turned off, the section numbering will not be incremented.

Given:

[source]
----
include::ex-section.adoc[tag=num]
----

The sections will be numbered as follows:

[source]
----
include::ex-section.adoc[tag=num-out]
----

Asciidoctor will always curtail incrementing the section number in regions of the document where section numbers are off.

If `sectnums` is set on the command line (or API), that overrides the value set in the document header, but it does not prevent the document from toggling the value for regions of the document.

If `sectnums!` is set on the command line (or API), then the numbers are disabled regardless of the setting within the document.

.Flexible attributes
NOTE: The `sectnums` attribute is referred to as a "`flexible attribute`", which means it can always be changed midstream in the document, even if it is enabled through the API or CLI.
At the time of writing, `sectnums` is unique in this way, though other attributes may receive this special status in the future.

==== Numbering depth

You can restrict section numbering depth by defining the `sectnumlevels` (document header-only) attribute.

[source]
----
include::ex-section.adoc[tag=sectnuml]
----
<1> When the `sectnumlevels` attribute is assigned a value of `2`, section titles with levels 3 through 5 are not numbered (i.e., not prefixed with a number).

When the `doctype` is `book`, recall that level-1 sections become chapters.
Therefore, a `sectnumlevels` of `4` translates to 3 levels of numbered sections inside each chapter.

Assigning `sectnumlevels` a value of `0` is effectively the same as disabling section numbering (i.e., `sectnums!`).
// end::number[]