Surprising Heading.content

[PatrickMassot]

In the following code, I was expecting to see my two titles printed.

from mistletoe import Document                                                            
                                                                                                         
doc = Document("""# My first title                                                        
Some text.                                                                                               
                                                                                          
# My second title                                                                         

Some more text.
""")                                                                                                     
                                                                                          
print(doc.children[0].content, doc.children[2].content)

But this prints the second title twice. To get the result I expected, I need to write print(doc.children[0].children[0].content, doc.children[2].children[0].content). I don't know if this is a bug or expected behavior, but I justed wasted half an hour on this.

[pbodnar]

Hi, this really is the expected behavior. Because by writing doc.children[0].content you access a somewhat-private, class-scoped helper property content of the Heading class. So yes, accessing the parsed text by doc.children[0].children[0].content instead is the correct way.

If you want to know how to access the parsed structure, the best is probably to run mistletoe with the ASTRenderer against your markdown text. With this, you'll get a nice tree view of what got parsed:

{
  "type": "Document",
  "footnotes": {},
  "children": [
    {
      "type": "Heading",
      "level": 1,
      "children": [
        {
          "type": "RawText",
          "content": "My first title"
        }
      ]
    },
    {
      "type": "Paragraph",
      "children": [
        {
          "type": "RawText",
          "content": "Some text."
        }
      ]
    },
    {
      "type": "Heading",
      "level": 1,
      "children": [
        {
          "type": "RawText",
          "content": "My second title"
        }
      ]
    },
    {
      "type": "Paragraph",
      "children": [
        {
          "type": "RawText",
          "content": "Some more text."
        }
      ]
    }
  ]
}

(BTW You should remove trailing spaces from your example markdown code - or one gets Code blocks parsed otherwise.)

[PatrickMassot]

Ok, thanks for the explanation. Feel free to close this issue, but I think some more documentation would be helpful here. I don't think it is such an exotic thing to do (I wanted to make the first h1 into the title of the whole thing in some metadata associated to the file).

[pbodnar]

@PatrickMassot, you're welcome. :) I'm not this project's maintainer though, so I can't close this issue. Anyway, I agree with you this could be documented, probably on the Contributing page...

[pbodnar]

Now when I can contribute to the project directly, I added a corresponding chapter Understanding the AST in 14a0d9e. I hope that could suffice. Suggestions welcome. :)