Indentation issues in description lists with tagged regions
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 38/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- ruby
- Domain
- documentation
Research direction
Reproduce the example using the description-list and tagged-region source shown in the issue, including stack-docs/docs/en/stack/index-landinall.adoc and glossary.asciidoc. Compare the generated nesting for the first leader index item with the local cluster item when building through Asciidoctor directly. Done means both items produce matching, correctly nested description-list output.
Written by the indexing model from the issue text.
Description
I think there is a bug in the indentations within description lists. For example, while playing with the Glossary in https://github.com/elastic/stack-docs/pull/1214, I noticed this:

Notice that the description of the first item in the "L" description list (in this case, "leader index") is not indented. [I don't think this bug is specific to our build tools, since the same thing happens when I build via Asciidoctor directly (e.g. asciidoctor stack-docs/docs/en/stack/index-landinall.adoc -r asciidoctor-diagram -a data-uri -D output/docs)].
The specific scenario where this seems to happen is when you're including content from tagged regions in the first item in the description list. Subsequent items have no such indentation issues. For example, here's an example of the source that hits this problem:
[[l-glos]] L::
[[glossary-leader-index]] leader index:::
+
--
include::{es-repo-dir}/glossary.asciidoc[tag=leader-index-def]
--
[[glossary-local-cluster]] local cluster:::
+
--
include::{es-repo-dir}/glossary.asciidoc[tag=local-cluster-def]
--
When you look at the output, you can see that the nesting of dl for the first item doesn't match the second item (i.e. it's nested incorrectly):
<dt>
--
| <span class="term">
| <a id="l-glos"></a> L
| </span>
| </dt>
| <dd>
| <div class="variablelist">
| <dl class="variablelist">
| <dt>
| <span class="term">
| <a id="glossary-leader-index"></a> leader index
| </span>
| </dt>
| </dl>
| </div>
| <p>The source index for <a class="xref" href="terms.html#glossary-ccr">cross-cluster replication</a>. A leader index exists
| on a remote cluster and is replicated to
| <a class="xref" href="terms.html#glossary-follower-index">follower indices</a>.</p>
| <div class="variablelist">
| <dl class="variablelist">
| <dt>
| <span class="term">
| <a id="glossary-local-cluster"></a> local cluster
| </span>
| </dt>
| <dd>
| <p>The cluster that pulls data from a <a class="xref" href="terms.html#glossary-remote-cluster">remote cluster</a> in cross-cluster search or cross-cluster replication.</p>
| </dd>
| </dl>
| </div>
| </dd>
| <dt>
I am going to move away from using description lists this way in the glossary, since I find these indentation issues off-putting. I think it's worth investigating, however, in case this is a real bug that's worth fixing.
- Dominant language
- Ruby
- Stars
- 265
- Forks
- 347
- Avg merge
- 3d 15h
- Merged PRs (30d)
- 2
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from elastic/docs
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 55/100
-
Difficulty 1/5 Under an hour Newbie friendliness 45/100
-
Difficulty 1/5 Under an hour Newbie friendliness 55/100
-
docs-build
Difficulty 4/5 3-5 days Newbie friendliness 45/100
Similar issues
-
user-reported
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
Kong/developer.konghq.com#7316 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
TheOdinProject/curriculum#31408 ·
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
notch8/utk_knapsack#148 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 78/100
Homebrew/homebrew-cask#288729 · 1 comment ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100