From 8feb08f33a4413ca13bf6fb12ae86f3b98835933 Mon Sep 17 00:00:00 2001 From: David Neal Date: Fri, 27 Feb 2026 18:07:10 -0500 Subject: [PATCH] Add Edge.js template language documentation --- src/_data/externalLinks.js | 4 +- src/_data/templatetypes.json | 4 + src/docs/languages.md | 1 + src/docs/languages/edgejs.md | 166 +++++++++++++++++++++++++++++++++++ 4 files changed, 174 insertions(+), 1 deletion(-) create mode 100644 src/docs/languages/edgejs.md diff --git a/src/_data/externalLinks.js b/src/_data/externalLinks.js index 7a47de993d..8eb3047ab7 100644 --- a/src/_data/externalLinks.js +++ b/src/_data/externalLinks.js @@ -1,3 +1,5 @@ export default { - "tsxNodeUse": "https://tsx.is/dev-api/entry-point" + "tsxNodeUse": "https://tsx.is/dev-api/entry-point", + "edgeJsDocs": "https://edgejs.dev", + "edgeJsPlugin": "https://github.com/reverentgeek/eleventy-plugin-edgejs" } diff --git a/src/_data/templatetypes.json b/src/_data/templatetypes.json index 93e8fec08f..88cd87f197 100644 --- a/src/_data/templatetypes.json +++ b/src/_data/templatetypes.json @@ -50,6 +50,10 @@ "name": "JSX", "ext": "jsx", "url": "/docs/languages/jsx/" +},{ + "name": "Edge.js", + "ext": "edge", + "url": "/docs/languages/edgejs/" },{ "name": "MDX", "ext": "mdx", diff --git a/src/docs/languages.md b/src/docs/languages.md index 8947b3be97..173c1fe589 100644 --- a/src/docs/languages.md +++ b/src/docs/languages.md @@ -14,6 +14,7 @@ Not sure which one to choose? [Liquid](/docs/languages/liquid/) is a popular opt .elv-page-toc-asterisk:before, .elv-page-toc li:has(> a[href="/docs/languages/mdx/"]):after, .elv-page-toc li:has(> a[href="/docs/languages/jsx/"]):after, +.elv-page-toc li:has(> a[href="/docs/languages/edgejs/"]):after, .elv-page-toc li:has(> a[href="/docs/languages/handlebars/"]):after, .elv-page-toc li:has(> a[href="/docs/languages/mustache/"]):after, .elv-page-toc li:has(> a[href="/docs/languages/ejs/"]):after, diff --git a/src/docs/languages/edgejs.md b/src/docs/languages/edgejs.md new file mode 100644 index 0000000000..187a1f7d29 --- /dev/null +++ b/src/docs/languages/edgejs.md @@ -0,0 +1,166 @@ +--- +eleventyNavigation: + parent: JavaScript + key: Edge.js +addedInVersion: 3.0.0 +relatedTitle: Template Language—Edge.js +layout: layouts/langs.njk +--- + + + +| Eleventy Short Name | File Extension | npm Package | +| ------------------- | -------------- | ----------- | +| `edge` | `.edge` | [`eleventy-plugin-edgejs`]({{ externalLinks.edgeJsPlugin }}) | + +- Related languages: [JavaScript](/docs/languages/javascript/), [JSX](/docs/languages/jsx/), [Custom](/docs/languages/custom/) + +{% callout "info", "md" %}Edge.js requires Eleventy v3.0.0+, ESM (`"type": "module"` in your `package.json`), and Node.js >= 22.{% endcallout %} + +## Installation + +{%- set codeBlock %} +npm install eleventy-plugin-edgejs +{%- endset %} +{{ codeBlock | highlight("bash") | safe }} + +## Configuration + +{% addedin "3.0.0" %}Add the plugin to your Eleventy configuration file: + +{% codetitle "eleventy.config.js" %} +{%- set codeBlock %} +import edgeJsPlugin from "eleventy-plugin-edgejs"; + +export default function (eleventyConfig) { + eleventyConfig.addPlugin(edgeJsPlugin); +} +{%- endset %} +{{ codeBlock | highlight("js") | safe }} + +### Plugin Options + +{% codetitle "eleventy.config.js" %} +{%- set codeBlock %} +import edgeJsPlugin from "eleventy-plugin-edgejs"; + +export default function (eleventyConfig) { + eleventyConfig.addPlugin(edgeJsPlugin, { + // Enable template caching (default: false) + cache: false, + + // Add custom global variables/functions + globals: {}, + + // Provide your own Edge.js instance + eleventyLibraryOverride: undefined, + }); +} +{%- endset %} +{{ codeBlock | highlight("js") | safe }} + +## Usage + +Edge.js templates use `{{ "{{" }} }}` for HTML-escaped output and `{{ "{{{" }} }}}` for raw (unescaped) output: + +{%- set codeBlock %} +--- +title: Hello World +--- +

{{ "{{" }} title }}

+{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +### Conditionals + +{%- set codeBlock %} +@if(featured) + Featured Post +@elseif(pinned) + Pinned +@else + Regular Post +@end +{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +### Loops + +{%- set codeBlock %} +@each(post in collections.posts) +
  • {{ "{{" }} post.data.title }}
    • +@end +{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +### Includes + +Place partial templates in your `_includes` directory and reference them with `@include`: + +{%- set codeBlock %} +@include("header") +
    Page content
    +@include("footer") +{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +### Components and Slots + +{%- set codeBlock %} +{{ "{{--" }} _includes/card.edge {{ "--" }}}} +
    +

    {{ "{{" }} title }}

    + {{ "{{{" }} $slots.main() }}} +
    +{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +{%- set codeBlock %} +@component("card", { title: "My Card" }) +

    Card content goes here.

    +@end +{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +### Comments + +{%- set codeBlock %} +{{ "{{--" }} This is a comment and won't appear in the output {{ "--" }}}} +{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +## Eleventy Integration + +The plugin automatically bridges Eleventy filters, shortcodes, and paired shortcodes as Edge.js global functions. + +### Filters + +Eleventy filters are available as globals. Call them as functions in your templates: + +{%- set codeBlock %} +{{ "{{" }} url("/my-page/") }} +{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +### Shortcodes + +Eleventy shortcodes are also available as globals: + +{%- set codeBlock %} +{{ "{{" }} year() }} +{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +### Paired Shortcodes + +For paired shortcodes, the content is passed as the first argument: + +{%- set codeBlock %} +{{ "{{" }} callout("This is the content", "warning") }} +{%- endset %} +{{ codeBlock | highlight("html") | safe }} + +## Community Contributions + +- {% indieweblink "eleventy-plugin-edgejs", externalLinks.edgeJsPlugin %} +- {% indieweblink "Edge.js documentation", externalLinks.edgeJsDocs %}