TOML is not very friendly for non-technical users

[jwatt]

I've been trying to teach some older non-technical users how to use TOML front-matter for a simple recipe site that I'm putting together. This front-matter might look something like this:

[extra]
title = "Traditional \"Scottish\" porridge"
description = """A traditional Scottish version of porridge made using
  water and salt.

  If you need instructions on how to make porridge, you're probably not a
  traditional Scot. ;-)  We recommend milk instead of water in that case.
  """
servings = 1
prep-time = "5 minutes"
ingredients = [
  "40 g oats",
  "250 ml water",
  "pinch of salt",
  ]
directions = [
  "Add all the ingredients to a saucepan.",
  """Stirring frequently, cook on a medium heat until the porridge thickens
    and becomes...porridgy.""",
  "Serve.",
  ]
[extra.nutrition]
  fat = "1 g"
  carbs = "30 g"
  protein = "4 g"

I've had quite a lot of trouble getting them to feel comfortable with this, so I tried them with YAML instead, which for comparison would be:

extra:
  title: Traditional "Scottish" porridge
  description: A traditional Scottish version of porridge made using water
    and salt.

    If you need instructions on how to make porridge, you're probably not a
    traditional Scot.  ;-) We recommend milk instead of water in that case.
  servings: 1
  prep-time: 5 minutes
  directions:
    - Add all the ingredients to a saucepan.
    - Stirring frequently, cook on a medium heat until the porridge
      thickens and becomes...porridgy.
    - Serve.
  ingredients:
    - 40 g oats
    - 250 ml water
    - pinch of salt
  nutrition:
    fat: 1 g
    carbs: 30 g
    protein: 4 g

There are a bunch of issues with the TOML (demonstrate in the TOML example above) that when taken together are making them really unhappy:

• In general there's a bunch of syntax that non-technical users aren't used to dealing with.
• As a programmer, quoting text seems normal to me, but to them it seems like an unnecessary irritation and visual clutter.
• The need to quote text also means that they would need to remember to "escape" quote marks using a backslash, and that probably isn't going to happen. :-/
• Requiring different quoting for single line text and multi-line text (triple quotes) seems to them to be gratuitous, and will likely be error prone.
• For lists of strings, in addition to the quoting, adding in the idea that trailing commas separate list items, and that square brackets have to "wrap" a list isn't going down well. They much prefer to forget all that and just begin each list item with the intuitive looking "-" marker used by YAML.
• Getting more nitty now, but they also don't like the use of "=" to associate values ("its not maths"), and prefer ":".

They find the YAML considerably cleaner/less confusing/more intuitive, and now that I've shown them that they simply can't understand why anyone would use TOML. (Which, for our schema and usage scenario, seems valid.)

YAML of course isn't without issues. Specifically I'd be worried about the potential for them to mess up the (semantically significant) indentation. However, they're pretty adamant that if that's the only thing they'd need to worry about then they could get that right, and that YAML would be by far the better choice for them. (In fact - if I'm going to ask them to enter their recipes in a text format - they think the indentation would be a good thing, since it makes things more readable.)

[jwatt]

It's also worth noting that of the five most popular static generators (as per https://www.staticgen.com/) that use page front-matter like Gutenberg, all five support YAML front-matter, while only two of them support TOML:

• Jekyll
  • YAML
• Hugo
  • YAML, TOML, JSON
• Hexo
  • YAML, JSON
• VuePress
  • YAML, TOML, JSON
• Metalsmith
  • YAML

Cobalt also only supports YAML.

So I'm guessing I'm far from the only one to have a usage scenario where YAML seems like a better fit for the content editors of a statically generated website.

[jwatt]

(And of course supporting YAML would make it easier to migrate from these other static generators to Gutenberg.)

[piedoom]

I believe this might be a duplicate of #189 (I'm not a maintainer but I follow the project)

[jwatt]

Hmm, I guess so, but the reason given for closing that issue (YAML "not being human readable") seems completely at odds with the example given above. My non-technical users certainly feel very strongly that it's 100% the other way around.

[jwatt]

Although also it's primarily the authoring issues (listed above) rather than readability that are the problem.

[Keats]

So I kind of agree that TOML is not that great (I must have been missing the Obvious part from the name, even started working on another language to fix some of my issues with it: https://github.com/Keats/scl) but I find YAML to be very easy to make mistakes in compared to TOML, granted the kind of YAML file I was trying to debug at the time of #189 were more like https://github.com/Keats/gutenberg/blob/master/sublime_syntaxes/TypeScript.sublime-syntax . I spent a good 2 hours before realising one line was missing one level of indent and had other various indentation issues while using Ansible.

I can totally see how TOML would be confusing for non-programmers though but adding it would also mean allowing a config.yaml and merging together toml/yaml together for themes. I'm less categoric about it but still not thrilled about the idea.

[jwatt]

I find YAML to be very easy to make mistakes in compared to TOML

Yes, I share this concern. The lack of delimiter characters might make YAML feel much nicer to author for some users, but it also means the parser is less able to point you to the location of any mistakes (unless you use a schema?). It certainly doesn't seem suitable for very large files (like TypeScript.sublime-syntax) where spotting indentation issues will be a huge pain.

For smaller sets of structured data like you'd find in Gutenberg's config files and front-matter I'm hopeful that in practice mistakes are less likely/easier to spot, and therefore the trade-off is a worthwhile one. Mostly it's the fact that the other static generators heavily favor YAML that gives me that hope, since otherwise they'd presumably have moved to favor something else. (Even the generators that support other formats favor YAML in their docs.)

[Keats]

If someone is willing to add YAML as an alternative to toml i would probably take it now but it needs to cover every single use of toml (date/datetime types, config file, merging of themes and config etc)

[Keats]

I've seen this article yesterday https://arp242.net/weblog/yaml_probably_not_so_great_after_all.html that kind of sums up my thoughts about YAML and even taught me that yes/no an a few other strings were automatically parsed as boolean for some reason...?
Either way if it is added, YAML should not be the recommended language, TOML still is and the docs should still use TOML.

[jwatt]

even taught me that yes/no an a few other strings were automatically parsed as
boolean for some reason

Yes, that's the top "stupid feature" on the StrictYAML FAQ which also lists a bunch of other things (a very interesting doc). I filed an issue in rust-yaml to consider adding an option to restrict parsing to the StrictYAML variant, and someone there commented that at least the yes/no thing is no longer supported in YAML 1.2 which is what rust-yaml aims to implement.

[Keats]

Any YAML support would probably need to use serde though, in order to keep things simple

[jwatt]

Sure. (serde_yaml uses yaml-rust under the hood though, so yaml-rust would still be the place to implement StrictYAML support if that was desirable.)

[devurandom]

Some thoughts on this:

• For the front matter, you don't have to decide on one format. +++ on the first line means TOML and --- on the first line means YAML.
  • Support for the pandoc-style front matter delimitter (... after the front matter) would be great! It could even be used generically for both formats.
  • Supporting both TOML and YAML would make it even easier to switch between different site rendering tools (e.g. from Hugo to Gutenberg)
• For config.toml, you could glob for config.* and then try config.toml followed by config.yaml, and in the end output Using config file {choice}, ignoring: {list...}, so that the user will always be informed which one was chosen and which not.
  • That way you don't have to go into merging multiple files, potentially creating a lot of confusion.

[Keats]

That way you don't have to go into merging multiple files, potentially creating a lot of confusion.

You still need to merge configs if the user is using a theme.

I like the --- idea for YAML!

Support for the pandoc-style front matter delimitter (... after the front matter) would be great!

I've never used pandoc, what does this mean? Just having ... in a line after the front-matter to delimit it?

[devurandom]

You mean theme.toml and config.toml need to be merged?

Regarding ...: Yes, exactly. The YAML metadata block (i.e. front matter) starts with --- and ends in .... The same delimiter could be used for TOML as well: Start with +++ and end with .... That makes the beginning and end even more clear, IMO. For an example look at the documentation of the Pandoc yaml_metadata_block extension, which is active by default. Pandoc supports having metadata blocks at arbitrary locations in the document, which would go way too far for Gutenberg, IMO.

[mtsr]

I'd like to suggest a different way of selecting the front-matter language. Why not use a Markdown code block with a language indicator? A TOML front-matter would then be wrapped in

```toml
<example>
```

YAML would be

```yaml
<example>
```

One of the big upsides of this syntax would be that it renders much more pleasingly in a preview. And parsing should be as simple as grabbing the first code block from the post (although this does mean a post cannot skip the front-matter and start with a code block).

What do you think?

[devurandom]

On Sunday, 9 September 2018 22:45:39 EAT Jonas Matser wrote: One of the big upsides of this syntax would be that it renders much more pleasingly in a preview. And parsing should be as simple as grabbing the first code block from the post (although this does mean a post cannot skip the front-matter and start with a code block). What do you think?

I think that the `---` and `+++` blocks for metadata are already pretty well established. In fact they are around for such a long time that I think, if the preview bothers you, the viewer should be taught about them instead.

[naturallymitchell]

Might zola (gutenberg) switch to scl?

I'm about to start using it, so it'd be great to see another app with it.

[Keats]

It might be possible in the future but SCL is still in flux imo and shouldn't be used that much yet

[mash-graz]

I'm really not a fan of YAML and there is no good safe yaml library in Rust I believe.

well -- i' personally don't like TOML and somehow got used to YAML, because it's used for so many really useful tools... but in this particular case, matters of individual taste shouldn't be decisive. it's more a serious question of compatibility.

i have used serde for some projects and would see it as one of the best multiformat parsers available.
for cases like this, where you have to support various formats, you can hardly find a better solution, because you can support a bunch of formats by the same interface.

[mash-graz]

although it's more related to #498, there is now a patched version of gutenberg available, which supports YAML at least in the front matter for compatibility reasons:

https://gitlab.com/mash-graz/gutenberg/commit/1c6b8addb8ac4497aa25639a6a542ee356cd971

i hope, it will find it's way into the upstream version.

[travismiller]

My 2 cents…

• Front matter: YAML would be helpful for content migrations and possibly for buy-in from some authors.
• Config: since config.toml and theme.toml are "platform" level specific, I think it not important to support YAML there.
• Regarding ```toml, ```yaml: As @devurandom already said, the current +++ and --- identifiers are well established for front matter. Plus that introduces confusion as those could be used for legitimate formatted code within the content. Yes, the viewer should handle any formatting. https://docs.gitlab.com/ce/user/markdown.html#front-matter

[focusaurus]

@jwatt my suggestion would be pick a format that works for you and your content authors and then script converting that to TOML front matter during a pre-build script. I'd argue any flavor of "edit text files" is generally considered unfriendly to non-technical users and that's why we have WYSIWYG content management systems. zola is not that.

I would definitely vote to not add YAML support to zola. I think YAML is very much out of harmony with the rust ecosystem, and for good reasons around correctness, consistency, robustness, automagic, and security. The line between a static site generator plus blog engine and a CMS or special-purpose site starts to get slippery quickly.

[southerntofu]

Hi, maintainers! We are currently rewriting the Tildeverse RFC website and we would love to use Zola. However for historical reasons we would like to keep our content with a ----delimited YAML frontmatter.

I understand there are concerns with YAML. I also understand Zola would highly recommend to use TOML. But couldn't we have YAML-frontmatter support for just pages & sections on a best-effort basis? The docs and Github issue template could mention potential issues with YAML and instruct to try a TOML equivalent before filing an issue.

Also @mash-graz has already implemented YAML support on their side showing a YAML integration is not too complicated via the excellent serde_yaml crate. Could you maybe review that patch so we know how to move forward on this issue?

Thanks!

[mash-graz]

Also @mash-graz has already implemented YAML support on their side showing a YAML integration is not too complicated via the excellent serde_yaml crate. Could you maybe review that patch so we know how to move forward on this issue?

it's completely up to the maintainers of the project to accept this kind of user requests and suggested patches. we simply have to accept it resp. can not change it.

but the way, how this issue got handled by the zola developers at least opened my eyes! :(

i really like the idea of "free" software! software, where users are able and wellcome to express and satisfy their needs by writing feature requests or more or less trivial code contributions. but rigid dictatorship and zero tolerance against deviating opinions, like zolas stupid YAML-hostility, simply isn't compatible with this idea of freedom and shared open software development!

therefore i stopped using this software after this frustrating experience and utilize other (non-rust based) static site generators again.

[Keats]

But couldn't we have YAML-frontmatter support for just pages & sections on a best-effort basis? The docs and Github issue template could mention potential issues with YAML and instruct to try a TOML equivalent before filing an issue.

I'm not a big fan of having to mix 2 configurations languages in the same project so I would rather have the YAML being available everywhere (config & theme). On the other hand, the less YAML the better so limiting it to front-matter is better but hard to argue against extending it.
I would really prefer to have Strict YAML though, is there an existing strict yaml crate with serde parsing?

Could you maybe review that patch so we know how to move forward on this issue?

I would rather have that coming in a fresh PR, that patch is too old.

i really like the idea of "free" software! software, where users are able and wellcome to express and satisfy their needs by writing feature requests or more or less trivial code contributions. but rigid dictatorship and zero tolerance against deviating opinions, like zolas stupid YAML-hostility, simply isn't compatible with this idea of freedom and shared open software development!

I think you completely misunderstand the concept of free software then. It has nothing to do with accepting every single feature request just because someone wrote a patch for it. Opinionated software is good, I don't want to deal with 200 options as a user and even less as support/maintainer. It's done on my free time and I am completely free to accept or reject any features. Something could make the point as you on why it's "stupid" to be against JSON front-matter. Or UCL. Or HCL. Or Hocon. Or SCL. Yet it is still free software.

therefore i stopped using this software after this frustrating experience and utilize other (non-rust based) static site generators again.

Great!

[MicahZoltu]

While this is "yet another incompatibility" I'm surprised this hasn't been brought up previously in this discussion: GitHub doesn't render toml nor understand the +++ syntax. I suspect that a lot of users are storing their markdown in GitHub for version control and utilizing GitHub's built-in tooling for editing/previewing/reading. In such cases, the change to toml breaks page rendering in the GitHub interface (first is yaml, second is toml):

As others have said, this isn't an issue of "preference of yaml" (in fact, I kind of hate yaml) but rather an issue of compatibility with other very popular tools in the ecosystem.