Flesh out the explanation of templates in Getting Started
Nobody has claimed this yet.
- Dominant language
- Nunjucks
- Stars
- 547
- Forks
- 726
- Avg merge
- 2h 23m
- Merged PRs (30d)
- 3
Description
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.
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with Step 4 of the Getting Started page and follow its link to the languages page. Clarify what counts as a template, how file extensions and folders work, and whether index.html receives special handling; revise the example if appropriate. Done means a newcomer can identify valid template files, their locations, and the relationship between the example files.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 48/100