11ty / 11ty/docs

Consider naming templates to content

Open
#1,874 5 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
Nunjucks
Stars
547
Forks
726
Avg merge
2h 23m
Merged PRs (30d)
3

Description

When moving from a different CMS or an SSG it is very confusing to learn about Eleventy's templates. While the idea is very solid the naming introduces mental/cognitive effort to understand.
Eleventy operates with templates which can be static Markdown or HTML files, templates which can be dynamic documents that render to certain format and then regular static files. Layouts are the first thing that are closely related to templates understood by the developer and web community.
I understand that it would require alot of code refactoring or maybe not so... The rough idea to consider would be as follows in terms of organization:

  • Themes/layouts with templates understood as JS/HBS/ other rendering-engine-based files,
  • Content files/sources including Markdown/HTML/JSON, including the data files transformed by the former,
  • Static files such as CSs/JS/images/audio/video.

The idea is very solid, but the naming was very confusing at the beginning and it is not so easy to become familiar with the concept when getting started with Eleventy.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No files, tests, or entry points are named. Start by reviewing the documentation's current use of “templates,” “layouts,” content, and static files; done would require agreed terminology and a defined documentation scope.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.