Fixed: "missed comma between flow collection entries" in Docusaurus Front Matter
A check on this site refused two blog posts with front matter does not parse, and then missed comma between flow collection entries. Every line in those lists ended with a comma. The problem was a # in one post and [] in the other. Both mean something to YAML, even inside a list of plain words.
What I Was Doing
I'd written new posts for this Docusaurus site, with their keywords in a YAML list in the front matter, the way the other posts have them. One post's keywords included ###, the separator in an .http file. Another had an error message with system.attribute[] in it. Then I ran the site's check on its posts, yarn check:images. It reads each post's front matter with js-yaml, the YAML package Docusaurus itself uses.
What I Expected
A list of keywords is only words, so I expected it to pass.
What I Got
Two posts failed. Here are the same lines in two small files, read with the same js-yaml:
missed comma between flow collection entries (7:5)
4 | keywords:
5 | [
6 | http file request separator ###,
7 | postman alternative vs code,
---------^
8 | ]
missed comma between flow collection entries (6:51)
6 | ... object of type system.attribute[] ienumerable,
-----------------------------------------^
What I Checked
Where the arrow points. In the first case, it points at the line after the keyword, and that line looks fine. So the problem had to come from what's before it.
What the commas mean here. A list written with [ ] is what YAML calls a flow collection, and the commas separate its entries. The parser was saying that it had reached a new entry with no comma before it, though I could see one on the line above.
The YAML specification. It explains both. On comments: "Comments must be separated from other tokens by white space characters." And on plain words in a list: "inside flow collections, or when used as implicit keys, plain scalars must not contain the '[', ']', ', ' and ',' characters."
Why It Happens
The ### case. A # after a space starts a comment, which runs to the end of the line. So ###, took the comma with it, and the parser saw one keyword run into the next, with no comma between them. That's why the message points at the next line.
The [] case. Inside a [ ] list, [ and ] have a meaning of their own, so a ] in the middle of a word is read as the end of the list, and what follows has no comma before it.
A # with no space before it is fine, which is why .net c# works in this site's keywords.
The Fix
Take the characters out, if the keyword doesn't need them. That's what I did, since a search phrase doesn't need ###:
keywords:
[
http file request separator ###,
unable to cast object of type system.attribute[] ienumerable,
]
keywords:
[
http file request separator,
unable to cast object of type system.attribute ienumerable,
]
Quote the Value
If you need those characters, put the value in double quotes, and YAML reads it as text:
keywords:
[
"http file request separator ###",
"unable to cast object of type system.attribute[] ienumerable",
]
["http file request separator ###","unable to cast object of type system.attribute[] ienumerable"]
After the Fix
yarn check:images reads every post, and the build goes through:
Scanned 501 markdown file(s) in blog, docs, src.
No local image references.
Common Mistakes
| Mistake | What happens | Do this instead |
|---|---|---|
| Looking for the missing comma on the line it points at | That line is fine | Read the line before it |
| Adding another comma | ###,, is still a comment | Remove or quote the # |
A keyword with a comma in it, such as results<ok, notfound> | No error, but it becomes two keywords | Reword it, or quote it |
A keyword with : , such as property: attribute | It's read as a key and a value | Reword it, or quote it |
Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| The arrow points at a line that looks right | A comment on the line before it swallowed the comma | Look for # above |
| The arrow points in the middle of a word | A [, ], { or } in that word | Quote the value |
| Only some posts fail | Only those have the character | Search your keywords for #, [, ] |
| It parses, and the keyword is cut short | A # with no comma needed after it | Quote the value |
FAQ
Why does c# work and ### not?
The space. The specification requires white space before a comment, so c# is text, and ### is a comment.
Would a list with dashes avoid this?
The bracket characters are only limited inside a flow collection, so yes for those. A # starts a comment there too, so that one still needs quotes.
Conclusion
missed comma between flow collection entries usually doesn't mean you left out a comma. A # on the line above has turned your comma into a comment, or a [ or ] inside a word has confused the list. Remove the character, or put the value in double quotes.
Additional Resources
- YAML 1.2.2 specification — comments and flow collections.
- Blog front matter in Docusaurus — the
keywordsfield.
