fix: hierarchical heading structure for docs

src/assets/css/local/details.css

@@ -26,15 +26,16 @@ is-land:not(:defined) .details .control {
   grid-column: content;
 }
 
-.details summary {
+.details summary,
+.details summary :is(h1, h2, h3) {
   display: flex;
   align-items: baseline;
   line-height: 1.2;
-  gap: 0 1ch;
+  gap: 0 var(--space-m);
   cursor: pointer;
   list-style: none;
   font-weight: var(--font-bold);
-  font-size: var(--size-step-1);
+  font-size: var(--size-step-2);
 }
 
 .details summary:hover,
@@ -48,30 +49,26 @@ is-land:not(:defined) .details .control {
   display: block;
   color: var(--color-primary);
   font-family: var(--font-mono);
-  font-size: var(--size-step-0);
+  font-size: var(--size-step-1);
   font-weight: var(--font-regular);
   line-height: 0.5;
-  transform: scale(1.4);
   transform-origin: right bottom;
-  margin-inline-start: 0.2ch;
 }
 
 .details details[open] summary::before {
   content: '–';
 }
 
-.details details > :is(h2, h3) {
+.details details > :is(h2, h3, h4) {
-  font-weight: var(--font-bold);
+  font-family: var(--font-body);
-  font-size: var(--size-step-0);
-  border-block-end: var(--stroke);
-  padding-block-end: var(--space-xs);
 }
 
-.details details > :is(h2, h3) {
+.details details > h2 {
-  font-weight: var(--font-bold);
+  font-size: var(--size-step-1);
+}
+
+.details details > h3 {
   font-size: var(--size-step-0);
-  border-block-end: var(--stroke);
-  padding-block-end: var(--space-xs);
 }
 
 /* Hide default marker */
@@ -86,5 +83,5 @@ is-land:not(:defined) .details .control {
 }
 
 .details details > * + * {
-  margin-inline-start: 2.4ch;
+  margin-inline-start: var(--size-step-2);
 }

src/docs/card.njk

@@ -9,51 +9,49 @@ title: Card
   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>
+<h3>Available slots:</h3>
 <ul>
   <li>
-    image: the <code>image</code> shortcode has the <code>slot="image"</code> assigned to its
+    <code>image</code>: has <code>slot="image"</code> on the
-    <code>picture</code> or <code>figure</code> wrapper by default!
+    container (<code>picture</code> or <code>figure</code>) by default)
   </li>
-  <li>headline: display the card's main title</li>
+  <li><code>headline</code>: 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
+    <code>date</code> and <code>tag</code>: Grouped within the classes <code>meta</code> and <code>cluster</code> for date and tagging
-    information.
+    information
   </li>
-  <li>content</li>
+  <li><code>content</code></li>
-  <li>footer: for links or whatever footer information</li>
+  <li><code>footer</code>: 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>img-square</code>: Enforces a square aspect ratio for images</li>
-  <li><code>clickable</code>: Makes the whole card clickable.</li>
+  <li><code>clickable</code>: Makes the whole card clickable</li>
-  <li><code>no-padding</code>: Removes padding and background modifications.</li>
+  <li><code>no-padding</code>: Removes padding and background modifications</li>
 </ul>
 
-<strong>Usage</strong>
+<h3>Usage</h3>
 
-<pre><code>{% raw %}
+<pre><code>{% raw %}<!--prettier-ignore-->&lt;custom-card&gt;
-  <!--prettier-ignore-->
+{% image "path-to-img", "alt-text" %}
-  &lt;custom-card&gt;
+&lt;span slot="date"&gt;&lt;/span&gt;
-	{% image "path-to-img", "alt-text" %}
+&lt;span slot="tag" class="button"&gt;&lt;/span&gt;
-	&lt;span slot="date"&gt;&lt;/span&gt;
+&lt;h2 slot="headline"&gt;&lt;/h2&gt;
-	&lt;span slot="tag" class="button"&gt;&lt;/span&gt;
+&lt;p slot="content"&gt;&lt;/p&gt;
-	&lt;h2 slot="headline"&gt;&lt;/h2&gt;
+&lt;footer slot="footer"&gt;&lt;/footer&gt;
-	&lt;p slot="content"&gt;&lt;/p&gt;
+&lt;/custom-card&gt;
-	&lt;footer slot="footer"&gt;&lt;/footer&gt;
-	&lt;/custom-card&gt;
 {% endraw %}</code></pre>
 
-<strong>Example</strong>
+<h3>Example</h3>
 
 <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" data-small-button>Default</span>
-    <h2 slot="headline">Utopia</h2>
+    <h4 slot="headline">Utopia</h4>
     <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
@@ -70,7 +68,7 @@ title: Card
       ><span class="button" data-small-button>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>
+    <h4 slot="headline">The order does not matter</h4>
   </custom-card>
 
   <custom-card>
@@ -78,7 +76,7 @@ title: Card
       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>
+    <h4 slot="headline">Just title and content</h4>
   </custom-card>
 
   <custom-card no-padding>
@@ -87,6 +85,6 @@ title: Card
       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>
+    <h4 slot="headline">This card has no padding</h4>
   </custom-card>
 </div>

src/docs/config.md

@@ -33,7 +33,7 @@ export default {
 
 ```
 
-**Integration in Eleventy Config**
+### Integration in Eleventy Config
 
 In the main Eleventy configuration file (`eleventy.config.js`), these modules are imported:
 

src/docs/css.md

@@ -8,7 +8,7 @@ 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/).
 
-**New in version 3.0: Inline CSS and bundles**
+### Inline CSS and bundles
 
 The main CSS file is now inline in production to improve performance, see `.src/_includes/head/css-inline.njk`.
 
@@ -24,16 +24,16 @@ You can add per-page or component bundles of CSS. Instead of adding your CSS fil
 
 {% endraw %}
 
-**New in version 3.0: Component CSS**
+### 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**
+### Debugging CSS
 
 In `src/assets/css/global.css` you can decomment `@import-glob 'tests/*.css';` to include CSS for debugging.
 
 It makes visible 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/).
 
-**New in version 4.0: Cascade layers**
+### Cascade layers
 
 We now use cascade layers! Up until now, I used the `:where()` pseudo-class to create low specificity selectors for the reset and compositions. [Mayank inspired me](https://mayank.co/blog/css-reset-layer/) to change to cascade layers. We have two major bundles of CSS: everything included in "global" In `src/assets/css/global/global.css` is now organized in cascade layers. The "local" bundle is for per-page or component CSS, and does not use cascade layers - it has thus a higher specificity, independent of any selector specificity in the global CSS.

src/docs/design-tokens.md

@@ -8,7 +8,7 @@ Additional colors, variants and gradients for custom properties are automaticall
 
 In the [style guide](/styleguide/) you can see how everything turns out.
 
-**Special case: colors**
+### Special case: colors
 
 As of version 4.0, you can create colors dynamically. Run `npm run colors` after setting your color values in `src/_data/designTokens/colorsBase.json`. This will create / overwrite the required `colors.json` file in the same directory. These colors become custom properties (e.g. `--color-gray-100`) and utility classes similar to the Tailwind CSS syntax (for example `bg-gray-100`, `text-gray-900`).
 

src/docs/details.md

@@ -1,6 +1,5 @@
 ---
 title: Details
-usage: "{% set itemList = collections.docs %}{% include 'partials/details.njk' %}"
 ---
 
 The `<custom-details>` WebC component has a corresponding Nunjucks include.
@@ -12,12 +11,16 @@ On page load, it checks if a hash corresponding to a details ID exists in the UR
 
 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
 
+{% raw %}
+```jinja2
+{% set itemList = collections.docs %}
+{% set headingLevel = "h2" %} {# optional, defaults to false #}
+{% include 'partials/details.njk' %}
 ```
-{{ usage | safe }}
+{% endraw %}
-```
 
-**Example**
+### Example
 
 You are in the middle of a custom details component!

src/docs/easteregg.md

@@ -5,18 +5,17 @@ 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**:
+### Defaults:
-  - **Keywords**: `"eleventy"`, `"excellent"`
+  - Keywords: `"eleventy"`, `"excellent"`
-  - **Shape**: `"⭐️"`
+  - Shape: `"⭐️"`
-  - **Particle Count**: `30`
+  - Particle Count: `30`
 
-**Customizable Attributes**:
+### 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
 
-
+```js
-```
 <script type="module" src="/assets/scripts/components/custom-easteregg.js"></script>
 <custom-easteregg keyword="yay" shape="🌈" particle-count="50"></custom-easteregg>
 ```

src/docs/images.md

@@ -6,14 +6,14 @@ Using the [Eleventy Image](https://www.11ty.dev/docs/plugins/image/) plugin, the
 
 Have a look at the [Attribute Overrides](https://www.11ty.dev/docs/plugins/image/#attribute-overrides) for the HTML Transform methods (1 and 2) for per instance overrides. Adding `eleventy:ignore` to an `<img>` element for example, skips this image.
 
-## **1. HTML Transform**
+### 1. HTML Transform
 The HTML Transform automatically processes `<img>` and `<picture>` elements in your HTML files as a post-processing step during the build.
 
 ```html
 <img src="./path/to/image.jpg" alt="alt text">
 ```
 
-## **2. Markdown Syntax**
+### 2. Markdown Syntax
 
 The Markdown syntax creates the `<img>` element that the _HTML Transform plugin_ is looking for, and then transforms it to the `<picture>` element (if more than one format is set).
 
@@ -21,7 +21,7 @@ The Markdown syntax creates the `<img>` element that the _HTML Transform plugin_
 ![alt text](/path/to/image.jpg)
 ```
 
-## **3. Nunjucks Shortcode**
+### 3. Nunjucks Shortcode
 
 In Nunjucks templates you can also use a shortcode.
 

src/docs/masonry.md

@@ -12,7 +12,7 @@ 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`.
 
-```
+```js
 <custom-masonry> (children) </custom-masonry>
 <custom-masonry layout="50-50"> (children) </custom-masonry>
 ```

src/docs/navigation.md

@@ -6,7 +6,7 @@ Edit your navigation items in `src/_data/navigation.js`.
 
 You have two options for mobile navigation: by default, the navigation on small displays is converted to small pills that wrap. This does not require any additional JavaScript.
 
-**Drawer Menu**
+### Drawer Menu
 
 You can activate a drawer menu for mobile in `src/_data/meta.js`:
 
@@ -29,7 +29,7 @@ Adjust your menu breakpoint in `src/_data/designTokens/viewports.json`
 }
 ```
 
-**Submenu**
+### Submenu
 
 You can activate submenus in `src/_data/meta.js`:
 

src/docs/open-graph.md

@@ -59,7 +59,7 @@ export const svgToJpeg = async function () {
 };
 ```
 
-**Regenerating OG images**
+### Regenerating OG images
 
 As you make changes, possibly adjust the title of your post or delete it, the images add up in `src/assets/og-images`. To delete this folder and regenerate all images, you can run `npm run clean:og`.
 

src/docs/svg.md

@@ -4,7 +4,7 @@ title: SVG
 
 All SVG icons used in the starter are in `src/assets/svg`. There is a directory dedicated to the dividers, the platform icons and a general folder called "misc".
 
-**Shortcode**
+### Shortcode
 
 The `svg.js` shortcode, introduced in version 3, allows for the seamless inclusion of SVG files. Located in `src/_config/shortcodes/svg.js`, this shortcode requires only the folder and file name of the SVG, omitting the file extension. By default, SVGs are injected with an `aria-hidden="true"` attribute. The SVGs should be stored in the `src/assets/svg` directory, and referenced using the format `"folder/svg-name"`.
 

src/docs/video.md

@@ -32,7 +32,7 @@ title: Video
 `@slug` unique video identifier for direct links in the `<custom-peertube-link>` fallback
 `@label` Used for accessibility and the `<custom-peertube-link>` fallback.
 
-```
+```html
 <custom-peertube
   @instance="fair.tube"
   @slug="8opkviMc2iDUYMwJzG1FQ4"

src/pages/get-started.md

@@ -19,6 +19,7 @@ The [blog posts](/blog/) also explain / show some features that aren't covered h
 
 <!-- loop docs -->
 {% set itemList = collections.docs %}
+{% set headingLevel = "h2" %}
 {% include 'partials/details.njk' %}
 
 {% css "local" %}