This guide defines the consistent formatting standards for all documentation pages in the ByDefault project.

Overview

All markdown files should follow these standardized patterns to ensure:

  • Consistent visual hierarchy - Clear heading structure and spacing
  • Readable content - Proper list formatting and code block styling
  • Maintainable structure - Standardized dividers and organization
  • Professional appearance - Clean, modern documentation styling

Frontmatter

Every markdown file must start with YAML frontmatter between delimiters. The generator reads these fields to determine page output, navigation, access control, and rendering.

Core Fields

Field Required Default Description
title Yes filename Page heading and browser tab title
subtitle No Secondary heading below the title
description No Meta description for SEO and social sharing
section No uncategorized Navigation group — determines output folder (Brand Book, Design System, Docs, Tools, Projects, Website)
layer Yes Architectural layer: foundation, core, docs-site, or app. Build aborts if missing or invalid. See §17 in CLAUDE.md.
author No "Studio" Page author name. Renders inside book cover cards as "by {author}".
subsection No Sub-category within a section for nav grouping
order No 999 Sort position within section (lower = first)
status No published Set to "draft" to exclude from generation
access No team Visibility: "public", "team", "admin", "client", "admin+client"
client No internal Client scope: "internal", "all", or a specific client key

Action Button Fields

Any page can display a header button linking to an external resource (tool, Figma file, etc).

Field Required Default Description
actionUrl No URL for the header button
actionLabel No Open Button text
actionAccess No Visibility control for the button on client pages

Enhancement Fields

Field Required Default Description
dropcap No Set to "true" to style the first paragraph with a drop cap
scripts No Comma-separated script names to inject (e.g. "splide, notion-form")

Available scripts: gsap, scroll-trigger, split-text, scroll-smoother, draggable, scroll-to, bd-animations, bd-audio, bd-cursor, splide, splide-auto-scroll, splide-intersection, notion-form

Opt-out Flags

These flags suppress parts of the standard page layout. All default to enabled — set to false only when needed.

Field Default Effect when false
toc true Suppresses the table of contents block
sticky-bar true Suppresses the sticky sub-bar (breadcrumb + section dropdown)
pagination true Suppresses the prev/next page nav at the bottom

Example

---
title: "CPM Calculator"
subtitle: "Plan campaign impressions, fees, and payouts"
description: "Calculate campaign impressions, fees, payouts, and margins."
section: "Tools"
layer: "app"
author: "Studio"
order: 1
status: "published"
access: "admin"
client: "internal"
actionUrl: "./cpm-calculator.html"
actionLabel: "Open Tool"
actionAccess: "public"
---

Headers

Your Primary Headline, Big, Bold, and Unmissable

Supporting Headline to Guide Your Content

Section Headings to Keep Content Organised

Smaller Subheading for Detailed Content Organisation

Compelling Statement That Captures Attention Instantly
Clear Navigation Heading for Important Information
# Your Primary Headline, Big, Bold, and Unmissable

## Supporting Headline to Guide Your Content

### Section Headings to Keep Content Organised

#### Smaller Subheading for Detailed Content Organisation

##### Compelling Statement That Captures Attention Instantly

###### Clear Navigation Heading for Important Information

Emphasis

This paragraph demonstrates how body text will look across your layout. Bold text adds emphasis, while italics offer a subtle highlight. You can also use strikethrough to show edits. Combined emphasis with asterisks and underscores for clarity.

This paragraph demonstrates how body text will look across your layout. **Bold text** adds emphasis, while *italics* offer a subtle highlight. You can also use ~~strikethrough~~ to show edits. Combined emphasis with **asterisks and _underscores_** for clarity.

Lists

Typography principles for effective design:

  1. Readability - Use clear, legible typefaces

  2. Hierarchy - Establish visual order with size and weight

    • Larger sizes for headings
    • Medium sizes for subheadings
    • Standard sizes for body text
  3. Spacing - Create breathing room between elements

    1. Letter spacing for clarity
    2. Line height for readability
    3. Paragraph spacing for flow
  4. Consistency - Maintain uniform styling throughout

    You can have properly indented paragraphs within list items. This extended paragraph serves to demonstrate how substantial blocks of text will behave across your layout, giving you a realistic sense of how readers will experience longer-form content.

    To have a line break without a paragraph, you will need to use two trailing spaces.
    This maintains readability while keeping content compact.
    (This is particularly useful for documentation where precision matters.)

  • Unordered lists can use asterisks
  • Or minuses
  • Or pluses
Typography principles for effective design:

1. **Readability** - Use clear, legible typefaces
2. **Hierarchy** - Establish visual order with size and weight
   * Larger sizes for headings
   * Medium sizes for subheadings
   * Standard sizes for body text
1. **Spacing** - Create breathing room between elements
   1. Letter spacing for clarity
   2. Line height for readability
   3. Paragraph spacing for flow
4. **Consistency** - Maintain uniform styling throughout

   You can have properly indented paragraphs within list items. This extended paragraph serves to demonstrate how substantial blocks of text will behave across your layout, giving you a realistic sense of how readers will experience longer-form content.

   To have a line break without a paragraph, you will need to use two trailing spaces.  
   This maintains readability while keeping content compact.  
   (This is particularly useful for documentation where precision matters.)

* Unordered lists can use asterisks
- Or minuses
+ Or pluses

Nested Lists

  1. Type with Purpose
    1. Design with Intent
      1. Making Letters Matter
        1. Typography That Tells Your Story
  2. From Serif to Sans
1. Type with Purpose
   1. Design with Intent
      1. Making Letters Matter
         1. Typography That Tells Your Story
2. From Serif to Sans
  • Fonts That Speak Volumes
    • Modern Design Principles
      • Visual Hierarchy
        • Content Organization
  • Strategic Typography
* Fonts That Speak Volumes
  * Modern Design Principles
    * Visual Hierarchy
      * Content Organization
* Strategic Typography

Task Lists

  • Review heading hierarchy
  • Document font scales
  • Update spacing guidelines
    • Define line heights
    • Create usage examples
- [ ] Review heading hierarchy
- [x] Document font scales
- [ ] Update spacing guidelines
  - [x] Define line heights
  - [ ] Create usage examples

For further information, check out this link, which will take you to another page.

Visit ByDefault Studio for comprehensive guidelines.

Or leave it empty and use the link text itself

Some text to show that the reference links can follow later.

For further information, check out [this link](overview.html), which will take you to another page.

Visit [ByDefault Studio](https://bydefault.studio "ByDefault Design System") for comprehensive guidelines.


Or leave it empty and use the [link text itself]

Some text to show that the reference links can follow later.

[tokens]: https://bydefault.studio/design-system#tokens
[typography]: https://bydefault.studio/design-system#typography
[1]: https://bydefault.studio
[link text itself]: https://bydefault.studio/contact

Images

Here's the ByDefault favicon (hover to see the title text):

Inline-style: ByDefault Favicon

Reference-style:
ByDefault Logo

Here's the ByDefault favicon (hover to see the title text):

Inline-style: ![ByDefault Favicon](../assets/icons/favicon.svg "ByDefault Studio Favicon")

Reference-style:
![ByDefault Logo][logo]

[logo]: ../assets/icons/favicon.svg "ByDefault Studio Logo"

HTML in Markdown

Since the documentation generator allows HTML, you can use HTML directly in markdown files to add styling classes and create custom layouts.

Image with Classes

You can use HTML <img> tags to add design system classes:

Example image
<img src="assets/images/og-default.jpg" alt="Example image" class="border border-secondary padding-m max-width-full">

HTML Blocks

You can create custom blocks with design system classes:

Custom Block Example

This is a custom HTML block with a heading, text, and button. You can use any design system classes to style it.

<div class="block gap-l border border-secondary padding-l">
  <h3>Custom Block Example</h3>
  <p>This is a custom HTML block with a heading, text, and button. You can use any design system classes to style it.</p>
  <button class="button">Action Button</button>
</div>

Note: HTML in markdown gives you full control over styling. Use design system classes (block, gap-*, border, padding-*, button, etc.) to maintain consistency with the rest of the documentation.


Code and Syntax Highlighting

The ByDefault design system uses CSS custom properties for all design tokens. Inline code has back-ticks around it for clarity.

:root {
  /* Typography tokens */
  --font-primary: "Arial", sans-serif;
  --font-s: 16px;
  --line-height-l: 1.4;
  
  /* Color tokens */
  --text-plain: var(--black);
  --text-link: var(--green);
  --background-plain: var(--white);
}
// Design system token usage
const designTokens = {
  spacing: {
    xs: 'var(--space-xs)',
    s: 'var(--space-s)',
    m: 'var(--space-m)'
  },
  colors: {
    primary: 'var(--text-primary)',
    accent: 'var(--text-link)'
  }
};
No language indicated, so no syntax highlighting.
Use this for plain text examples or design notes.

Markdown code (shown as indented code block):

The ByDefault design system uses `CSS custom properties` for all design tokens. Inline `code` has `back-ticks around` it for clarity.

```css
:root {
  /* Typography tokens */
  --font-primary: "Arial", sans-serif;
  --font-s: 16px;
  --line-height-l: 1.4;
  
  /* Color tokens */
  --text-plain: var(--black);
  --text-link: var(--green);
  --background-plain: var(--white);
}
```

```javascript
// Design system token usage
const designTokens = {
  spacing: {
    xs: 'var(--space-xs)',
    s: 'var(--space-s)',
    m: 'var(--space-m)'
  },
  colors: {
    primary: 'var(--text-primary)',
    accent: 'var(--text-link)'
  }
};
```

```
No language indicated, so no syntax highlighting.
Use this for plain text examples or design notes.
```

Tables

Design system spacing tokens:

Token Value Pixels Usage
0.25rem 4px Tight spacing
0.5rem 8px Small gaps
0.75rem 12px Medium spacing
1rem 16px Standard spacing
1.5rem 24px Large spacing

Typography scale tokens:

Token Size Line Height Use Case
14px 1.4 Small text
16px 1.4 Body text
18px 1.4 Default
20px 1.4 Subheadings
22px 1.2 Headings
Design system spacing tokens:

| Token | Value | Pixels | Usage |
| ----- |:-----:| -----: | ----- |
| `--space-xs` | 0.25rem | 4px | Tight spacing |
| `--space-s` | 0.5rem | 8px | Small gaps |
| `--space-m` | 0.75rem | 12px | Medium spacing |
| `--space-l` | 1rem | 16px | Standard spacing |
| `--space-xl` | 1.5rem | 24px | Large spacing |

Typography scale tokens:

| Token | Size | Line Height | Use Case |
| --- | --- | --- | --- |
| `--font-xs` | 14px | 1.4 | Small text |
| `--font-s` | 16px | 1.4 | Body text |
| `--font-m` | 18px | 1.4 | Default |
| `--font-l` | 20px | 1.4 | Subheadings |
| `--font-xl` | 22px | 1.2 | Headings |

Blockquotes

Words matter, but how those words are presented matters just as much. Typography transforms content from mundane to magical, from ordinary to extraordinary.

Typography is more than style; it's about communication. The right type makes content readable, relatable, and engaging, drawing readers into the heart of the message.

The details are not the details. They make the design. — Charles Eames

> Words matter, but how those words are presented matters just as much. Typography transforms content from mundane to magical, from ordinary to extraordinary.

> Typography is more than style; it's about communication. The right type makes content readable, relatable, and engaging, drawing readers into the heart of the message.

> The details are not the details. They make the design. — Charles Eames

Nested Blockquotes

Typography is the craft of endowing human language with a durable visual form.

Good design is as little design as possible. — Dieter Rams

Every letter, every space, serves a purpose in creating cohesive digital experiences.

> Typography is the craft of endowing human language with a durable visual form.
>
> > Good design is as little design as possible. — Dieter Rams
>
> Every letter, every space, serves a purpose in creating cohesive digital experiences.

Blockquotes with Other Elements

Typography Principles

  1. Readability - Use clear, legible typefaces
  2. Hierarchy - Establish visual order with size and weight

Here's how to apply spacing:

padding: var(--space-l);
margin: var(--space-xl);
> ## Typography Principles
>
> 1.   **Readability** - Use clear, legible typefaces
> 2.   **Hierarchy** - Establish visual order with size and weight
>
> Here's how to apply spacing:
>
>     padding: var(--space-l);
>     margin: var(--space-xl);

Horizontal Rule

Section break


Typography section


Design tokens section


Content organization section

Section break

---

Typography section

***

Design tokens section

___

Content organization section

Line Breaks

This paragraph demonstrates how body text will look across your layout. Bold text adds emphasis, while italics offer a subtle highlight.

This line is separated from the one above by two newlines, so it will be a separate paragraph.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line in the same paragraph.

This paragraph demonstrates how body text will look across your layout. **Bold text** adds emphasis, while *italics* offer a subtle highlight.

This line is separated from the one above by two newlines, so it will be a *separate paragraph*.

This line is also a separate paragraph, but...
This line is only separated by a single newline, so it's a separate line in the *same paragraph*.

Visit our website: https://bydefault.studio

Contact us: hello@bydefault.studio

Visit our website: <https://bydefault.studio>

Contact us: <hello@bydefault.studio>

Best Practices

Content Guidelines

  • Be concise - Get to the point quickly
  • Use examples - Show, don't just tell
  • Be consistent - Follow established patterns
  • Test thoroughly - Verify all code examples work

Formatting Guidelines

  • Consistent spacing - Use blank lines appropriately
  • Proper hierarchy - Use headings logically
  • Clean code blocks - Always include language tags
  • Readable lists - Use proper indentation

Maintenance

  • Regular reviews - Check for consistency
  • Update examples - Keep code current
  • Test changes - Verify formatting works
  • Follow standards - Use this guide as reference

Was this page helpful?

We use this feedback to improve our documentation.

Thanks for your feedback