add and update docs

src/docs/card.njk

@@ -0,0 +1,91 @@
+---
+title: Card
+---
+
+<p>
+  Previous to version 3, the card component was a Nunjucks include. There are a number of things that had to
+  be set before being able to use it, like the level of the heading or whether tags shall be displayed.
+  <a href="https://www.11ty.dev/docs/languages/webc/">WebC</a>
+  makes this easier, as you can now use the custom element and opt in to the different slots.
+</p>
+
+<p><strong>Available slots:</strong></p>
+<ul>
+  <li>
+    image: the <code>image</code> shortcode has the <code>slot="image"</code> assigned to its
+    <code>picture</code> or <code>figure</code> wrapper by default!
+  </li>
+  <li>headline: display the card's main title</li>
+  <li>
+    date and tag: Grouped within the classes <code>meta</code> and <code>cluster</code> for date and tagging
+    information.
+  </li>
+  <li>content</li>
+  <li>footer: for links or whatever footer information</li>
+</ul>
+
+<p>I added some <strong>variants</strong>, avaliable via attribute selectors:</p>
+
+<ul>
+  <li><code>img-square</code>: Enforces a square aspect ratio for images.</li>
+  <li><code>clickable</code>: Makes the whole card clickable.</li>
+  <li><code>no-padding</code>: Removes padding and background modifications.</li>
+</ul>
+
+<strong>Usage</strong>
+
+<pre><code>{% raw %}
+  <!--prettier-ignore-->
+  &lt;custom-card&gt;
+	{% image "path-to-img", "alt-text" %}
+	&lt;span slot="date"&gt;&lt;/span&gt;
+	&lt;span slot="tag" class="button post-tag"&gt;&lt;/span&gt;
+	&lt;h2 slot="headline"&gt;&lt;/h2&gt;
+	&lt;p slot="content"&gt;&lt;/p&gt;
+	&lt;footer slot="footer"&gt;&lt;/footer&gt;
+	&lt;/custom-card&gt;
+{% endraw %}</code></pre>
+
+<strong>Example</strong>
+
+<div class="grid" data-layout="50-50">
+  <custom-card>
+    {% image "./src/assets/images/gallery/asturias-3.jpg", "Close-up of a delicate white flower with a yellow center, surrounded by green leaves" %}
+    <span slot="date">1516</span>
+    <span slot="tag" class="button post-tag">Default</span>
+    <h2 slot="headline">Utopia</h2>
+    <p slot="content">
+      Among them, there is no sort of traffic, no knowledge of letters, no understanding of numbers, no name
+      of magistrates, nor of politics, only of virtues; and they measure all things by barleycorns; their
+      money, plate, and other ornaments they so diligently polish that no rust can stick to them.
+    </p>
+    <footer slot="footer"><a href="#">Link in the footer</a></footer>
+  </custom-card>
+
+  <custom-card clickable img-square>
+    {% image "./src/assets/images/gallery/asturias-3.jpg", "Close-up of a delicate white flower with a yellow center, surrounded by green leaves" %}
+    <span slot="date">18.02.1984</span>
+    <div slot="tag" webc:nokeep>
+      <span class="button post-tag">clickable</span><span class="button post-tag">square image</span>
+    </div>
+    <footer slot="footer"><a href="#">Link in the footer makes whole card a link</a></footer>
+    <h2 slot="headline">The order does not matter</h2>
+  </custom-card>
+
+  <custom-card>
+    <p slot="content">
+      They have no lawyers among them, for they consider them as a sort of people whose profession it is to
+      disguise matters and to wrest the laws [...].
+    </p>
+    <h2 slot="headline">Just title and content</h2>
+  </custom-card>
+
+  <custom-card no-padding>
+    {% image "./src/assets/images/gallery/asturias-3.jpg", "Close-up of a delicate white flower with a yellow center, surrounded by green leaves" %}
+    <p slot="content">
+      Red Hat's first logo appeared on an early invoice. It was a simple, bright red brimmed top hat placed
+      above the words "Red Hat Software."
+    </p>
+    <h2 slot="headline">This card has no padding</h2>
+  </custom-card>
+</div>

src/docs/config.md

@@ -0,0 +1,56 @@
+---
+title: Config
+---
+
+I like to divide things into small thematic areas, it helps me orient myself better. Configurations are structured into separate modules in `src/_config` and are then imported into the main configuration file.
+
+- **collections.js**: Manages Eleventy collections such as posts and tags: https://www.11ty.dev/docs/collections/
+- **events.js**: For code that should run at certain times during the compiling process: https://www.11ty.dev/docs/events/
+- **filters.js**: Used within templating syntax to transform data into a more presentable format: https://www.11ty.dev/docs/filters/
+- **plugins.js**: Everything I or Eleventy considers to be a plugin: https://www.11ty.dev/docs/plugins/
+- **shortcodes.js**: Defines shortcodes for reusable content: https://www.11ty.dev/docs/shortcodes/
+
+Each configuration category (filters, plugins, shortcodes, etc.) is modularized. or example, `dates.js` within the `filters` folder contains date-related filters.
+
+```js
+import dayjs from 'dayjs';
+
+export const toISOString = dateString => dayjs(dateString).toISOString();
+export const formatDate = (date, format) => dayjs(date).format(format);
+```
+
+These individual modules are then imported and consolidated in a central `filters.js` file, which exports all the filters as a single default object.
+
+```js
+import {toISOString, formatDate} from './filters/dates.js';
+// more imports
+
+export default {
+  toISOString,
+  formatDate,
+// more exports
+};
+
+```
+
+**Integration in Eleventy Config**
+
+In the main Eleventy configuration file (`eleventy.config.js`), these modules are imported:
+
+```js
+import filters from './src/_config/filters.js';
+import shortcodes from './src/_config/shortcodes.js';
+```
+
+They are then used to register filters and shortcodes with Eleventy, using this nice concise syntax:
+
+```js
+eleventyConfig.addFilter('toIsoString', filters.toISOString);
+eleventyConfig.addFilter('formatDate', filters.formatDate);
+// More filters...
+eleventyConfig.addShortcode('svg', shortcodes.svgShortcode);
+```
+
+This method hopefully keeps the Eleventy config clean and focused, only concerning itself with the registration of functionalities, while the logic and definition remain abstracted in their respective modules.
+
+Some time ago I wrote a blog post about [how to organize the Eleventy configuration file](https://www.lenesaile.com/en/blog/organizing-the-eleventy-config-file/) where I go a little bit deeper into this topic.

src/docs/css.md

@@ -2,9 +2,35 @@
 title: CSS
 ---
 
-Add and delete your custom block stylesheets in `src/assets/css/blocks/*.css`, they get pulled in your output stylesheet automatically.
+Add and delete your globally available custom block stylesheets in `src/assets/css/global/blocks/*.css`.
 
 The methodology used is [CUBE CSS.](https://cube.fyi/)
 
-The CSS system of this starter was invented by Andy Bell.
-If you want to know exactly how it all works, and have a look at the (further elaborated) original, [read this article on piccalil.li](https://piccalil.li/blog/a-css-project-boilerplate/).
+The CSS system of this starter was invented by Andy Bell. If you want to know exactly how it all works, and have a look at the (further elaborated) original, [read this article on piccalil.li](https://piccalil.li/blog/a-css-project-boilerplate/).
+
+**New in version 3.0: Inline CSS**
+
+The main CSS file is now inline in production to improve performance, see `.src/_includes/head/css-inline.njk`.
+
+You can add per-page or component bundles of CSS. Instead of adding your CSS file to the `src/assets/css/global/blocks/` directory, you can place them in `src/assets/css/bundle/`. All CSS files in there will be stored alongside `global.css` in `.src/_includes/css/`. You can now include them in the "inline" bundle only on pages or components where you need them:
+
+
+{% raw %}
+
+```jinja2
+{% css "inline" %}
+  {% include "css/your-stylesheet.css" %}
+{% endcss %}
+```
+
+{% endraw %}
+
+**New in version 3.0: Component CSS**
+
+All CSS files placed in `src/assets/css/components/` will be sent to the output folder, where components can reference them: `/assets/css/components/*.css`.
+
+**New in version 3.0: Debugging CSS**
+
+In `src/assets/css/global.css` you can decomment `@import-glob 'tests/*.css';` to include CSS for debugging.
+
+It makes visible you when your code[ wrapped in `<is-land>` elements](https://github.com/11ty/is-land) is being hydrated, where things might overflow and many other warnings and errors [that Heydon Pickering came up with](https://heydonworks.com/article/testing-html-with-modern-css/).

src/docs/design-tokens.md

@@ -4,7 +4,7 @@ title: Design tokens
 
 Edit all your preferences (colors, fluid text sizes etc.) in `src/_data/designTokens/*.json`.
 
-Additional colors, variants and gradients for custom properties are automatically created in `src/assets/css/global/variables.css` based on the colors set in `colors.json`. If you change names you should edit `variables.css` as well and check if the names are used elsewhere in the template.
+Additional colors, variants and gradients for custom properties are automatically created in `src/assets/css/global/base/variables.css` based on the colors set in `colors.json`. If you change names you should edit `variables.css` as well and check if the names are used elsewhere in the template.
 Admittedly, I went a little bit crazy there with the new CSS color syntax stuff.
 
 In the [style guide](/styleguide/) you can see how everything turns out.

src/docs/details.md

@@ -0,0 +1,23 @@
+---
+title: Details
+usage: "{% set itemList = collections.docs %}{% include 'partials/details.njk' %}"
+---
+
+The `custom-details` WebC component has a corresponding Nunjucks include.
+It uses the `details` and `summary` elements to create a collapsible section and enhances them aesthetically and functionally.
+
+The JavaScript for the `custom-details` component adds functionality to buttons to expand and collapse the sections with one action. When JavaScript is disabled, the sections are still accessible and collapsible, but the extra buttons are hidden.
+
+On page load, it checks if a hash corresponding to a details ID exists in the URL. If such an ID is found, the corresponding details section is programmatically opened, allowing direct navigation to an open section from a shared URL.
+
+The sorting is set by default on "alphabetic", but you can also pass in "shuffle" or "reverse" as a parameter (directly in the `details.njk` partial).
+
+**Usage**
+
+```
+{{ usage | safe }}
+```
+
+**Example**
+
+You are in the middle of a custom details component!

src/docs/docs.json

@@ -1,4 +1,4 @@
 {
-	"tags": "docs",
+  "tags": "docs",
   "permalink": false
 }

src/docs/easteregg.md

@@ -0,0 +1,23 @@
+---
+title: Easteregg
+---
+
+The `custom-easteregg` component is by default in the base layout in `src/_layouts/base.njk`. Just delete the two lines if you don't want to use it. The component is
+ designed to trigger a confetti effect when a user types a specific keyword sequence. It uses the dynamic import of the `canvas-confetti` library to render custom-shaped particles based on user input.
+
+**Defaults**:
+  - **Keywords**: `"eleventy"`, `"excellent"`
+  - **Shape**: `"⭐️"`
+  - **Particle Count**: `30`
+
+**Customizable Attributes**:
+  - `keyword`: custom keyword
+  - `shape`: custom shape for the confetti particles using emojis or text
+  - `particle-count`: number of particles to release during the effect
+
+
+```
+<script type="module" src="/assets/scripts/components/custom-easteregg.js"></script>
+<custom-easteregg keyword="yay" shape="🌈" particle-count="50"></custom-easteregg>
+```
+

src/docs/favicons.md

@@ -2,10 +2,20 @@
 title: Favicons
 ---
 
-The favicons used are based on the recommendations from the [How to Favicon article on evilmartians.com.](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs)
+All "necessary" favicons are in `src/assets/images/favicon`, and copied over to the root of the output folder.
 
-All favicons are in `src/assets/images/favicons`, and copied over to the root of the output folder.
+I chose the sizes based on the recommendations from the [How to Favicon article on evilmartians.com.](https://evilmartians.com/chronicles/how-to-favicon-in-2021-six-files-that-fit-most-needs)
 
-There is no automatization in place to create them.
+You can place them in that directory manually, or use the script to autmate the process:
 
-I recommend keeping the file names as they are, since they are referenced like that in different places.
+```bash
+npm run favicons
+```
+
+In this case define the SVG icon on which all formats are based on in `meta.js`:
+
+```js
+export const pathToSvgLogo = 'src/assets/svg/misc/logo.svg'; // used for favicon generation
+```
+
+Regardless of whether you generate the icons automatically or create them manually, it is best to keep the names so as not to break any reference to them.

src/docs/fonts.md

@@ -2,12 +2,12 @@
 title: Fonts
 ---
 
-This starter uses three fonts, Red Hat Display, Figtree and Roboto Mono. You can add or delete fonts in `src/assets/fonts`.
+This starter uses two custom fonts, Red Hat Display and Inclusive Sans. You can add or delete fonts in `src/assets/fonts`.
 
-You can create font subsets for a better performance, for example using the [Fontsquirrel Webfont Generator](https://www.fontsquirrel.com/tools/webfont-generator).
+I often create font subsets using the [Fontsquirrel Webfont Generator](https://www.fontsquirrel.com/tools/webfont-generator).
 
-Next, edit `src/assets/css/global/fonts.css`.
+Next, edit `src/assets/css/global/base/fonts.css`.
 
 Add your new font aliases in `src/_data/designTokens/fonts.json`.
 
-Finally, in `src/_layouts/base.njk` edit the font preloads. Roboto Mono is only used for code blocks. Its preload is set directly in the post layout: `src/_layouts/post.njk`.
+Finally, in `src/_includes/head/preloads.njk` edit the font preloads.

src/docs/javascript.md

@@ -0,0 +1,36 @@
+---
+title: JavaScript
+---
+
+This starter has **no real JS dependency**. If JavaScript is not available, components that rely on it -- like the theme switcher -- will be hidden. If you opted in for the drawer menu, pills will be shown instead.
+
+There are two kinds of bundles for JavaScript in this starter, see `.src/_includes/head/js-inline.njk` and `.src/_includes/head/js-defer.njk`.
+By default, I include Eleventy's [is-land](https://github.com/11ty/is-land) framework and the theme toggle inline.
+
+You can include more scripts like so:
+
+{% raw %}
+
+```jinja2
+{% js "inline" %}
+ {% include "scripts/your-inline-script.js" %}
+{% endjs %}
+```
+
+{% endraw %}
+
+Same goes for scripts that should be defered:
+
+{% raw %}
+
+```jinja2
+{% js "defer" %}
+ {% include "scripts/your-defered-script.js" %}
+{% endjs %}
+```
+
+{% endraw %}
+
+Scripts stored in `src/assets/scripts/components/` are sent to the output folder, while scripts in  `src/assets/scripts/bundle/` are sent to `.src/_includes/scripts/`, from where you can include them in the respective bundle.
+
+Some components are enhanced with JavaScript.

src/docs/masonry.md

@@ -2,8 +2,38 @@
 title: Masonry
 ---
 
-There is the idea of making masonry layout a native part of CSS grid, using `grid-template-rows: masonry;`. It is [not yet to be seen on the horizon](https://caniuse.com/mdn-css_properties_grid-template-rows_masonry), but it is already included in the starter (inside the `grid.css` composition).
-Until then, a small script will help us to get the effect.
 
-It gets loaded by opt-in.
-Set `masonry: true` in your front matter to activate.
+Masonry layout is not yet a native part of CSS grid. There is a debate if using `grid-template-rows: masonry;` is actually the best way to implement it.
+
+It should be used carefully so we don't create confusion with the tabbing order. In version 3 of the starter I made the masonry layout a web component, and no longer a opt-in feature (was: `masonry: true` in the front matter).
+
+`custom-masonry` is designed to function as a masonry grid by dynamically adjusting item positions based on the available column space and the size of its content. The necessary JavaScript (`custom-masonry.js`) is loaded only once per component usage due to the `data-island="once"` attribute.
+Optional: pass in `layout="50-50"` to set a 50% width for each column.
+
+If no JavaScript is available, the grid will fall back to the regular grid layout defined in `src/assets/css/global/compositions/grid.css`.
+
+```
+<custom-masonry> (children) </custom-masonry>
+<custom-masonry layout="50-50"> (children) </custom-masonry>
+```
+
+<div><custom-masonry>
+   <div style="background-color: var(--color-primary); aspect-ratio: 3/2;"></div>
+	 	<div></div>
+		<div style="background-color: var(--color-tertiary); aspect-ratio: 4/5;"></div>
+		<div style="background-color: var(--color-primary);"></div>
+		<div></div>
+		<div style="background-color: var(--color-secondary); aspect-ratio: 5/4;"></div>
+		<div></div>
+		<div style="background-color: var(--color-secondary);"></div>
+    <div style="background-color: var(--color-primary); aspect-ratio: 16/9;"></div>
+	 	<div></div>
+</custom-masonry></div>
+
+<style>
+  custom-masonry div {
+    inline-size: min(30rem, 100%);
+		aspect-ratio: 1;
+    background-color: var(--color-text);
+  }
+</style>