fix: hierarchical heading structure for docs

2025-10-24 12:50:46 +02:00 · 2025-10-24 12:50:46 +02:00 · 96cb292183
commit 96cb292183
parent 66e042825f
14 changed files with 68 additions and 70 deletions
--- 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);
 }
--- 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.
 </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>picture</code> or <code>figure</code> wrapper by default!
+    <code>image</code>: has <code>slot="image"</code> on the
+    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
-    information.
+    <code>date</code> and <code>tag</code>: 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>
+  <li><code>content</code></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>clickable</code>: Makes the whole card clickable.</li>
-  <li><code>no-padding</code>: Removes padding and background modifications.</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>no-padding</code>: Removes padding and background modifications</li>
 </ul>

-<strong>Usage</strong>
+<h3>Usage</h3>

-<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"&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;
+<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"&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>
+<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>
--- 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:

--- 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 `<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.
--- 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`).

--- 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 `<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!
--- a/src/docs/easteregg.md
+++ b/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**:
-  - **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
 <script type="module" src="/assets/scripts/components/custom-easteregg.js"></script>
 <custom-easteregg keyword="yay" shape="🌈" particle-count="50"></custom-easteregg>
 ```
--- 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 `<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.

--- 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
 <custom-masonry> (children) </custom-masonry>
 <custom-masonry layout="50-50"> (children) </custom-masonry>
 ```
--- 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`:

--- 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`.

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

--- 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 `<custom-peertube-link>` fallback
 `@label` Used for accessibility and the `<custom-peertube-link>` fallback.

-```
+```html
 <custom-peertube
  @instance="fair.tube"
  @slug="8opkviMc2iDUYMwJzG1FQ4"
--- a/src/pages/get-started.md
+++ b/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" %}