Indentation issues in description lists with tagged regions

Open
#1,876 0 comments 0 reactions 0 assignees View on GitHub

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

asciidoc bug

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:

image

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

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from elastic/docs

All issues in elastic/docs

Similar issues

More Ruby issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.