~sircmpwn/sr.ht-discuss

3 3

Suspected Bug in man.sr.ht's Markdown Parser

Details
Message ID
<CCJULCX6Q161.MND2UMI3ULCL@ARCHe-Moritz>
DKIM signature
pass
Download raw message
Hello,

this ticket is regarding – what I assume to be – a bug in the markdown
parsing of man.sr.ht. If you take a look at [1] you can see that the
first line of GLOG_COLOR is not like the others (2 bullet-points
directly after another) while the content of the first bullet-point is
moved above the ToC.

When I add frontmatter, I get a ToC that looks like this:

1. title: "Environment"
2. Environment variables
	GLOG_COLOR
	GLOG_LEVEL
	GLOG_METALOGGER

Only after adding a little prose after the h1, I get the desired
formatting.

1: https://man.sr.ht/~poldi1405/glog/docs/env.md
Details
Message ID
<875yxok265.fsf@halcyon.my.domain>
In-Reply-To
<CCJULCX6Q161.MND2UMI3ULCL@ARCHe-Moritz> (view parent)
DKIM signature
pass
Download raw message
> ... you can see that the first line ... is not like the others (2
> bullet-points directly after another) while the content of the first
> bullet-point is moved above the ToC.

You will need to add a newline after your YAML front matter to correct
the inclusion of your title in the table of contents:

```
---
title: Environment
---

# Environment variables
```

Specifically, you haven't written the front matter in a way that is
identifiable according to the parsing which you see here:

man.sr.ht/mansrht/blueprints/html.py:129

> Only after adding a little prose after the h1, I get the desired
> formatting.

This is part of the design of man.sr.ht, you can see the source here:

man.sr.ht/mansrht/blueprints/html.py:170

But the gist is: if there is a paragraph tag in the rendered markup it
is pulled to the top of the page, ahead of the table of contents.

The reason your list item "ALWAYS, ON, 1" is being pulled to the top of
the page is a result of the nested lists. With a plain list the item
would not be wrapped with another tag, but with the nested lists each
list item is wrapped in a paragraph tag which is then identified as the
first paragraph.

This is all handled by the markdown parser, mistletoe, and you can read
the source for more information on how paragraph tags are suppressed
within list items here:

https://github.com/miyuchina/mistletoe/blob/master/mistletoe/html_renderer.py#L138

If you want to use nested lists then you have already identified the
correct practice to handle the "hoisting" - write some expository text
at the beginning of the document.
Details
Message ID
<CCM37S2074HQ.UUWMZIPEXELZ@ARCHe-Moritz>
In-Reply-To
<875yxok265.fsf@halcyon.my.domain> (view parent)
DKIM signature
pass
Download raw message
Thank you, for the in depth explanation. I might open a ticket with
mistletoe then. I get the design choice and it seems reasonable.
However, moving a bullet point up, or anything after the first
non-paragraph seems like a bug to me.

I consider my question answered. Thanks.
Details
Message ID
<CEH80APQAHDG.15MABZTZBUOC@taiga>
In-Reply-To
<CCJULCX6Q161.MND2UMI3ULCL@ARCHe-Moritz> (view parent)
DKIM signature
fail
Download raw message
DKIM signature: fail
Thanks for bringing this to my attention, and waiting until I could
prioritize it. I have pushed a fix for this issue.
Reply to thread Export thread (mbox)