From 96cb292183bd9274f2276cb359f833bbb5ae5076 Mon Sep 17 00:00:00 2001 From: madrilene Date: Fri, 24 Oct 2025 12:50:46 +0200 Subject: [PATCH] fix: hierarchical heading structure for docs --- src/assets/css/local/details.css | 29 ++++++++---------- src/docs/card.njk | 52 +++++++++++++++----------------- src/docs/config.md | 2 +- src/docs/css.md | 8 ++--- src/docs/design-tokens.md | 2 +- src/docs/details.md | 13 +++++--- src/docs/easteregg.md | 13 ++++---- src/docs/images.md | 6 ++-- src/docs/masonry.md | 2 +- src/docs/navigation.md | 4 +-- src/docs/open-graph.md | 2 +- src/docs/svg.md | 2 +- src/docs/video.md | 2 +- src/pages/get-started.md | 1 + 14 files changed, 68 insertions(+), 70 deletions(-) diff --git a/src/assets/css/local/details.css b/src/assets/css/local/details.css index d5afab7..4f9805e 100644 --- a/src/assets/css/local/details.css +++ b/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) { - font-weight: var(--font-bold); - font-size: var(--size-step-0); - border-block-end: var(--stroke); - padding-block-end: var(--space-xs); +.details details > :is(h2, h3, h4) { + font-family: var(--font-body); } -.details details > :is(h2, h3) { - font-weight: var(--font-bold); +.details details > h2 { + 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); } diff --git a/src/docs/card.njk b/src/docs/card.njk index 4996337..fd65a8f 100644 --- a/src/docs/card.njk +++ b/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.

-

Available slots:

+

Available slots:

I added some variants, avaliable via attribute selectors:

-Usage +

Usage

-
{% raw %}
-  
-  <custom-card>
-	{% image "path-to-img", "alt-text" %}
-	<span slot="date"></span>
-	<span slot="tag" class="button"></span>
-	<h2 slot="headline"></h2>
-	<p slot="content"></p>
-	<footer slot="footer"></footer>
-	</custom-card>
+
{% raw %}<custom-card>
+{% image "path-to-img", "alt-text" %}
+<span slot="date"></span>
+<span slot="tag" class="button"></span>
+<h2 slot="headline"></h2>
+<p slot="content"></p>
+<footer slot="footer"></footer>
+</custom-card>
 {% endraw %}

 
-Example
+
Example

 
 

   
     {% image "./src/assets/images/gallery/asturias-3.jpg", "Close-up of a delicate white flower with a yellow center, surrounded by green leaves" %}
     1516
     Default
-    
Utopia

+    
Utopia

     

       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
       >square image
     

     
-    
The order does not matter

+    
The order does not matter

   
 
   
@@ -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 [...].
     

-    
Just title and content

+    
Just title and content

   
 
   
@@ -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."
     

-    
This card has no padding

+    
This card has no padding

   
 
diff --git a/src/docs/config.md b/src/docs/config.md
index 6301fab..3e28b14 100644
--- a/src/docs/config.md
+++ b/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:
 
diff --git a/src/docs/css.md b/src/docs/css.md
index 2d2c4fd..4a3aae1 100644
--- a/src/docs/css.md
+++ b/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 `` 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.
\ No newline at end of file
diff --git a/src/docs/design-tokens.md b/src/docs/design-tokens.md
index 9a11fa2..f24979c 100644
--- a/src/docs/design-tokens.md
+++ b/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`).
 
diff --git a/src/docs/details.md b/src/docs/details.md
index bb55644..5e5d991 100644
--- a/src/docs/details.md
+++ b/src/docs/details.md
@@ -1,6 +1,5 @@
 ---
 title: Details
-usage: "{% set itemList = collections.docs %}{% include 'partials/details.njk' %}"
 ---
 
 The `` 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!
\ No newline at end of file
diff --git a/src/docs/easteregg.md b/src/docs/easteregg.md
index 99214b6..3702286 100644
--- a/src/docs/easteregg.md
+++ b/src/docs/easteregg.md
@@ -5,18 +5,17 @@ title: Easteregg
 The `` 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`
+### Defaults:
+  - Keywords: `"eleventy"`, `"excellent"`
+  - Shape: `"⭐️"`
+  - 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
 
 
 ```
diff --git a/src/docs/images.md b/src/docs/images.md
index 8617288..8bc9fe0 100644
--- a/src/docs/images.md
+++ b/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 `` element for example, skips this image.
 
-## **1. HTML Transform**
+### 1. HTML Transform
 The HTML Transform automatically processes `` and `` elements in your HTML files as a post-processing step during the build.
 
 ```html
 alt text
 ```
 
-## **2. Markdown Syntax**
+### 2. Markdown Syntax
 
 The Markdown syntax creates the `` element that the _HTML Transform plugin_ is looking for, and then transforms it to the `` element (if more than one format is set).
 
@@ -21,7 +21,7 @@ The Markdown syntax creates the `` 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.
 
diff --git a/src/docs/masonry.md b/src/docs/masonry.md
index 9e11495..cd5a90e 100644
--- a/src/docs/masonry.md
+++ b/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
  (children) 
  (children) 
 ```
diff --git a/src/docs/navigation.md b/src/docs/navigation.md
index 55d9cb2..8bed106 100644
--- a/src/docs/navigation.md
+++ b/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`:
 
diff --git a/src/docs/open-graph.md b/src/docs/open-graph.md
index 36dcbdd..5597261 100644
--- a/src/docs/open-graph.md
+++ b/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`.
 
diff --git a/src/docs/svg.md b/src/docs/svg.md
index 96cdf48..71193a9 100644
--- a/src/docs/svg.md
+++ b/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"`.
 
diff --git a/src/docs/video.md b/src/docs/video.md
index 806e0df..0894d6b 100644
--- a/src/docs/video.md
+++ b/src/docs/video.md
@@ -32,7 +32,7 @@ title: Video
 `@slug` unique video identifier for direct links in the `` fallback
 `@label` Used for accessibility and the `` fallback.
 
-```
+```html
 
 {% set itemList = collections.docs %}
+{% set headingLevel = "h2" %}
 {% include 'partials/details.njk' %}
 
 {% css "local" %}