elastic / elastic/docs

Indentation issues in description lists with tagged regions

Open
#1,876 0 comments 0 reactions 0 assignees View on GitHub
asciidoc bug
Dominant language
Ruby
Stars
265
Forks
347
Avg merge
3d 15h
Merged PRs (30d)
2

Description

I think there is a bug in the indentations within [description lists](https://asciidoctor.org/docs/user-manual/#description-list). For example, while playing with the Glossary in https://github.com/elastic/stack-docs/pull/1214, I noticed this:

![image](https://user-images.githubusercontent.com/26471269/85639809-bfc7ee80-b63e-11ea-81fd-492378a096c5.png)

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](https://asciidoctor.org/docs/user-manual/#by-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):

````


--
  |
  | L
  |

  |

  |

  |

  |

  |

  |
  | leader index
  |

  |

  |

  |

  |

The source index for cross-cluster replication. A leader index exists
  | on a remote cluster and is replicated to
  | follower indices.


  |

  |

  |

  |
  | local cluster
  |

  |

  |

  |

The cluster that pulls data from a remote cluster in cross-cluster search or cross-cluster replication.


  |

  |

  |

  |

  |

````

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.

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.