search

11ty / 11ty-website

Documentation site for the Eleventy static site generator.
https://www.11ty.dev/
MIT License
474 stars 681 forks source link

Rewrite /docs/languages pages in _that_ templating language #421

Open reubenlillie opened 4 years ago

reubenlillie commented 4 years ago

This is a pretty meta idea—even for me—but what if each of the docs pages for the different supported templating languages were written in that templating language? (This idea may not work for .html, .md, or .jstl—but it'd be a potential game changer for the others.) What a tremendous benefit for readers—especially newcomers—to see the language being discussed in action, not merely in snippets wrapped in a different templating language they may not understand, but in the very templating language they're trying to learn about! I'm also thinking that it would reduce cognitive overload, at least in terms of editing individual docs pages, for that page to be all in one language. Thoughts?

I'm happy to begin converting the /docs/languages/javascript.md over to *.11ty.js. Any takers for the others?

Ryuno-Ki commented 4 years ago

I worked with those template languages: Nunjucks, EJS, Pug, Haml, Mustache, Handlebars, Liquid. So … um … perhaps someone else can pick her/his favourite first?

reubenlillie commented 4 years ago

So, I was able to spin up #422 PR up for *.11ty.js. I think we have a snag, though … and that snag is syntax highlighting. In my PR, I was able to make a version of the hightlight() shortcode from eleventy-plugin-syntax-highlight. I also submitted an issue 11ty/eleventy-plugin-syntax-highlight#21 for adding *.11ty.js support over there. But I don’t know if any takers (or even is @zachleat likes the idea?) of expanding syntax highlighting support to the other languages. Can we rule out languages that couldn’t be supported with native syntax highlighting .html, .md, .jstl; any others? Would it be possible still to wrap the code examples themselves in Nunjucks/Liquid-style paired shortcodes for the syntax highlighting? 🤔 Or, … I may be wrong. Is syntax highlighting available within the other languages that support Markdown ``` blocks?

Ryuno-Ki commented 4 years ago

Under the hood, that plugin is using Prism.js, which has a huge number of supported languages. Couldn't .jstl be considered plain .js?

reubenlillie commented 4 years ago

@Ryuno-Ki,

Sorry if I was unclear. It's not a matter of if Prism supports the language, but if the language supports template shortcodes (assuming Markdown ``` doesn't suffice for all of them?) to say: "Hey, Prism, highlight that as LANGUAGE." Then, to create plugin support for those template shortcodes. Right?

Ryuno-Ki commented 4 years ago

Well, normally, I'd assume ```lang would suffice.

But, the template shortcode thing is something I hadn't on my radar. Hmm …

reubenlillie commented 4 years ago

All I know is I had to spin up a function for JavaScript because of how backticks work with template literals. I'm just wondering if something similar affects other templating languages. I dunno. I don't use them. That's why I'm asking.