Switching between different templating options in the same doc

[hxlnt]

The docs include several references to 11ty.js files, but I can't find any part in the docs that actually document them for beginners. Some questions a beginner might have include:

• What is an 11ty.js file for?
• Are 11ty.js files meant to be generated, copy-and-pasted from somewhere, or created from scratch?
• Do 11ty.js files undergo transformation, or are they just "regular JS files?"
• Are its contents automatically picked up, or does the file need to be referenced or added to the project in some way?
• Is the filename significant?
• Do I need an 11ty.js file?
• What must be included in at 11ty.js file in order for it to work? Is there a boilerplate?

My particular scenario: I was looking for a way to add custom filters, and the docs recommended that I add a snippet to my 11ty.js file. At this point, I realized I didn't have an 11ty.js file in my project and didn't know what that was. When I wanted to learn more, I wasn't able to easily find an explanation by browsing the docs.

Not sure if this is a case of missing documentation or just documentation being located in a non-intuitive spot. (I still haven't found it!)

Thanks!

[santicros]

I agree with @hxlnt. For me it's not very clear all the options available, what makes them powerful,... I think improving the documentation on this part would be great.

Also for beginners I think it would be interesting to have a comparison table of all the supported languages and what they support or not, if there are some that are recommended in some situations... As a user that had never used Liquid, Nunjucks, 11ty.js, ... it was very difficult for me to know what templating language to choose... If there was a recommended option or not,..

[pdehaan]

If you’re talking about *.11ty.js templates, the docs are at https://www.11ty.dev/docs/languages/javascript/

if you’re talking about .eleventy.js config files, that should be documented at https://www.11ty.dev/docs/config/

[hxlnt]

@pdehaan Yes, I missed https://www.11ty.dev/docs/config/ because it's shown as a docs heading, and I didn't realize the headings are clickable and house content as well. However, now that I've had a chance to see these two docs, I realize what was actually confusing me...

The syntax snippets usually show Nunjucks/Liquid samples and rarely show Javascript samples. As a Nunjucks user, when I came across a docs page that showed both Nunjucks and Javascript snippets, one after the other, I thought it was saying, essentially "Here's what you put in your template, and the below that is what you put in your .11ty.js file" because it's rather uncommon to see a JS snippet example.

Looking at the snippets more closely, I now realize they're showing the same thing, but this was a point of confusion. I think if this had been shown with something like a tabbed snippet box where users could select between templating options, it would be clearer.

[Ryuno-Ki]

Actually: The syntax Liquid | Nunjucks above the code snippets are tabs :-) The documentation repo is over at https://github.com/11ty/11ty-website if you want to submit a PR to improve the documentation.

For example, your screenshot is located at https://github.com/11ty/11ty-website/blob/f8f849d7ee84346f4991eb45dd014e623d4bcfd6/docs/collections.md#a-blog-example

The codetitle shortcode is defined at

https://github.com/11ty/11ty-website/blob/0445e48f08274a386dd8efb4f261650e1d03a2b9/.eleventy.js#L106-L108

[hxlnt]

@Ryuno-Ki No, the screenshots above don't show tabs, which is part of the confusion: they're non-clickable labels. But browsing around the website, I do see other places where tabs are used as you describe; I think it just needs to be applied consistently. Will look into making a PR. 👍

[zachleat]

Moving to 11ty-website