Snapstromegon
commented
11 months ago Hi @caesiumtea, thanks for bringing up that you think the documentation could be improved here.
I think part of the difficulty of writing these docs is, that the 11ty "templates" are in fact templates which can be filled with data which e.g. could be loaded from a CMS. In many usecases (and I think nearly all simpler ones) you actually have the data in your template, so they don't seem like templates anymore (e.g. when you have a markdown file as a template). In addition to this, 11ty is really really really flexibel, so you can add your own templating languages to it, so there isn't a finite list of extensions or languages to use.
Every point you bring up is stated quite clearly in the correct location in the docs, but these locations are not that easy to find, when you don't already know them.
E.g. the special index.html handling is shown in the example "4". A file that creates an index.html (e.g. an index.md or index.html or index.njk) is considered a root of a folder, so it doesn't create a subfolder while every other filename creates one (e.g. README.md creates the page README/index.html). Because of this I think the names index.html and README.md were chosen on purpose.
Either way I agree that the docs can use some improvement here.
Step 4 of Getting Started leaves me still confused about templates. Is every file with content considered a "template"? Looking back on the page now, I see that it does link to the languages page, where one can find a list of file types that can serve as templates--but on my first reading, I was left confused about "so what kind of file would a template be?"
After giving the two examples, it says to "make sure they have the correct file extensions". But without a clearer mention of "here's a list of all the file extensions that a template could be", I was left thinking that a template MUST consist of an HTML file and a MD file.
I think some of my confusion is because, in other software, I'm used to a "template" being only half of the equation--something that still has blanks left in it, that need to be filled in by some other type of content. But it seems like ALL the content is called a template here, no matter where it goes? If that's correct, it might be wise to explicitly state so, to avoid up this confusion.
It's also unclear where templates go--whether they have to be in the project root or whether they can go inside folders. And if they can go in folders, then does Eleventy handle templates in folders differently than ones at the root?
The example is also a bit misleading. If I understand correctly now, index.html and README.md are two separate, unrelated templates, right? I know you say "two template files" but I had initially interpreted that as "two files that make up one template". These are perhaps poor choices of file names too, since they're both files that usually serve a very specific purpose. I can't tell from the example whether index.html is handled in a special way or whether it's just another template. I suggest just using something like "example1.html" and "example2.md" to avoid this confusion. Since I guess we still want to see something right away in our site preview, maybe still include index.html, but perhaps with a note about whether it has any special handling or whether it's just like any other template.