Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix formatting of continued list #401

Merged

Conversation

emlun
Copy link
Contributor

@emlun emlun commented Feb 12, 2025

The continued list in section 6.6.3.1 was not being rendered as a list but as a continuation of the preceding paragraph. Adding the blank line makes it render as a list, but instead breaks the continued item numbering in MkDocs. Pandoc respects the starting number of the continued list, but MkDocs does not by default. This therefore requires the sane_lists MkDocs extension.

Enabling the sane_lists extension could have unintended consequences, so I compared the "main" ARF page of the rendered MkDocs sites side by side to check. I found only one place affected apart from the intended one in 6.6.3.1, namely a nested bullet point list in section 6.6.3.9 which was being rendered as numbered items of the parent list. This list formatting was broken by enabling the sane_lists extension, but fixed by indenting the nested lists to 4 spaces instead of 3.

The continued list in section 6.6.3.1 was not being rendered as a list but as a
continuation of the preceding paragraph. Adding the blank line makes it render
as a list, but instead breaks the continued item numbering in MkDocs. Pandoc
respects the starting number of the continued list, but MkDocs does not by
default. This therefore requires the [`sane_lists`][1] MkDocs extension.

Enabling the `sane_lists` extension could have unintended consequences, so I
compared the "main" ARF page of the rendered MkDocs sites side by side to check.
I found only one place affected apart from the intended one in 6.6.3.1, namely a
nested bullet point list in section 6.6.3.9 which was being rendered as numbered
items of the parent list. This list formatting was broken by enabling the
`sane_lists` extension, but fixed by indenting the nested lists to 4 spaces
instead of 3.

[1]: https://python-markdown.github.io/extensions/sane_lists/
@skounis
Copy link
Contributor

skounis commented Feb 13, 2025

This list formatting was broken by enabling the sane_lists extension, but fixed by indenting the nested lists to 4 spaces instead of 3.

3 spaces is not officially supported by markdown

@emlun
Copy link
Contributor Author

emlun commented Feb 13, 2025

3 spaces is not officially supported by markdown

Indeed. But it's easy to end up with 3-space indentation when line-breaking a numbered list item, as 1. for example is 3 spaces of displacement. I therefore prefer to prepend a space so the item contents line up at 4 spaces indentation:

Paragraph text

 1. List text
    More text in the same list item

@paolo-de-rosa paolo-de-rosa merged commit b5cd83a into eu-digital-identity-wallet:main Feb 14, 2025
@emlun emlun deleted the list-formatting branch February 17, 2025 11:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants