ESM docs for plugins! 11ty/eleventy#836

src/_includes/snippets/configDefinition.njk

@@ -13,6 +13,7 @@
   {% highlight "js" %}
 {%- if codeContent %}{{ codeContent | esmToCjs | safe }}{% endif %}
   {% endhighlight %}
+	{# <p><em>You’re only allowed one <code>module.exports</code> in your configuration file, so make sure you only copy the <code>require</code> and the <code>addPlugin</code> lines above!<em></p> #}
   </div>
 </seven-minute-tabs>
 </is-land>

src/_includes/snippets/plugins/base-add.njk

@@ -0,0 +1,73 @@
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "htmlbase-fullurl"} %}
+  <div id="htmlbase-fullurl-liquid" role="tabpanel">
+
+With path prefix set to `"/pathprefix/"`:
+
+{% codetitle "Liquid", "Syntax" %}
+
+{% raw %}
+
+```liquid
+{{ "http://example.com/" | addPathPrefixToFullUrl }}
+=> "http://example.com/pathprefix/"
+```
+
+{% endraw %}
+
+  </div>
+  <div id="htmlbase-fullurl-njk" role="tabpanel">
+
+With path prefix set to `"/pathprefix/"`:
+
+{% codetitle "Nunjucks", "Syntax" %}
+
+{% raw %}
+
+```njk
+{{ "http://example.com/" | addPathPrefixToFullUrl }}
+=> "http://example.com/pathprefix/"
+```
+
+{% endraw %}
+
+  </div>
+  <div id="htmlbase-fullurl-js" role="tabpanel">
+
+With path prefix set to `"/pathprefix/"`:
+
+{% codetitle "11ty.js", "Syntax" %}
+
+{% raw %}
+
+```js
+export default function () {
+	return this.addPathPrefixToFullUrl("http://example.com/");
+	// "http://example.com/pathprefix/"
+};
+```
+
+{% endraw %}
+
+  </div>
+	<div id="htmlbase-fullurl-cjs" role="tabpanel">
+
+With path prefix set to `"/pathprefix/"`:
+
+{% codetitle "11ty.cjs", "Syntax" %}
+
+{% raw %}
+
+```js
+module.exports = function () {
+	return this.addPathPrefixToFullUrl("http://example.com/");
+	// "http://example.com/pathprefix/"
+};
+```
+
+{% endraw %}
+
+  </div>
+</seven-minute-tabs>
+</is-land>

src/_includes/snippets/plugins/base-install-options.njk

@@ -0,0 +1,49 @@
+{% set tabid %}tab-{% uid %}{% endset %}
+<div class="codetitle codetitle-right-md">eleventy.config.js</div>
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs class="tabs-flush" persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %}
+  <div id="{{ tabid }}-jsesm" role="tabpanel">
+
+```js
+import { EleventyHtmlBasePlugin } from "@11ty/eleventy";
+
+export default function (eleventyConfig) {
+	eleventyConfig.addPlugin(EleventyHtmlBasePlugin, {
+		// The base URL: defaults to Path Prefix
+		baseHref: eleventyConfig.pathPrefix,
+
+		// But you could use a full URL here too:
+		// baseHref: "http://example.com/"
+
+		// Comma separated list of output file extensions to apply
+		// our transform to. Use `false` to opt-out of the transform.
+		extensions: "html",
+	});
+}
+```
+
+  </div>
+  <div id="{{ tabid }}-jscjs" role="tabpanel">
+
+```js
+module.exports = async function (eleventyConfig) {
+	const { EleventyHtmlBasePlugin } = await import("@11ty/eleventy");
+
+	eleventyConfig.addPlugin(EleventyHtmlBasePlugin, {
+		// The base URL: defaults to Path Prefix
+		baseHref: eleventyConfig.pathPrefix,
+
+		// But you could use a full URL here too:
+		// baseHref: "http://example.com/"
+
+		// Comma separated list of output file extensions to apply
+		// our transform to. Use `false` to opt-out of the transform.
+		extensions: "html",
+	});
+}
+```
+
+  </div>
+</seven-minute-tabs>
+</is-land>

src/_includes/snippets/plugins/base-install.njk

@@ -0,0 +1,29 @@
+{% set tabid %}tab-{% uid %}{% endset %}
+<div class="codetitle codetitle-right-md">eleventy.config.js</div>
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs class="tabs-flush" persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %}
+  <div id="{{ tabid }}-jsesm" role="tabpanel">
+
+```js
+import { EleventyHtmlBasePlugin } from "@11ty/eleventy";
+
+export default function (eleventyConfig) {
+	eleventyConfig.addPlugin(EleventyHtmlBasePlugin);
+}
+```
+
+  </div>
+  <div id="{{ tabid }}-jscjs" role="tabpanel">
+
+```js
+module.exports = async function (eleventyConfig) {
+	const { EleventyHtmlBasePlugin } = await import("@11ty/eleventy");
+
+	eleventyConfig.addPlugin(EleventyHtmlBasePlugin);
+}
+```
+
+  </div>
+</seven-minute-tabs>
+</is-land>

src/_includes/snippets/plugins/base-transform.njk

@@ -0,0 +1,193 @@
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs persist sync>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "htmlbasehtmlblock"} %}
+  <div id="htmlbasehtmlblock-liquid" role="tabpanel">
+
+With path prefix set to `"/pathprefix/"`:
+
+{% codetitle "Liquid", "Syntax" %}
+
+{% raw %}
+
+```liquid
+{{ '<a href="/test/">Link</a>' | transformWithHtmlBase }}
+=> '<a href="/pathprefix/test/">Link</a>'
+
+{{ '<a href="/test/">Link</a>' | transformWithHtmlBase: "http://example.com/" }}
+=> '<a href="http://example.com/pathprefix/test/">Link</a>'
+```
+
+{% endraw %}
+
+Resolving relative URLs (with path prefix still at `"/pathprefix/"`):
+
+{% codetitle "Liquid", "Syntax" %}
+
+{% raw %}
+
+```liquid
+On a page with URL `/my-template/`:
+
+{{ '<a href="test/">Link</a>' | transformWithHtmlBase: "http://example.com/" }}
+=> '<a href="http://example.com/pathprefix/my-template/test/">Link</a>'
+
+Override the page URL:
+
+{{ '<a href="test/">Link</a>' | transformWithHtmlBase: "http://example.com/", "/my-other-template/" }}
+=> '<a href="http://example.com/pathprefix/my-other-template/test/">Link</a>'
+```
+
+{% endraw %}
+
+  </div>
+  <div id="htmlbasehtmlblock-njk" role="tabpanel">
+
+With path prefix set to `"/pathprefix/"`:
+
+{% codetitle "Nunjucks", "Syntax" %}
+
+{% raw %}
+
+```njk
+{{ '<a href="/test/">Link</a>' | transformWithHtmlBase }}
+=> '<a href="/pathprefix/test/">Link</a>'
+
+{{ '<a href="/test/">Link</a>' | transformWithHtmlBase("http://example.com/") }}
+=> '<a href="http://example.com/pathprefix/test/">Link</a>'
+```
+
+{% endraw %}
+
+Resolving relative URLs (with path prefix still at `"/pathprefix/"`):
+
+{% codetitle "Nunjucks", "Syntax" %}
+
+{% raw %}
+
+```njk
+On a page with URL `/my-template/`:
+
+{{ '<a href="test/">Link</a>' | transformWithHtmlBase("http://example.com/") }}
+=> '<a href="http://example.com/pathprefix/my-template/test/">Link</a>'
+
+Override the page URL:
+
+{{ '<a href="test/">Link</a>' | transformWithHtmlBase("http://example.com/", "/my-other-template/") }}
+=> '<a href="http://example.com/pathprefix/my-other-template/test/">Link</a>'
+```
+
+{% endraw %}
+
+  </div>
+  <div id="htmlbasehtmlblock-js" role="tabpanel">
+
+With path prefix set to `"/pathprefix/"`:
+
+{% codetitle "11ty.js", "Syntax" %}
+
+{% raw %}
+
+```js
+export default async function () {
+	return `
+${await this.transformWithHtmlBase(`<a href="/test/">Link</a>`)}
+=> '<a href="/pathprefix/test/">Link</a>'
+
+${await this.transformWithHtmlBase(
+	`<a href="/test/">Link</a>`,
+	"http://example.com/"
+)}
+=> '<a href="http://example.com/pathprefix/test/">Link</a>'`;
+};
+```
+
+{% endraw %}
+
+Resolving relative URLs (with path prefix still at `"/pathprefix/"`):
+
+{% codetitle "11ty.js", "Syntax" %}
+
+{% raw %}
+
+```js
+export default async function () {
+	return `
+On a page with URL "/my-template/":
+
+${await this.transformWithHtmlBase(
+	'<a href="test/">Link</a>',
+	"http://example.com/"
+)}
+=> '<a href="http://example.com/pathprefix/my-template/test/">Link</a>'
+
+Override the page URL:
+
+${await this.transformWithHtmlBase(
+	'<a href="test/">Link</a>',
+	"http://example.com/",
+	"/my-other-template/"
+)}
+=> '<a href="http://example.com/pathprefix/my-other-template/test/">Link</a>''`;
+};
+```
+
+{% endraw %}
+
+  </div>
+	<div id="htmlbasehtmlblock-cjs" role="tabpanel">
+
+With path prefix set to `"/pathprefix/"`:
+
+{% codetitle "11ty.cjs", "Syntax" %}
+
+{% raw %}
+
+```js
+module.exports = async function () {
+	return `
+${await this.transformWithHtmlBase(`<a href="/test/">Link</a>`)}
+=> '<a href="/pathprefix/test/">Link</a>'
+
+${await this.transformWithHtmlBase(
+	`<a href="/test/">Link</a>`,
+	"http://example.com/"
+)}
+=> '<a href="http://example.com/pathprefix/test/">Link</a>'`;
+};
+```
+
+{% endraw %}
+
+Resolving relative URLs (with path prefix still at `"/pathprefix/"`):
+
+{% codetitle "11ty.cjs", "Syntax" %}
+
+{% raw %}
+
+```js
+module.exports = async function () {
+	return `
+On a page with URL "/my-template/":
+
+${await this.transformWithHtmlBase(
+	'<a href="test/">Link</a>',
+	"http://example.com/"
+)}
+=> '<a href="http://example.com/pathprefix/my-template/test/">Link</a>'
+
+Override the page URL:
+
+${await this.transformWithHtmlBase(
+	'<a href="test/">Link</a>',
+	"http://example.com/",
+	"/my-other-template/"
+)}
+=> '<a href="http://example.com/pathprefix/my-other-template/test/">Link</a>''`;
+};
+```
+
+{% endraw %}
+
+  </div>
+</seven-minute-tabs>
+</is-land>