Skip to content

Should markdown2ctags detect YAML frontmatter? #10

Closed
@DancingQuanta

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

changed the title YAML frontmatter Should markdown2ctags detect YAML frontmatter? on Nov 30, 2017
jszakmeister

jszakmeister commented on Nov 30, 2017

@jszakmeister
Owner

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

DancingQuanta commented on Nov 30, 2017

@DancingQuanta
Author

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

jszakmeister commented on Dec 2, 2017

@jszakmeister
Owner

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

DancingQuanta commented on Dec 3, 2017

@DancingQuanta
Author

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


---
title: My Wiki
tags: 
author: Andrew Tolmie
---

# Section 1

## Section 1.1

# Section 2

## Section 2.2

And using Tagbar, it's results are as shown

" Press <F1>, ? for help

  author: Andrew Tolmie : section

▼ Section 1 : section
    Section 1.1 : section

▼ Section 2 : section
    Section 2.2 : section

The yaml is still there in the tag window and I checked site-packages for markdownctags and it is 0.2.1.

DancingQuanta

DancingQuanta commented on Dec 3, 2017

@DancingQuanta
Author

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

DancingQuanta commented on Dec 3, 2017

@DancingQuanta
Author

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

jszakmeister commented on Dec 3, 2017

@jszakmeister
Owner

Would it be great to add a help option and version option so I can check quickly what version it is.

That feature has been there from day 1. Use --help and --version.

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.

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

DancingQuanta commented on Dec 3, 2017

@DancingQuanta
Author

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

jszakmeister commented on Dec 5, 2017

@jszakmeister
Owner

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.

added a commit that references this issue on Oct 6, 2018

Fix #10: skip the front matter, if present

2c74fdd
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions

      Should markdown2ctags detect YAML frontmatter? · Issue #10 · jszakmeister/markdown2ctags