Summary

The specifications use a flavor of Markdown which is compatible with GitHub-flavor but not with strict interpretations of the original spec as used by mkdocs.

In the specifications repository, nested lists use indentation levels of 2 or 3 spaces. The mkdocs interpretation requires 4 spaces for the nesting to be detected.

As a result, nested lists are collapsed leading to confusion about exactly where the nested items should be placed. In some cases, it isn't clear that the items should be nested at all.

Examples:

This is actually a set of four nested lists identifying separate test cases; mkdocs merges them into one flat list: https://specifications.readthedocs.io/en/latest/bson-binary-uuid/uuid/#explicit-decoding

The list of entities on the unified-test-format list is mostly flattened, meaning there's no way to immediately see which entity some fields are part of: https://specifications.readthedocs.io/en/latest/unified-test-format/unified-test-format/#entity  See the "database", "collection", and "session" entities. The last field in the previous entity and the field containing the next entity are only separated by a small amount of extra whitespace.

For more, try a regex search for /^ {1,3}[-*0-9]/ in all markdown files.

Motivation

Who is the affected end user?

Developers who use our public spec documentation, and view it via a local mkdocs installation or via readthedocs.

How does this affect the end user?

Developer confusion in some cases.

How likely is it that this problem or use case will occur?

Developers interested in low-level details will hit this quickly, but others may never refer to the specs.

If the problem does occur, what are the consequences and how severe are they?

The problem will be surprising/confusing at first, but once it's been identified there are easy workarounds: viewing the markdown source directly, or using a different processor like GitHub.

Is this issue urgent?

No

Is this ticket required by a downstream team?

No

Is this ticket only for tests?

Documentation impact only.

Acceptance Criteria

Nested text in existing specs should render as nested in the provided HTML version.

This could be accomplished by modifying the documents or switching HTML generators.

A naive replacement of all indentation leaves some lingering formatting problems, so it's possible a new HTML generator would be a more complete solution. Alternatively, there may be automatic formatting tools we could adopt.