.editorconfig's use of tabs instead of spaces causes eleventyNavigation to fail

[jayjansheski]

First, thanks for 11ty!

Here's an issue I'm seeing: .editorconfig was changed to use tabs instead of spaces, but that seems to cause eleventyNavigation to fail. (Tabs are forbidden in YAML.)

Here's how the issue can be reproduced:

1. git clone https://github.com/11ty/eleventy-base-blog.git
2. cd eleventy-base-blog
3. npm install
4. Add books/index.md parallel to about/index.md
5. Select and copy the contents of about/index.md to books/index.md, changing key to Books and order to 4. Optionally, change the markdown content. I'm using VSCode on macOS.

layout: layouts/base.njk
eleventyNavigation:
	key: "Books"
	order: 4
---
# Books

I am a person that reads stuff.

6. npm start and visit the site at localhost:8080; notice Books doesn't show up in the menu.

Change the tabs before key and order to spaces and it'll work fine.

[fapdash]

Another example from this repo, changed spaces to tabs in the frontmatter of thirdpost.md (my editor inserts tabs automatically for indentation bc of the .editorconf):

---
title: This is my third post.
description: This is a post on My Blog about win-win survival strategies.
date: 2018-08-24
tags:
	- second tag
	- posts with two tags
---
Leverage agile frameworks to provide a robust synopsis for high level overviews. Iterative approaches to corporate strategy foster collaborative thinking to further the overall value proposition. Organically grow the holistic world view of disruptive innovation via workplace diversity and empowerment.

Error:

[11ty] Problem writing Eleventy templates: (more in DEBUG output)
[11ty] 1. Having trouble reading front matter from template ./content/blog/thirdpost.md (via TemplateContentFrontMatterError)
[11ty] 2. end of the stream or a document separator is expected at line 7, column 2:
[11ty]          - posts with two tags
[11ty]      ^ (via YAMLException)
[11ty] 
[11ty] Original error stack trace: YAMLException: end of the stream or a document separator is expected at line 7, column 2:
[11ty]          - posts with two tags
[11ty]      ^
[11ty]     at generateError (/home/fap/repos/eleventy-base-blog/node_modules/js-yaml/lib/js-yaml/loader.js:167:10)
[11ty]     at throwError (/home/fap/repos/eleventy-base-blog/node_modules/js-yaml/lib/js-yaml/loader.js:173:9)
[11ty]     at readDocument (/home/fap/repos/eleventy-base-blog/node_modules/js-yaml/lib/js-yaml/loader.js:1545:5)
[11ty]     at loadDocuments (/home/fap/repos/eleventy-base-blog/node_modules/js-yaml/lib/js-yaml/loader.js:1588:5)
[11ty]     at load (/home/fap/repos/eleventy-base-blog/node_modules/js-yaml/lib/js-yaml/loader.js:1614:19)
[11ty]     at Object.safeLoad (/home/fap/repos/eleventy-base-blog/node_modules/js-yaml/lib/js-yaml/loader.js:1637:10)
[11ty]     at module.exports (/home/fap/repos/eleventy-base-blog/node_modules/gray-matter/lib/parse.js:12:17)
[11ty]     at parseMatter (/home/fap/repos/eleventy-base-blog/node_modules/gray-matter/index.js:109:17)
[11ty]     at matter (/home/fap/repos/eleventy-base-blog/node_modules/gray-matter/index.js:50:10)
[11ty]     at file:///home/fap/repos/eleventy-base-blog/node_modules/@11ty/eleventy/src/TemplateContent.js:201:13

Sadly I don't think .editorconf spec and implementations support mixing spaces and tabs in the same file type based on further rules?
@jayjansheski Since editorconf plugins usually don't replace existing indentations it's possible to "manually" add indentation with spaces, which works fine, no?

[jayjansheski]

@fapdash yes, easy fix! But I don't understand why it was switched to tabs... seems like it breaks stuff with no upside other than maybe somebody's personal preference?

[fapdash]

@jayjansheski zachleat shared this link back then when the change happened: https://adamtuttle.codes/blog/2021/tabs-vs-spaces-its-an-accessibility-issue/, see e6dc55c#commitcomment-99554645

[jayjansheski]

@fapdash I think that's a fine argument (the argument is that tabs allow people to choose their own indentation width) but if tabs break the build, it seems like an odd change to make. For anyone using an editor that respects .editorconfig (which is the whole point of .editorconfig) they would have to revert this change locally after checking the project out, which is possibly a bigger impediment to working with 11ty than squinting to see the indentation.

[ashleyross]

This wasted multiple hours of my time. New to Eleventy, I could not figure out why even copy-pasted examples of eleventyNavigation refused to appear in the generated site navigation, while the samples included in the repo worked fine. I certainly did not realize that the two-space indentation in the examples was being dutifully replaced with one-tab indentation by my editor, and only happened to spot the difference when eventually viewing a diff that displayed whitespace characters.

On the whole, this is very surprising behaviour. One might hope that modern editors would be aware of YAML front matter and how its formatting rules might contradict those defined in .editorconfig, but as with all software, features don't exist until they're implemented, and neither VSCode nor IntelliJ/WebStorm/etc. currently handle this exception to those .editorconfig rules.

To my mind, there are four options here:

1. Revert the spaces-to-tabs change in e6dc55c
2. Document this gotcha
3. Emit errors during the build for tab-indented YAML
4. Remove .editorconfig

Option 1 is undesirable, as the accessibility argument seems reasonable, so defaulting the template repo to use tabs where appropriate is fair.

Option 2 is straight forward but falls short; people who learn by diving in instead of first reading documentation will still have their finite lives wasted as they clone the samples in this repo and hit this problem (cf. non-western language users repeatedly having problems with the default Eleventy slugify library's lack of support for their language).

Option 3 requires work to implement and still has shortcomings; people will only learn about the problem when running a build, increasing cycle time. Also, unless this error explicitly signposts .editorconfig, people might be baffled as to why their editor is behaving in this way.

Option 4 is easy and keeps to the principle of least surprise; only people who go on to explicitly create their own .editorconfig and configure it to use tabs are likely to encounter this problem in future.

Ideally, options 2, 3, and 4 would all be applied to provide complete coverage for this situation. However, in the short term, option 4 would resolve this gotcha for the majority of people starting out with this template repo, with Option 2 being a possible fast follow to help anyone using a version of this repo pre-Option 4.

[zachleat]

Marginally related to 11ty/eleventy#2126 which has better error messaging for tabs in YAML front matter.

Additionally, we’ll mitigate some of this by swapping to js front matter in these files in v9: 1ad494c

I’m also open to removing .editorconfig too, unless there are any good cases to keep it around

[zachleat]

Eleventy Base Blog v9 has shipped

[ashleyross]

Thanks for the update!

Option 3 definitely seems to be ticked by 11ty/eleventy#2126

Regarding option 4, if YAML is the defacto standard for frontmatter, perhaps it might be best to go ahead with removing .editorconfig too, given the unexpected interaction it is causing.

The mitigation applied in 1ad494c likely wouldn't assist people migrating content in from other systems that use YAML frontmatter, and they may well run into this issue as they update their existing YAML frontmatter if their editor obeys .editorconfig.

Even with 11ty/eleventy#2126 catching the issue at build time, they would have to constantly fight their editor inserting tabs in the YAML, and avoiding this issue entirely by removing .editorconfig would reduce overall cycle time.