diff --git a/.docs/.eleventy.js b/.docs/.eleventy.js index 87d5aa5..93776bc 100644 --- a/.docs/.eleventy.js +++ b/.docs/.eleventy.js @@ -1,3 +1,4 @@ +const fs = require("fs"); const path = require("path"); const htmlentities = require("html-entities"); @@ -5,18 +6,28 @@ const Image = require("@11ty/eleventy-img"); var nextid = 0; +const image_filename_format = (_id, src, width, format, _options) => { + const extension = path.extname(src); + const name = path.basename(src, extension); + return `${name}-${width}w.${format}`; +}; + +function image_metadata_log(metadata, source) { + for(let format in metadata) { + for(let img of metadata[format]) { + console.log(`${source.padEnd(10)} ${format.padEnd(5)} ${`${img.width}x${img.height}`.padEnd(10)} ${img.outputPath}`); + } + } +} + async function shortcode_image(src, alt, classes = "") { let metadata = await Image(src, { widths: [300, null], formats: ["avif", "jpeg"], outputDir: `./_site/img/`, - filenameFormat: (_id, src, width, format, _options) => { - const extension = path.extname(src); - const name = path.basename(src, extension); - return `${name}-${width}w.${format}`; - } + filenameFormat: image_filename_format }); - console.log(metadata); + image_metadata_log(metadata, `IMAGE`); let imageAttributes = { class: classes, @@ -35,31 +46,35 @@ async function shortcode_image_url(src) { widths: [ null ], formats: [ "jpeg" ], outputDir: `./_site/img/`, - filenameFormat: (_id, src, width, format, _options) => { - const extension = path.extname(src); - const name = path.basename(src, extension); - return `${name}-${width}w.${format}`; - } + filenameFormat: image_filename_format }); - console.log(metadata); + image_metadata_log(metadata, `IMAGE_URL`); let data = metadata.jpeg[metadata.jpeg.length - 1]; return data.url; } -async function shortcode_cssbox(content, src) { - let idprev = `image-${nextid}`; - nextid += 1; - let idthis = `image-${nextid}`; - let idnext = `image-${nextid + 1}`; - return `
-${await shortcode_image(src, content, "cssbox_thumb", "300w")} - ${await shortcode_image(src, content, "", "1920w")} - - -< -> -
`; +async function shortcode_image_urlpass(src) { + let target_dir = `./_site/img`; + if(!fs.existsSync(target_dir)) + await fs.promises.mkdir(target_dir, { recursive: true }); + let filename = path.basename(src); + // Generally speaking we optimise PNGs *very* well with oxipng/Zopfli, + // and the Image plugin doesn't respect this + await fs.promises.copyFile(src, path.join(target_dir, filename)); + return `/img/${filename}`; +} + +async function shortcode_gallerybox(content, src, idthis, idprev, idnext) { + return `
+ + ${await shortcode_image(src, "", "", "1920w")} + +
${content}
+ +❰ +❱ +
`; } module.exports = function(eleventyConfig) { @@ -67,6 +82,9 @@ module.exports = function(eleventyConfig) { // eleventyConfig.addPassthroughCopy("css"); eleventyConfig.addShortcode("image", shortcode_image); eleventyConfig.addJavaScriptFunction("image", shortcode_image); - eleventyConfig.addShortcode("image-url", shortcode_image_url); - eleventyConfig.addPairedShortcode("cssbox", shortcode_cssbox); + // eleventyConfig.addNunjucksAsyncShortcode("image_url", shortcode_image_url); + eleventyConfig.addAsyncShortcode("image_url", shortcode_image_url); + eleventyConfig.addAsyncShortcode("image_urlpass", shortcode_image_urlpass); + eleventyConfig.addNunjucksAsyncShortcode("image_urlpass", shortcode_image_urlpass); + eleventyConfig.addPairedShortcode("gallerybox", shortcode_gallerybox); } diff --git a/.docs/Changelog.11tydata.json b/.docs/Changelog.11tydata.json index 0ee657c..67d8eca 100644 --- a/.docs/Changelog.11tydata.json +++ b/.docs/Changelog.11tydata.json @@ -1,5 +1,5 @@ { - "layout": "theme.njk", + "layout": "content-generic.njk", "title": "Changelog", "tags": "navigable", "date": "2002-01-01" diff --git a/.docs/Cookbook.11tydata.json b/.docs/Cookbook.11tydata.json new file mode 100644 index 0000000..14cbdf0 --- /dev/null +++ b/.docs/Cookbook.11tydata.json @@ -0,0 +1,6 @@ +{ + "layout": "content-generic.njk", + "title": "Cookbook", + "tags": "navigable", + "date": "2006-01-01" +} diff --git a/.docs/Cookbook.md b/.docs/Cookbook.md new file mode 120000 index 0000000..7190abd --- /dev/null +++ b/.docs/Cookbook.md @@ -0,0 +1 @@ +../Cookbook.md \ No newline at end of file diff --git a/.docs/Reference.11tydata.js b/.docs/Reference.11tydata.js new file mode 100644 index 0000000..a93e951 --- /dev/null +++ b/.docs/Reference.11tydata.js @@ -0,0 +1,24 @@ +const fs = require("fs"); +const path = require("path"); +const parse_sections = require("./lib/parse_sections.js"); + +const sections = parse_sections(fs.readFileSync( + path.resolve( + __dirname, + `../Chat-Command-Reference.md` + ), + "utf-8" +)); + +console.log(`REFERENCE SECTION TITLES`, sections.slice(1) + .sort((a, b) => a.title.localeCompare(b.title)).map(s => s.title)); + +module.exports = { + layout: "theme.njk", + title: "Reference", + tags: "navigable", + date: "2001-01-01", + section_intro: sections[0], + sections_help: sections.slice(1) + .sort((a, b) => a.title.localeCompare(b.title)) +} diff --git a/.docs/Reference.11tydata.json b/.docs/Reference.11tydata.json deleted file mode 100644 index 5506455..0000000 --- a/.docs/Reference.11tydata.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "layout": "theme.njk", - "title": "Reference", - "tags": "navigable", - "date": "2001-01-01" -} diff --git a/.docs/Reference.html b/.docs/Reference.html new file mode 100644 index 0000000..e9004a1 --- /dev/null +++ b/.docs/Reference.html @@ -0,0 +1,99 @@ +
+
+

{{ section_intro.title }}

+

This is the full chat command reference for WorldEditAdditions. It has 2 parts:

+ +
    +
  1. A contents list of commands and their syntax
    2. +
  2. A full reference, with detailed explanations for each command
    3. +
+ +

After the contents, there is a filter box for filtering the detailed explanations to quickly find the one you're after.

+
+ +
+

+ 🔗 + Contents +

+

TODO: Group commands here by category (*especially* the meta commands)

+ +
+ +
+
+ + +
+
+ + +
+
+ + + + {% for section in sections_help %} +
+

+ 🔗 + {{ section.title }} +

+ + {{ section.content }} +
+ {% endfor %} +
diff --git a/.docs/Reference.md b/.docs/Reference.md deleted file mode 120000 index 8e2095a..0000000 --- a/.docs/Reference.md +++ /dev/null @@ -1 +0,0 @@ -../Chat-Command-Reference.md \ No newline at end of file diff --git a/.docs/Tutorial.md b/.docs/Tutorial.md new file mode 100644 index 0000000..4982348 --- /dev/null +++ b/.docs/Tutorial.md @@ -0,0 +1,120 @@ +--- +layout: content-generic.njk +title: Tutorial +tags: navigable +date: 2004-01-01 +--- + +# WorldEditAdditions Beginner's Tutorial +Welcome to the WorldEditAdditions beginners tutorial! There are a number of conventions used in the [chat command reference](/Reference) that may not be immediately obvious - this guide serves to explain in detail. + +It is assumed that: + + - You are already familiar the basics of [Minetest](https://www.minetest.net/) (try the [tutorial game](https://content.minetest.net/packages/Wuzzy/tutorial/) if you're unsure) + - You have both WorldEdit and WorldEditAdditions installed (see the [Download](/#download) section) + +Minetest supports the execution of _Chat Commands_ to manipulate the Minetest world. While in a Minetest world, simply type `/help` (the first forward slash `/` will automatically cause the chat window to appear) and hit enter to display a list of chat commands that are currently registered grouped by mod for example. + +WorldEdit commands are, by convention, prefixed with an additional forward slash `/`. Here are some examples of WorldEdit chat commands: + +``` +//1 +//2 +//set dirt +``` + +Explaining core WorldEdit commands is out of scope of this tutorial, but you can find a complete list of them here: . + +The purpose of _WorldEditAdditions_ is to extend _WorldEdit_ by adding additional commands. Example commands that have been implemented that are not present in core _WorldEdit_ include (but certainly aren't limited to): + + - [`//maze`](/Reference/#maze-replace_node-path_length-path_width-seed): Create instant mazes + - [`//forest`](/Reference/#forest-density-sapling_a-chance_a-sapling_b-chance_b-sapling_n-chance_n-): Plant forests + - [`//torus`](http://localhost:8080/Reference/#torus-major_radius-minor_radius-node_name-axesxy-hollow): Generate [torus](https://en.wikipedia.org/wiki/Torus) shapes + - [`//scale`](/Reference/#scale-axis-scale_factor-factor_x-factor_y-factor_z-anchor_x-anchor_y-anchor_z): Scale things up and down - even both at the same time! + +See a full list with complete explanations in the [chat command reference](/Reference). + + +## Regions +WorldEdit allows you to define a _region_ by specifying 2 points in the world - we number these points 1 and 2. By using the WorldEdit wand (or WorldEditAdditions Far Wand), one can left click to set the position of point 1, and right click to set point 2: + +{% image "images/tutorial_pos1_2.jpeg" "A screenshot showing WorldEdit points 1 and 2 in a desert with a cactus" %} + +Point 1 is on the cactus, and point 2 is on the ground in the bottom left. + +Most WorldEdit and WorldEditAdditions commands require either 1 or 2 points to be set in order to work. + + - If 1 point is required, it's the origin point used by the command + - If 2 points are required, the defined region specifies the area in which the command is operate + + +## Command syntax +When explaining the syntax (ref [a](https://en.wikipedia.org/wiki/Syntax_(programming_languages)), [b](https://www.bbc.co.uk/bitesize/guides/z22wwmn/revision/6)) of a command, a number of different conventions are used to concisely explain said syntax. Understanding enables you to quickly understand the output of `/help /maze` for example, or the list of commands in the [reference](/Reference). + + - ``: A placeholder for a value that you can change. Do *not* include the `<` angle brackets `>` when replacing it with your actual value. + - `a | b`: 1 thing or another, but not both. + - `[optional_thing]`: Something that's optional. Specifying it enables greater control over the behaviour of the command, but it can be left out for convenience. + - ``: Pick 1 item from the list and replace the entire group, removing the `<` angle brackets `>` as with ``. For example `` could become either `snowballs` or `river`, but not both at the same time. + - ``: Most commonly seen in `[` square brackets `]` indicating an optional thing. Indicates the default value of something that you can replace (or omit). + - `...`: Indicates that the previous items can be repeated. + +Let's illustrate this with a practical example. Consider the following: + +``` +//example | [] +``` + +The following different invocations of the above would be valid: + +``` +//example 10 apple +//example 45 30 maple +//example 30 12 pear something_else +``` + +Now let's apply this to a more practical example: + +``` +//erode [ [ []] [ []] ...] +``` + +The `` explains that either a value of `snowballs` or `river` is acceptable. Then, a key - value list of options can be specified - allowing an arbitrary number of options. + +From this, we can infer the following usage: + +``` +//erode snowballs speed 1 count 50000 +``` + + +## Anything else? + + - Make sure we have covered everything + + +## Advanced Concepts +A number of additional concepts that are not required to use WorldEditAdditions are explained here, as they can be helpful for understanding some of the more advanced concepts and commands provided by WorldEditAdditions. + +### Meta commands +WorldEditAdditions provides a number of *meta commands*. Such commands don't do anything on their own, but call other commands in various different ways. Examples of meta commands include: + + - [`//subdivide`](/Reference#subdivide-size_x-size_y-size_z-cmd_name-args): split a region into chunks, and execute the command once for each chunk + - [`//many`](/Reference#many-times-command): Execute a command multiple times + - [`//multi`](/Reference#multi-command_a-command_b-command_c-): Execute multiple commands in sequence + +Of course, this isn't an exhaustive list - check the [reference](/Reference) for a full list. + +### Memory usage +Memory (or RAM - Random Access Memory) is used by all the processes running on a system to hold data that they are currently working with. This is especially important for WorldEdit and WorldEditAdditions, since the larger the region you define the more memory that will be required to run commands on it. + +Depending on your system, Minetest and your system can slow to a crawl or even crash if you execute a command on a region that's too big. + +To work around this, the [`//subdivide`](/Reference#subdivide-size_x-size_y-size_z-cmd_name-args) command was implemented. It splits the defined region into chunks, and calls the specified command over and over again for each chunk. + +It's not suitable for all commands (since it requires that said command takes 2 points) though, but because it splits the defined region into multiple chunks, it can be executed on *enormous* regions that can't fit into memory all at the same time. + + +## Conclusion +This short tutorial has explained a few key concepts that are useful for understanding WorldEditAdditions, from executing chat commands to the syntax used in the [reference](/Reference) to concisely describe commands. + +If there's a concept that you don't understand after reading this and the [reference](/Reference), please [open an issue](https://github.com/sbrl/Minetest-WorldEditAdditions/issues/new) with a detailed explanation of what it is that you're finding difficult to understand. diff --git a/.docs/_data/contributors.js b/.docs/_data/contributors.js new file mode 100644 index 0000000..b03dacc --- /dev/null +++ b/.docs/_data/contributors.js @@ -0,0 +1,23 @@ +const fs = require("fs"); +const path = require("path"); +const htmlentities = require("htmlentities"); + +function read_contributors() { + return fs.readFileSync(path.resolve(__dirname, "../../CONTRIBUTORS.tsv"), "utf-8") + .split("\n") + .slice(1) + .filter(line => line.length > 0) + .map(line => line.split(/\s+/)) + .map(items => { return { + handle: htmlentities.encode(items[0]), + name: htmlentities.encode(items[1]), + profile_url: `https://github.com/${encodeURIComponent(items[0])}`, + avatar_url: `https://avatars.githubusercontent.com/${encodeURIComponent(items[0])}` + } }); +} + +const contributors = read_contributors(); + +console.log(`CONTRIBUTORS`, contributors); + +module.exports = contributors; diff --git a/.docs/_includes/content-generic.njk b/.docs/_includes/content-generic.njk new file mode 100644 index 0000000..7441c6a --- /dev/null +++ b/.docs/_includes/content-generic.njk @@ -0,0 +1,7 @@ +--- +layout: theme.njk +--- + +
+ {{ content | safe }} +
diff --git a/.docs/_includes/theme.njk b/.docs/_includes/theme.njk index 4faa0ba..f00aae7 100644 --- a/.docs/_includes/theme.njk +++ b/.docs/_includes/theme.njk @@ -1,6 +1,3 @@ ---- - ---- @@ -10,9 +7,9 @@ -