Add a configuration in DocPad to use CSON by default

Tags: #<Tag:0x00007f10eadd6768> #<Tag:0x00007f10eadd6628>


Currently in DocPad, metadata frontmatter is formatted using YAML by default, and if you want to use CSON instead, you have to write --- cson at the beginning for each file.

I suppose this is useful as a way of reminding the developer which format the document’s metadata uses. But I also think it would be nice, for those who always prefer CSON over YAML, if we could instead set the default frontmatter format in the configuration file.


Let me think about it.

My initial thoughts on this would that it would increase incompatibility between unspecified document meta formats (if one person copies meta data in CSON default format, and injects it into a website of YAML default format). The idea to solve this would be for everyone, even the YAML users, to have to specify explicitly the meta data formats for each document, as CSON users have to do currently, so there is no default. The reason why this was done by default, was that YAML is more or less a defacto standard among SSGs and for people moving from another SSG to DocPad, not having YAML is quite the conversion cost of their time.

I mean, it would be easy enough to make it optional, but then as maintainers we also have to write tests and take into account user experiences and support requests. We could probably make it an unsupported feature… however should we really be encouraging such things that aren’t what we consider best practices?


I would think that a small development team could remember which metadata format they’re using, and that a large community project would have someone check before merging in changes. But currently I am only using DocPad by myself for my personal web sites, and I’m tracking everything in git, so I may biased toward that use case.

I understand why you’d implement YAML, I just don’t like it as much; the way they format code examples in the documentation strikes me as awfully opaque, and the way of writing lists and multiline strings is a little weird. Basiclaly I just like CSON better, and I’d mainly prefer using a config over adding --- cson to the frontmatter for aesthetic reasons. It doesn’t significantly affect DocPad workflow either way.

I agree that implementing “unsupported” features is probably a bad idea, though.


I think this will break expectations too much, which will break cross compatibility with a lot of tooling. As such, YAML will always be the default. Even then, it would be nice to be able to always require the parser, however nearly all other SSGs just use YAML, which is a pity. They could use docmatter to support it all.