Markdown Style Guide¶

Purpose¶

Defines writing and formatting standards for Markdown documentation in AudioLab. Ensures consistency, readability, and professional quality.

File Structure¶

Front Matter (Optional)¶

---
title: Page Title Here
description: Brief description for SEO and social sharing
author: Your Name
date: 2025-01-15
tags: [audio, dsp, tutorial]
---

Document Structure¶

# Page Title (H1 - Only One Per Page)

Brief introduction paragraph explaining the page's purpose.

## Major Section (H2)

Content for this section.

### Subsection (H3)

Detailed content.

#### Minor Section (H4)

Use sparingly - indicates deep nesting.

## Next Major Section

More content.

Headings¶

Rules¶

One H1 per page - Matches the page title
No skipping levels - Don't jump from H2 to H4
Sentence case - "Getting started" not "Getting Started"
No trailing punctuation - No periods or colons

Examples¶

✅ GOOD
# User guide
## Getting started
### Installation on Windows

❌ BAD
# User Guide                    # Title case
## Getting Started
#### Installation on Windows    # Skipped H3
### Installation on Windows:    # Trailing punctuation

Emphasis and Formatting¶

Bold¶

Use for UI elements, important terms, warnings

Click the **Start** button to begin processing.
**Warning:** This operation cannot be undone.

Italic¶

Use for emphasis, technical terms, variable placeholders

Set the *cutoff frequency* to the desired value.
Replace *username* with your actual username.

Code (Inline)¶

Use for code, function names, file paths, variables

Call the `initialize()` function before processing.
Edit the `config.json` file.
Set the `sampleRate` parameter to 48000.

Bold + Code¶

Use for important code elements

The **`process()`** method is the core of the audio callback.

Lists¶

Unordered Lists¶

Use - (not * or +) for consistency

✅ GOOD
- First item
- Second item
  - Nested item (2 spaces indent)
  - Another nested item
- Third item

❌ BAD
* First item                    # Wrong bullet
+ Second item                   # Wrong bullet
  * Nested item                 # Inconsistent nesting

Ordered Lists¶

Use 1. for all items (auto-numbering)

✅ GOOD
1. First step
1. Second step
1. Third step

✅ ALSO GOOD (manual)
1. First step
2. Second step
3. Second step

❌ BAD
1) First step                   # Wrong syntax
2) Second step

Task Lists¶

- [x] Completed task
- [ ] Incomplete task
- [ ] Another task

Links¶

Internal Links (Same Repository)¶

✅ Relative paths
See the [Parameter Guide](../user-guide/parameters.md)

❌ Absolute paths
See the [Parameter Guide](/docs/user-guide/parameters.md)

External Links¶

✅ Descriptive text
Read the [Doxygen manual](https://www.doxygen.nl/manual/)

❌ Generic text
Click [here](https://www.doxygen.nl/manual/) for the manual

Reference-Style Links (For Reuse)¶

AudioLab uses [Doxygen][doxygen] and [MkDocs][mkdocs] for documentation.

[doxygen]: https://www.doxygen.nl/
[mkdocs]: https://www.mkdocs.org/

Email and Autolinks¶

<support@audiolab.dev>
<https://audiolab.dev>

Code Blocks¶

Syntax Highlighting¶

Always specify language

✅ GOOD
```cpp
float gain = 0.5f;
```

```python
gain = 0.5
```

```bash
cmake --build build
```

❌ BAD
```                             # No language
float gain = 0.5f;
```

Supported Languages¶

cpp / c++ - C++ code
c - C code
python - Python
bash / sh - Shell scripts
powershell / ps1 - PowerShell
cmake - CMake
json - JSON
yaml - YAML
xml - XML
markdown / md - Markdown

Line Highlighting¶

```cpp hl_lines="2 3"
void process(float* buffer, size_t size) {
    for (size_t i = 0; i < size; ++i) {
        buffer[i] *= 0.5f;  // Highlighted line
    }
}
```

Line Numbers¶

```cpp linenums="1"
void process(float* buffer, size_t size) {
    // Implementation
}
```

Titles¶

```cpp title="AudioProcessor.hpp"
class AudioProcessor {
    // ...
};
```

Tables¶

Basic Table¶

| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2   | Cell 3   |
| Cell 4   | Cell 5   | Cell 6   |

Alignment¶

| Left    | Center  | Right   |
|:--------|:-------:|--------:|
| Left    | Center  | Right   |

Complex Tables (Use HTML)¶

<table>
  <tr>
    <th rowspan="2">Header</th>
    <th colspan="2">Spanning Header</th>
  </tr>
  <tr>
    <td>Cell 1</td>
    <td>Cell 2</td>
  </tr>
</table>

Admonitions (Callouts)¶

Available Types¶

!!! note
    Informational note

!!! tip "Custom Title"
    Helpful tip

!!! warning
    Important warning

!!! danger
    Critical warning

!!! example
    Code example

!!! quote
    Quotation

!!! info
    General information

Collapsible¶

??? note "Click to expand"
    Hidden content that can be expanded

Inline Code in Admonitions¶

!!! note "Function Signature"
    ```cpp
    void process(float* buffer, size_t size);
    ```

Images¶

Basic Image¶

![Alt text](path/to/image.png)

Image with Title¶

![Alt text](path/to/image.png "Hover title")

Centered Image with Caption¶

<figure markdown>
  ![Audio Pipeline](../images/pipeline.png)
  <figcaption>AudioLab processing pipeline</figcaption>
</figure>

Image Sizing (HTML)¶

<img src="image.png" alt="Description" width="400">

Diagrams (Mermaid)¶

Flowchart¶

```mermaid
flowchart LR
    A[Input] --> B{Process?}
    B -->|Yes| C[Process]
    B -->|No| D[Bypass]
    C --> E[Output]
    D --> E
```

Sequence Diagram¶

```mermaid
sequenceDiagram
    participant User
    participant Plugin
    participant DSP

    User->>Plugin: Set Parameter
    Plugin->>DSP: Update
    DSP-->>Plugin: Acknowledge
    Plugin-->>User: UI Update
```

Class Diagram¶

```mermaid
classDiagram
    class AudioBuffer {
        +getNumChannels()
        +getNumSamples()
        +getChannelData()
    }
    class AudioProcessor {
        +process(buffer)
        +initialize(sampleRate)
    }
    AudioProcessor --> AudioBuffer
```

Math Formulas (MathJax)¶

Inline Math¶

The gain formula is $y = x \times g$ where $g$ is the gain value.

Block Math¶

$$
y[n] = x[n] + \alpha \cdot x[n-1]
$$

Common Formulas¶

Decibels: $dB = 20 \log_{10}(amplitude)$

Frequency: $f = \frac{1}{T}$ where $T$ is the period

Filter: $H(z) = \frac{b_0 + b_1 z^{-1}}{1 + a_1 z^{-1}}$

Footnotes¶

AudioLab uses lock-free queues[^1] for real-time safety.

[^1]: See "Lock-Free Programming" by Herb Sutter

Abbreviations¶

The HTML specification is maintained by the W3C.

*[HTML]: Hyper Text Markup Language
*[W3C]: World Wide Web Consortium

Keyboard Keys¶

Press ++ctrl+c++ to copy.
Press ++cmd+v++ to paste on macOS.

Content Tabs¶

=== "C++"
    ```cpp
    float gain = 0.5f;
    ```

=== "Python"
    ```python
    gain = 0.5
    ```

Line Length¶

Prose¶

Soft limit: 80 characters
Hard limit: 100 characters
Exception: URLs, code, tables

Code Blocks¶

Limit: 88 characters (match Black formatter)
Exception: Long strings, URLs

Whitespace¶

Blank Lines¶

✅ GOOD
## Heading

Content paragraph.

Another paragraph.

✅ ALSO GOOD (code block)

Content before code.

```cpp
code();

Content after code.

❌ BAD (too many blank lines)

Heading¶

Content paragraph.

### List Spacing
```markdown
✅ Tight list (related items)
- Item 1
- Item 2
- Item 3

✅ Loose list (complex items)
- Item 1 with long explanation
  that spans multiple lines.

- Item 2 with its own
  detailed explanation.

Common Patterns¶

File Path References¶

Edit the file `2 - FOUNDATION/04_CORE/AudioBuffer.hpp`.

Command Examples¶

```bash
# Build the project
cmake --build build --config Release

# Run tests
ctest --test-dir build
```

API References¶

The [`AudioBuffer`](api-reference.md#audiobuffer) class provides...

Version References¶

!!! info "Version 2.0+"
    This feature requires AudioLab 2.0 or later.

TODO Markers¶

<!-- TODO: Add performance benchmarks -->
<!-- FIXME: Update screenshot after UI redesign -->

Accessibility¶

Alt Text¶

✅ GOOD - Descriptive
![Frequency response graph showing lowpass filter cutoff at 1kHz](filter.png)

❌ BAD - Generic
![Image](filter.png)

Link Text¶

✅ GOOD - Descriptive
Download the [AudioLab SDK](https://audiolab.dev/sdk)

❌ BAD - Generic
[Click here](https://audiolab.dev/sdk) to download

Headings¶

Use logical hierarchy
Don't skip levels
Use descriptive text (not "Introduction" for everything)

Validation¶

Lint with markdownlint¶

# Install
npm install -g markdownlint-cli

# Check files
markdownlint **/*.md

Check Links¶

# Install markdown-link-check
npm install -g markdown-link-check

# Check links
markdown-link-check README.md

Spell Check¶

# Use cSpell
npm install -g cspell

# Check spelling
cspell "**/*.md"

References¶

CommonMark Spec: https://spec.commonmark.org/
Material for MkDocs: https://squidfunk.github.io/mkdocs-material/reference/
Markdown Guide: https://www.markdownguide.org/
GitHub Flavored Markdown: https://github.github.com/gfm/