Closed
Description
YAML frontmatter included in a markdown document is marked by triple dashes above and below the YAML.
---
title: Document title
---
markdown2ctags
interprets the last yaml item as a section title simply because that line is just above the triple dashes.
Solution suggestions:
- Check for any pairs of triple dashes and ignore them
- Set lower limit of number of characters needed to form a setext title to four.
Activity
jszakmeister commentedon Nov 30, 2017
Well, I wouldn't call this a feature of markdown (see John Gruber's original spec here) nor is it in the CommonMark spec, but I realize that this is something tools have adopted (Jekyll, for example).
Jekyll front matter states that it must be right at the top of the file, so it's probably best that we look for the triple dash right away, and if it's there slurp the data until another triple dash and then process as normal.
I don't really consider this a bug since it's not in the markdown specs, but I do think it's a nice enhancement.
DancingQuanta commentedon Nov 30, 2017
Of course it is not a feature of original markdown and I am working my way through various tools to write a wiki in markdown or restructuredtext. Unfortunately there are a number of flavours of markdown and additions such as YAML frontmatter.
However with pandoc and jekyll, YAML frontmatter is useful for adding metadata to the markdown documents.
jszakmeister commentedon Dec 2, 2017
I added a simple fix for this. v0.2.1 should do the trick. Let me know if you run into problems. If you do, please include a sample of what is failing.
DancingQuanta commentedon Dec 3, 2017
Would it be great to add a help option and version option so I can check quickly what version it is.
I tried a test document
And using Tagbar, it's results are as shown
The yaml is still there in the tag window and I checked
site-packages
for markdownctags and it is 0.2.1.DancingQuanta commentedon Dec 3, 2017
Oh the issue is fixed if I removed the blank line before the YAML block.
Now, I have been using this blank line before YAML block for years and I cannot remember why. So I need to investigate this blank line to make sure it is not important.
DancingQuanta commentedon Dec 3, 2017
I will accept the fix and ensure that I do not introduce the blank line before the YAML block. I do not have time to investigate the reason why I used a blank line preceding the block and so I will see if I break something later on.
Oh and 'pandoc' allows for multiple YAML blocks in a document and I have no idea who will have multiple YAML blocks. More details here
jszakmeister commentedon Dec 3, 2017
That feature has been there from day 1. Use
--help
and--version
.I wasn't sure about what to do with leading blank lines (and what should be considered blank... is it blank if it only contains whitespace?). The few things I looked at said that the
---
had to be at the top of the file. I'm definitely not trying to work in every situation, especially since every tool does something a little different. On the other hand, slurping a few blank lines in the beginning shouldn't be too bad as long as there seems to be a reasonable consensus that it was what most of the formats do.There is also, perhaps, concern about things like the vim settings being embedded into the file too. I also don't want to treat any occurrence of
---
as a YAML block, since it's possible for it to be a heading. For now though, I think the answer is good enough. I'll think about it more though, and if you find other tools that support this kind of feature, knowing what they expect would be nice.DancingQuanta commentedon Dec 3, 2017
Yes, there shouldn't be any blank line preceding the YAML block at top of the file. I just can't remember why I added a blank line to each document I wrote.
jszakmeister commentedon Dec 5, 2017
I made the expectations a little less strict. You can have multiple YAML blocks (pandoc supports this), and have blank lines in between everything. Once it sees a like that is not in the front matter, then it expects to see nothing but Markdown from that point on. I think it's about as flexible as I can make it, expect by ignoring whitespace-only lines.
Fix #10: skip the front matter, if present