From 2b6858ae60dbec16e01865acd602d097bb614245 Mon Sep 17 00:00:00 2001 From: Zach Leatherman Date: Tue, 24 Sep 2024 16:52:29 -0500 Subject: [PATCH] Custom Data Files ESM docs https://github.com/11ty/eleventy/issues/836 --- .../snippets/cascade/custom-exif.njk | 53 +++++++++ .../snippets/cascade/custom-json.njk | 29 +++++ .../snippets/cascade/custom-order.njk | 39 +++++++ .../snippets/cascade/custom-toml.njk | 29 +++++ .../snippets/cascade/custom-yaml.njk | 29 +++++ src/_includes/snippets/cascade/custom.njk | 31 ++++++ src/_includes/snippets/cascade/customopts.njk | 39 +++++++ src/docs/data-custom.md | 101 ++---------------- 8 files changed, 257 insertions(+), 93 deletions(-) create mode 100644 src/_includes/snippets/cascade/custom-exif.njk create mode 100644 src/_includes/snippets/cascade/custom-json.njk create mode 100644 src/_includes/snippets/cascade/custom-order.njk create mode 100644 src/_includes/snippets/cascade/custom-toml.njk create mode 100644 src/_includes/snippets/cascade/custom-yaml.njk create mode 100644 src/_includes/snippets/cascade/custom.njk create mode 100644 src/_includes/snippets/cascade/customopts.njk diff --git a/src/_includes/snippets/cascade/custom-exif.njk b/src/_includes/snippets/cascade/custom-exif.njk new file mode 100644 index 0000000000..dfe366aee6 --- /dev/null +++ b/src/_includes/snippets/cascade/custom-exif.njk @@ -0,0 +1,53 @@ +{%- set tabid = "customexif" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +import exifr from "exifr"; + +export default function (eleventyConfig) { + eleventyConfig.addDataExtension("png,jpeg", { + parser: async (file) => { + let exif = await exifr.parse(file); + + return { + exif, + }; + }, + + // Using `read: false` changes the parser argument to + // a file path instead of file contents. + read: false, + }); +}; +``` + +
+
+ +```js +const exifr = require("exifr"); + +module.exports = function (eleventyConfig) { + eleventyConfig.addDataExtension("png,jpeg", { + parser: async (file) => { + let exif = await exifr.parse(file); + + return { + exif, + }; + }, + + // Using `read: false` changes the parser argument to + // a file path instead of file contents. + read: false, + }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/cascade/custom-json.njk b/src/_includes/snippets/cascade/custom-json.njk new file mode 100644 index 0000000000..7542854b48 --- /dev/null +++ b/src/_includes/snippets/cascade/custom-json.njk @@ -0,0 +1,29 @@ +{%- set tabid = "customjson" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + eleventyConfig.addDataExtension("geojson", (contents) => + JSON.parse(contents) + ); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + eleventyConfig.addDataExtension("geojson", (contents) => + JSON.parse(contents) + ); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/cascade/custom-order.njk b/src/_includes/snippets/cascade/custom-order.njk new file mode 100644 index 0000000000..88e50faf1b --- /dev/null +++ b/src/_includes/snippets/cascade/custom-order.njk @@ -0,0 +1,39 @@ +{%- set tabid = "customorder" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +import toml from "@iarna/toml"; +import yaml from "js-yaml"; + +export default function (eleventyConfig) { + // Lower priority + eleventyConfig.addDataExtension("toml", (contents) => toml.parse(contents)); + + // Higher priority + eleventyConfig.addDataExtension("yaml", (contents) => yaml.load(contents)); +}; +``` + +
+
+ +```js +const toml = require("@iarna/toml"); +const yaml = require("js-yaml"); + +module.exports = function (eleventyConfig) { + // Lower priority + eleventyConfig.addDataExtension("toml", (contents) => toml.parse(contents)); + + // Higher priority + eleventyConfig.addDataExtension("yaml", (contents) => yaml.load(contents)); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/cascade/custom-toml.njk b/src/_includes/snippets/cascade/custom-toml.njk new file mode 100644 index 0000000000..3812ad7b65 --- /dev/null +++ b/src/_includes/snippets/cascade/custom-toml.njk @@ -0,0 +1,29 @@ +{%- set tabid = "customtoml" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +import toml from "@iarna/toml"; + +export default function (eleventyConfig) { + eleventyConfig.addDataExtension("toml", (contents) => toml.parse(contents)); +}; +``` + +
+
+ +```js +const toml = require("@iarna/toml"); + +module.exports = function (eleventyConfig) { + eleventyConfig.addDataExtension("toml", (contents) => toml.parse(contents)); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/cascade/custom-yaml.njk b/src/_includes/snippets/cascade/custom-yaml.njk new file mode 100644 index 0000000000..7854dcbab1 --- /dev/null +++ b/src/_includes/snippets/cascade/custom-yaml.njk @@ -0,0 +1,29 @@ +{%- set tabid = "customyaml" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +import yaml from "js-yaml"; + +export default function (eleventyConfig) { + eleventyConfig.addDataExtension("yaml", (contents) => yaml.load(contents)); +}; +``` + +
+
+ +```js +const yaml = require("js-yaml"); + +module.exports = function (eleventyConfig) { + eleventyConfig.addDataExtension("yaml", (contents) => yaml.load(contents)); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/cascade/custom.njk b/src/_includes/snippets/cascade/custom.njk new file mode 100644 index 0000000000..10fe393964 --- /dev/null +++ b/src/_includes/snippets/cascade/custom.njk @@ -0,0 +1,31 @@ +{%- set tabid = "custom" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // Receives file contents, return parsed data + eleventyConfig.addDataExtension("yml,yaml", (contents, filePath) => { + return {}; + }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // Receives file contents, return parsed data + eleventyConfig.addDataExtension("yml,yaml", (contents, filePath) => { + return {}; + }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/_includes/snippets/cascade/customopts.njk b/src/_includes/snippets/cascade/customopts.njk new file mode 100644 index 0000000000..7c8787baed --- /dev/null +++ b/src/_includes/snippets/cascade/customopts.njk @@ -0,0 +1,39 @@ +{%- set tabid = "customopts" %} +
eleventy.config.js
+ + + {% renderFile "./src/_includes/syntax-chooser-tablist.11ty.js", {id: tabid, only: "jsesm,jscjs"} %} +
+ +```js +export default function (eleventyConfig) { + // or with options (new in 2.0) + eleventyConfig.addDataExtension("fileExtension", { + parser: (contents, filePath) => ({}), + + // defaults are shown: + read: true, + encoding: "utf8", + }); +}; +``` + +
+
+ +```js +module.exports = function (eleventyConfig) { + // or with options (new in 2.0) + eleventyConfig.addDataExtension("fileExtension", { + parser: (contents, filePath) => ({}), + + // defaults are shown: + read: true, + encoding: "utf8", + }); +}; +``` + +
+ + \ No newline at end of file diff --git a/src/docs/data-custom.md b/src/docs/data-custom.md index ccbd784195..4550860b8e 100644 --- a/src/docs/data-custom.md +++ b/src/docs/data-custom.md @@ -19,42 +19,14 @@ Note that you can also add [Custom Front Matter Formats](/docs/data-frontmatter- ## Usage -{% codetitle ".eleventy.js" %} - -```js -// Receives file contents, return parsed data -eleventyConfig.addDataExtension("fileExtension", (contents, filePath) => { - return {}; -}); -``` +{% include "snippets/cascade/custom.njk" %} - {% addedin "2.0.0-canary.10" %} Pass a comma-separated list of extensions. - {% addedin "2.0.0-canary.19" %} `filePath` was added as a second argument. -{% codetitle ".eleventy.js" %} - -```js -eleventyConfig.addDataExtension("yml, yaml", (contents, filePath) => { - // … -}); -``` - -### Usage with Options - -{% addedin "2.0.0-canary.10" %} - -{% codetitle ".eleventy.js" %} +### Usage with Options {% addedin "2.0.0-canary.10" %} -```js -// or with options (new in 2.0) -eleventyConfig.addDataExtension("fileExtension", { - parser: (contents, filePath) => ({}), - - // defaults are shown: - read: true, - encoding: "utf8", -}); -``` +{% include "snippets/cascade/customopts.njk" %} - `parser`: the callback function used to parse the data. The first argument is the data file’s contents (unless `read: false`). The second argument is the file path {% addedin "2.0.0-canary.19" %}. - `read` (default: `true`): use `read: false` to change the parser function’s first argument to be a file path string instead of file contents. @@ -66,41 +38,17 @@ eleventyConfig.addDataExtension("fileExtension", { Here we’re using the [`js-yaml` package](https://www.npmjs.com/package/js-yaml). Don’t forget to `npm install js-yaml`. -{% codetitle ".eleventy.js" %} - -```js -const yaml = require("js-yaml"); - -module.exports = (eleventyConfig) => { - eleventyConfig.addDataExtension("yaml", (contents) => yaml.load(contents)); -}; -``` +{% include "snippets/cascade/custom-yaml.njk" %} ### TOML Here we’re using the [`@iarna/toml` package](https://www.npmjs.com/package/@iarna/toml). Don’t forget to `npm install @iarna/toml`. -{% codetitle ".eleventy.js" %} - -```js -const toml = require("@iarna/toml"); - -module.exports = (eleventyConfig) => { - eleventyConfig.addDataExtension("toml", (contents) => toml.parse(contents)); -}; -``` +{% include "snippets/cascade/custom-toml.njk" %} ### Adding a custom JSON file extension -{% codetitle ".eleventy.js" %} - -```js -module.exports = (eleventyConfig) => { - eleventyConfig.addDataExtension("geojson", (contents) => - JSON.parse(contents) - ); -}; -``` +{% include "snippets/cascade/custom-json.njk" %} ### Feed EXIF image data into the Data Cascade @@ -108,27 +56,7 @@ module.exports = (eleventyConfig) => { Note that the second argument is an object with a `parser` function. -{% codetitle ".eleventy.js" %} - -```js -const exifr = require("exifr"); - -module.exports = function (eleventyConfig) { - eleventyConfig.addDataExtension("png,jpeg", { - parser: async (file) => { - let exif = await exifr.parse(file); - - return { - exif, - }; - }, - - // Using `read: false` changes the parser argument to - // a file path instead of file contents. - read: false, - }); -}; -``` +{% include "snippets/cascade/custom-exif.njk" %} - Example using a _template data file_: - Given `my-blog-post.md` and `my-blog-post.jpeg` then `exif` will be available for use in `my-blog-post.md` (e.g. `{% raw %}{{ exif | log }}{% endraw %}`) @@ -141,20 +69,7 @@ Note that in the [data cascade](/docs/data-cascade/) there is a specific conflic If you add multiple file extensions, the latter ones take priority over the earlier ones. In the following example, if there is ever conflicting data between `*.toml` and `*.yaml` files, the `yaml` file will take precedence. -{% codetitle ".eleventy.js" %} - -```js -const toml = require("@iarna/toml"); -const yaml = require("js-yaml"); - -module.exports = (eleventyConfig) => { - // Lower priority - eleventyConfig.addDataExtension("toml", (contents) => toml.parse(contents)); - - // Higher priority - eleventyConfig.addDataExtension("yaml", (contents) => yaml.load(contents)); -}; -``` +{% include "snippets/cascade/custom-order.njk" %} ### Example