Docs for 11ty/eleventy#84

src/_includes/syntax-chooser-tablist.11ty.js

@@ -1,9 +1,18 @@
-async function render({id, valid, additions, subtractions, label}) {
+async function render({id, valid, additions, subtractions, only, label}) {
 	let syntaxes = {};
 
 	let extraSyntaxes = {
 		md: "Markdown",
 		webc: "WebC",
+		jscjs: "CommonJS",
+		jsesm: "ESM",
+	};
+
+	let syntaxMap = {
+		liquid: "Liquid",
+		njk: "Nunjucks",
+		js: "11ty.js",
+		hbs: "Handlebars",
 	};
 
 	// Extras go first
@@ -14,12 +23,13 @@ async function render({id, valid, additions, subtractions, label}) {
 		}
 	}
 
-	Object.assign(syntaxes, {
-		liquid: "Liquid",
-		njk: "Nunjucks",
-		js: "11ty.js",
-		hbs: "Handlebars",
-	});
+	if(only) {
+		for(let syn of (only || "").split(",")) {
+			syntaxes[syn] = extraSyntaxes[syn] || syntaxMap[syn];
+		}
+	} else {
+		Object.assign(syntaxes, syntaxMap);
+	}
 
 	for(let syn of (subtractions || "").split(",")) {
 		if(syn) {

src/docs/filters/inputpath-to-url.md

@@ -0,0 +1,84 @@
+---
+eleventyNavigation:
+  parent: Filters
+  key: inputPathToUrl Filter
+  title: '<code>inputPathToUrl</code>'
+  order: 4
+  excerpt: 'Map a template’s input path to its output URL.'
+---
+# `inputPathToUrl` Universal Filter
+
+{% addedin "3.0.0-alpha.5" %} Map a file’s location and to the template’s output URL. Very useful for robust hyperlinking allowing you to change your output URLs without breaking content links!
+
+This filter is an alternative to the [InputPath To Url plugin](/docs/plugins/inputpath-to-url/), which provides an Eleventy transform that is less verbose but a bit slower.
+
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "inputpathtourl"} %}
+  <div id="inputpathtourl-liquid" role="tabpanel">
+
+{% codetitle "Liquid", "Syntax" %}
+
+{% raw %}
+```liquid
+<a href="{{ "index.md" | inputPathToUrl }}">Home</a>
+```
+{% endraw %}
+
+  </div>
+  <div id="inputpathtourl-njk" role="tabpanel">
+
+{% codetitle "Nunjucks", "Syntax" %}
+
+{% raw %}
+```jinja2
+<a href="{{ "index.md" | inputPathToUrl }}">Home</a>
+```
+{% endraw %}
+
+  </div>
+  <div id="inputpathtourl-js" role="tabpanel">
+
+{% codetitle "JavaScript (CommonJS)", "Syntax" %}
+
+{% raw %}
+```js
+module.exports = function(data) {
+  return `<a href="${this.inputPathToUrl("index.md")}">Home</a>`;
+}
+```
+{% endraw %}
+
+  </div>
+  <div id="inputpathtourl-jsesm" role="tabpanel">
+
+{% codetitle "JavaScript (ESM)", "Syntax" %}
+
+{% raw %}
+```js
+export default function(data) {
+  return `<a href="${this.inputPathToUrl("index.md")}">Home</a>`;
+}
+```
+{% endraw %}
+
+  </div>
+  <div id="inputpathtourl-hbs" role="tabpanel">
+
+{% codetitle "Handlebars", "Syntax" %}
+
+{% raw %}
+```hbs
+<a href="{{ inputPathToUrl "index.md" }}">Home</a>
+```
+{% endraw %}
+
+  </div>
+</seven-minute-tabs>
+</is-land>
+
+Renders as `<a href="/">Home</a>`.
+
+---
+
+[← Back to Filters documentation.](/docs/filters/)

src/docs/filters/log.md

@@ -102,4 +102,6 @@ This is the same as:
 </seven-minute-tabs>
 </is-land>
 
-* [← Back to Filters documentation.](/docs/filters/)
+---
+
+[← Back to Filters documentation.](/docs/filters/)

src/docs/plugins/inputpath-to-url.md

@@ -0,0 +1,106 @@
+---
+eleventyNavigation:
+  key: InputPath to URL
+  order: 3
+  excerpt: Maps an Eleventy input file path to its output URL.
+---
+# InputPath to URL {% addedin "3.0.0-alpha.5" %}
+
+{% tableofcontents %}
+
+This plugin allows you to use file system paths in your HTML and they will be automatically transformed to their output URLs. Very useful for robust hyperlinking allowing you to change your output URLs without breaking content links! Works out of the box with [`permalink` remapping](/docs/permalinks/), the [HTML `<base>` plugin](/docs/plugins/html-base/), etc.
+
+This plugin is an implicit alternative to the [`inputPathToUrl` filter](/docs/filters/inputpath-to-url/). The filter is faster but a bit more verbose.
+
+### Usage
+
+You can link to `inputPath` in any `a[href]`, `video[src]`, `audio[src]`, `source`, `img[src]`, `[srcset]` and [a whole bunch more](https://github.com/posthtml/posthtml-urls/blob/307c91342a211b3f9fb22bc57264bbb31f235fbb/lib/defaultOptions.js) (via [posthtml-urls](https://github.com/posthtml/posthtml-urls)) and this plugin will render the correct URL for the template in your output directory.
+
+```html
+<a href="my-template.md">Home</a>
+
+<!-- renders as -->
+<a href="/my-template/">Home</a>
+```
+
+### Installation
+
+{% addedin "3.0.0-alpha.5" %} This plugin is bundled with Eleventy 3.0 and does not require you to install anything from `npm`. However, the plugin is _opt-in_ (requires you to use `addPlugin`). It is compatible with _all_ template languages via an Eleventy Transform.
+
+Note that the [`inputPathToUrl` filter](/docs/filters/inputpath-to-url/) is available by default and does not require use of `addPlugin`.
+
+Open up your Eleventy config file (probably `.eleventy.js`) and use `addPlugin`:
+
+<is-land on:visible import="/js/seven-minute-tabs.js">
+<seven-minute-tabs>
+  {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: "configfile", only: "jsesm,jscjs" } %}
+  <div id="configfile-jsesm" role="tabpanel">
+
+{% codetitle ".eleventy.js (ESM)" %}
+
+```js
+import { PathToUrlTransformPlugin } from "@11ty/eleventy";
+
+export default function(eleventyConfig) {
+  eleventyConfig.addPlugin(PathToUrlTransformPlugin);
+};
+```
+_You’re only allowed one `export default` in your configuration file, so make sure you only copy the `import` and the `addPlugin` lines above!_
+
+<details>
+<summary>Expand for full options list</summary>
+
+{% codetitle ".eleventy.js (ESM)" %}
+
+```js
+import { PathToUrlTransformPlugin } from "@11ty/eleventy";
+
+export default function(eleventyConfig) {
+  eleventyConfig.addPlugin(PathToUrlTransformPlugin, {
+		// Comma separated list of outputPath file extensions to apply the transform
+		extensions: "html",
+	});
+};
+```
+
+* Read more about [Transform outputPaths](/docs/config/#transforms).
+
+</details>
+
+  </div>
+  <div id="configfile-jscjs" role="tabpanel">
+
+{% codetitle ".eleventy.js (CommonJS)" %}
+
+```js
+module.exports = async function(eleventyConfig) {
+	const { PathToUrlTransformPlugin } = await import("@11ty/eleventy");
+
+  eleventyConfig.addPlugin(PathToUrlTransformPlugin);
+};
+```
+_You’re only allowed one `module.exports` in your configuration file, so make sure you only copy the `import` and the `addPlugin` lines above!_
+
+<details>
+<summary>Expand for full options list</summary>
+
+{% codetitle ".eleventy.js (CommonJS)" %}
+
+```js
+module.exports = async function(eleventyConfig) {
+	const { PathToUrlTransformPlugin } = await import("@11ty/eleventy");
+
+  eleventyConfig.addPlugin(PathToUrlTransformPlugin, {
+		// Comma separated list of outputPath file extensions to apply the transform
+		extensions: "html",
+	});
+};
+```
+
+* Read more about [Transform outputPaths](/docs/config/#transforms).
+
+</details>
+
+  </div>
+</seven-minute-tabs>
+</is-land>