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:
Readability - Use clear, legible typefaces
Hierarchy - Establish visual order with size and weight
- Larger sizes for headings
- Medium sizes for subheadings
- Standard sizes for body text
Spacing - Create breathing room between elements
- Letter spacing for clarity
- Line height for readability
- Paragraph spacing for flow
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
- Type with Purpose
- Design with Intent
- Making Letters Matter
- Typography That Tells Your Story
- Making Letters Matter
- Design with Intent
- 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
- Visual Hierarchy
- Modern Design Principles
- 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
Links
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:
Reference-style:
Here's the ByDefault favicon (hover to see the title text):
Inline-style: 
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:
<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
- Readability - Use clear, legible typefaces
- 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*.
Automatic Links
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