Add documentation pages

.github/workflows/ci.yml

@@ -54,3 +54,14 @@ jobs:
           python-version: ${{ matrix.python-version }}
       - run: uv sync --group dev
       - run: uv run pytest
+
+  docs:
+    name: Docs (mkdocs)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+      - run: uv sync --group docs
+      - run: uv run mkdocs build --strict

.github/workflows/docs.yml

@@ -0,0 +1,59 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "overrides/**"
+      - "mkdocs.yml"
+      - "pyproject.toml"
+      - "uv.lock"
+      - "scripts/generate_step_docs.py"
+      - "normalization/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build MkDocs site
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: uv sync --group docs
+
+      - name: Build site
+        run: uv run mkdocs build --strict
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: site
+
+  deploy:
+    name: Deploy to GitHub Pages
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -17,4 +17,7 @@ wheels/
 .vscode/
 .idea/
 .cursor/
-.claude/
+.claude/
+
+# MkDocs
+site/

AGENTS.md

@@ -157,4 +157,4 @@ Never modify a published preset YAML. Never let a preset reference a step that h
 - [ ] Add unit tests in `tests/unit/steps/`
 - [ ] If it involves placeholder protection, add both protect and restore to `steps/text/placeholders.py` and update `pipeline/base.py`'s `validate()` accordingly; use `ProtectStep`/`RestoreStep` base classes where the contract fits, otherwise use `TextStep` directly and document why in the docstring
 - [ ] Add the step name to relevant preset YAMLs if needed (new preset version if existing presets are affected)
-- [ ] If you added or changed the class docstring, run `python scripts/generate_step_docs.py` to regenerate `docs/steps.md`
+- [ ] If you added or changed the class docstring, run `python scripts/generate_step_docs.py` to regenerate `docs/reference/steps.md`

CONTRIBUTING.md

@@ -20,7 +20,7 @@ A new language requires:
 4. Decorate with `@register_language` and add one import to `normalization/languages/__init__.py`
 5. Add tests under `tests/unit/languages/` and a per-language CSV in `tests/e2e/files/{preset}/` (e.g. `tests/e2e/files/gladia-3/fr.csv`)
 
-See [docs/contributing-guide.md](docs/contributing-guide.md) for the full checklist and design rules.
+See [docs/contributing/guide.md](docs/contributing/guide.md) for the full checklist and design rules.
 
 ### Add a new normalization step
 
@@ -33,9 +33,9 @@ A new step requires:
 3. Add an import to `steps/text/__init__.py` or `steps/word/__init__.py`
 4. Add unit tests under `tests/unit/steps/`
 5. Add the step name to the relevant preset YAML, or create a new preset version
-6. If you added or changed the class docstring, regenerate `docs/steps.md`: `uv run scripts/generate_step_docs.py`
+6. If you added or changed the class docstring, regenerate `docs/reference/steps.md`: `uv run scripts/generate_step_docs.py`
 
-See [docs/contributing-guide.md](docs/contributing-guide.md) for base class selection and test conventions.
+See [docs/contributing/guide.md](docs/contributing/guide.md) for base class selection and test conventions.
 
 ### Report a bug
 
@@ -52,7 +52,7 @@ Open a GitHub issue with the `question` label. We're happy to help.
 ```bash
 git clone https://github.com/gladiaio/normalization.git
 cd normalization
-uv sync
+uv sync --all-groups
 uv run pre-commit install --install-hooks   # install hooks once
 ```
 
@@ -63,6 +63,7 @@ uv run pytest               # run tests
 uv run ruff check .         # lint
 uv run ruff format .        # format
 uv run ty check             # type-check
+uv run mkdocs serve         # preview docs at http://127.0.0.1:8000
 ```
 
 ---

README.md

@@ -3,7 +3,7 @@
   <p align="center">
     A lightweight library for normalizing speech transcripts before computing WER.
     <br />
-    <a href="#quick-start">Quick Start</a> &middot; <a href="docs/steps.md">Step Reference</a> &middot; <a href="CONTRIBUTING.md">Contributing</a>
+    <a href="#quick-start">Quick Start</a> &middot; <a href="https://gladiaio.github.io/normalization/">Documentation</a> &middot; <a href="CONTRIBUTING.md">Contributing</a>
   </p>
 </p>
 
@@ -106,7 +106,7 @@ Every pipeline runs exactly **three stages**, always in this order:
 
 This ordering is a hard constraint. Some steps depend on earlier steps having run (e.g. a placeholder protecting a decimal point in Stage 1 must be restored in Stage 3, so that `remove_symbols` doesn't destroy it in between).
 
-Pipelines are defined declaratively in **YAML presets**. Each preset lists the steps that run in each stage and the order they run in. See the full [step reference](docs/steps.md) for every available step.
+Pipelines are defined declaratively in **YAML presets**. Each preset lists the steps that run in each stage and the order they run in. See the full [step reference](https://gladiaio.github.io/normalization/reference/steps/) for every available step.
 
 ## Supported languages
 
@@ -120,6 +120,7 @@ Pipelines are defined declaratively in **YAML presets**. Each preset lists the s
 | `fr` | French   |
 | `it` | Italian  |
 | `nl` | Dutch    |
+| `no` | Norwegian |
 | `sv` | Swedish  |
 
 Unsupported language codes fall back to a safe default that applies language-independent normalization only.
@@ -140,15 +141,13 @@ stages:
     - casefold_text
     - remove_symbols
     - remove_diacritics
-    - normalize_whitespace
 
   word:
     - apply_word_replacements
 
   text_post:
     - restore_email_at_symbol_with_word
     - restore_email_dot_symbol_with_word
-    - normalize_whitespace
 ```
 
 _Load from your custom configuration:_

docs/concepts.md

@@ -0,0 +1,33 @@
+# How it works
+
+Every pipeline runs **three stages**, always in this order:
+
+```text
+text  >  [1] text_pre  >  split  >  [2] word  >  join  >  [3] text_post  >  text
+```
+
+| Stage | Operates on | Typical work |
+| --- | --- | --- |
+| **1. Text pre** | Full string | Protect symbols, expand contractions/numbers, convert currency/degrees, casefold, remove punctuation |
+| **2. Word** | One token | Replacements (`vs` → `versus`), skip emails |
+| **3. Text post** | Full string | Restore placeholders, format times, collapse digits, whitespace |
+
+This order is a hard constraint. Placeholder steps illustrate why: a decimal point is **protected** in stage 1 so `remove_symbols` cannot erase it, then **restored** in stage 3.
+
+## Steps
+
+A step is a small, stateless transform with a unique `name`. Steps register themselves via `@register_step`; presets reference those names.
+
+See the full [step reference](reference/steps.md).
+
+## Presets
+
+A preset is a YAML file that lists which steps run in each stage and in what order. Published presets are **immutable** — new behavior means a new preset file (e.g. `gladia-4`).
+
+Details and custom YAML: [Presets](presets.md).
+
+## Languages
+
+Language-specific data and behavior live under `normalization/languages/`. Unknown codes fall back to a language-agnostic default.
+
+Details: [Languages](languages.md).