DEV: Add the Markbridge documentation site

.github/dependabot.yml

@@ -24,3 +24,17 @@ updates:
       gems:
         patterns:
           - "*"
+
+  - package-ecosystem: npm
+    directory: "/docs"
+    schedule:
+      interval: "weekly"
+    commit-message:
+      prefix: "DEPS"
+    versioning-strategy: increase
+    allow:
+      - dependency-type: "all"
+    groups:
+      docs:
+        patterns:
+          - "*"

.github/workflows/docs.yml

@@ -0,0 +1,52 @@
+name: Deploy docs to Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  release:
+    types: [published, edited, deleted]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Per-ref so a PR build never queues behind (or blocks) a main deploy.
+# Cancel superseded PR builds; never cancel an in-flight deploy.
+concurrency:
+  group: pages-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: withastro/action@v6
+        with:
+          path: ./docs
+          # Astro requires Node 22.12 or newer.
+          node-version: 22
+          # pnpm version comes from the "packageManager" field in
+          # docs/package.json — passing it here too makes pnpm/action-setup
+          # error with "Multiple versions of pnpm specified".
+
+  deploy:
+    needs: build
+    # PRs validate the build only; deploy happens on push to main / release.
+    if: github.event_name != 'pull_request'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.rubocop.yml

@@ -18,5 +18,6 @@ Lint/UnusedMethodArgument:
 
 RSpec/DescribeClass:
   Exclude:
+    - spec/docs/**/*
     - spec/integration/**/*
     - spec/system/**/*

.silo.yml

@@ -12,20 +12,27 @@ use:
     default: "4.0"
 
 setup:
+  - sudo dnf update -y
+  # Node + pnpm for the docs site (Astro/Starlight); both ship as Fedora packages.
+  - sudo dnf install -y nodejs pnpm
   - bundle install
-  - bundle exec lefthook install
+  - bundle exec lefthook install -f
+  - (cd docs && CI=true pnpm install)
 
 sync:
   - bundle install
+  - (cd docs && CI=true pnpm install)
 
 update:
   - sudo dnf update -y
   - rv self update
 
-ports:
-  - 4567:4567
-
 daemons:
   playground:
     cmd: bin/playground
+    ports: ["4567"]
+    autostart: true
+  docs:
+    cmd: bin/docs
+    ports: ["4321"]
     autostart: true

AGENTS.md

@@ -4,7 +4,7 @@ Quick reference guide for AI assistants working on the Markbridge codebase.
 
 ## Project Overview
 
-**Markbridge** converts BBCode to Discourse-flavored Markdown using a **Parse → AST → Render** pipeline.
+**Markbridge** converts BBCode, HTML, MediaWiki, and s9e TextFormatter XML to Markdown using a **Parse → AST → Render** pipeline. The shipped renderer produces Discourse-flavored Markdown. The parsers and AST are renderer-agnostic.
 
 **Design Philosophy:**
 - Graceful degradation (unknown tags preserved, no exceptions)
@@ -155,7 +155,7 @@ check ships as a shared RSpec example (`require "markbridge/rspec"`,
 then `it_behaves_like "an html_mode safe tag"`), so consumer projects
 can run it against their own tags.
 
-**See `examples/` for complete examples.**
+**See `docs/src/content/docs/customization/extending.md` for complete examples.**
 
 ## Development Workflow
 
@@ -217,7 +217,7 @@ automatically when mutation work comes up.
 bundle exec ruby --yjit bench/bench.rb --isolated`). It pins the process
 to the fastest cores and reports power and governor state. Results from
 a laptop on battery, or from an efficiency core, don't compare with
-the numbers in `docs/benchmarks.md`.
+the numbers in `docs/src/content/docs/concepts/benchmarks.md`.
 
 **MarkdownEscaper** is a hot path. Benchmark before/after any change to
 `lib/markbridge/renderers/discourse/markdown_escaper.rb` with the
@@ -299,17 +299,17 @@ refactors when behavior is equivalent.
 
 - **This file**: Quick reference and architecture
 - **README.md**: User-facing quick start
-- **docs/architecture.md**: System architecture and design patterns
-- **docs/parsers/**: BBCode, HTML, and TextFormatter parser guides
-- **docs/renderers/**: Discourse renderer guide
-- **docs/extending.md**: How to add custom tags and handlers
-- **docs/performance.md**: Performance optimization guide
-- **examples/**: Runnable code examples
+- **docs/src/content/docs/concepts/architecture.md**: System architecture and design patterns
+- **docs/src/content/docs/format-guides/**: BBCode, HTML, and TextFormatter parser guides
+- **docs/src/content/docs/concepts/renderers.md**: Discourse renderer guide
+- **docs/src/content/docs/customization/extending.md**: How to add custom tags and handlers
+- **docs/src/content/docs/concepts/performance.md**: Performance optimization guide
+- **spec/docs/**: Checks for runnable documentation examples and AST coverage
 - **spec/**: Executable documentation (tests show expected behavior)
 
 ---
 
-**Maintenance**: This file should be updated when core architecture changes. Details that change frequently (file counts, specific line numbers, step-by-step tutorials) are intentionally excluded. Point to examples/ and spec/ for those.
+**Maintenance**: This file should be updated when core architecture changes. Details that change frequently (file counts, specific line numbers, step-by-step tutorials) are intentionally excluded. Point to the docs site and spec/ for those.
 
 **Last Updated**: 2025-11-26
 **Version**: 0.1.0

Gemfile

@@ -4,7 +4,9 @@ source "https://rubygems.org"
 
 gemspec
 
+gem "benchmark"
 gem "benchmark-ips"
+gem "csv"
 gem "commonmarker", install_if: -> { RUBY_ENGINE == "ruby" }
 gem "lefthook"
 gem "nokogiri"

Gemfile.lock

@@ -14,6 +14,7 @@ GEM
       ice_nine (~> 0.11.0)
       thread_safe (~> 0.3, >= 0.3.1)
     base64 (0.3.0)
+    benchmark (0.5.0)
     benchmark-ips (2.15.1)
     bigdecimal (4.1.3)
     bigdecimal (4.1.3-java)
@@ -31,6 +32,7 @@ GEM
     commonmarker (2.10.0-x86_64-linux)
     commonmarker (2.10.0-x86_64-linux-musl)
     concurrent-ruby (1.3.8)
+    csv (3.3.5)
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.6.2)
@@ -277,8 +279,10 @@ PLATFORMS
   x86_64-linux-musl
 
 DEPENDENCIES
+  benchmark
   benchmark-ips
   commonmarker
+  csv
   lefthook
   markbridge!
   mutant
@@ -300,6 +304,7 @@ CHECKSUMS
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   axiom-types (0.1.1) sha256=c1ff113f3de516fa195b2db7e0a9a95fd1b08475a502ff660d04507a09980383
   base64 (0.3.0) sha256=27337aeabad6ffae05c265c450490628ef3ebd4b67be58257393227588f5a97b
+  benchmark (0.5.0) sha256=465df122341aedcb81a2a24b4d3bd19b6c67c1530713fd533f3ff034e419236c
   benchmark-ips (2.15.1) sha256=07a1a9f3c6105ecaf68c174fc3fbcddd71a0e9ada6236ae03093a0dcfd812d59
   bigdecimal (4.1.3) sha256=61ebe1e5e559bdc3cc6f2c0ee7f427321fc838f59611c294356eb04d6e21cf66
   bigdecimal (4.1.3-java) sha256=9a6a1fa67723a27ab1b3a6d5526322d8c82170af03199da7c915b8d9a1770532
@@ -315,6 +320,7 @@ CHECKSUMS
   commonmarker (2.10.0-x86_64-linux) sha256=945c510c0bfca9022245928e2248468fe3ddad58c939be0c37b20082cc392880
   commonmarker (2.10.0-x86_64-linux-musl) sha256=288cd4fb9f17eed2ffa73551ef241dcf594e0f484b2aee2a0999540333c0618e
   concurrent-ruby (1.3.8) sha256=b2f1be836e968ccc78ccfce277ea79c72a88633f22306782c16ff23fb415d1e1
+  csv (3.3.5) sha256=6e5134ac3383ef728b7f02725d9872934f523cb40b961479f69cf3afa6c8e73f
   descendants_tracker (0.0.4) sha256=e9c41dd4cfbb85829a9301ea7e7c48c2a03b26f09319db230e6479ccdc780897
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
   dry-configurable (1.4.0) sha256=e35d1b5f3c081753ef361f564919db79000f32cfa6f20ee3a3ba5921b41b73ce

README.md

@@ -1,17 +1,16 @@
 # Markbridge
 
-Markbridge converts BBCode into Discourse-flavored Markdown through a clean parse → AST → render pipeline. It is intended for forum migrations and any workflow that needs predictable BBCode handling.
+Markbridge converts BBCode, HTML, MediaWiki wikitext, and s9e/TextFormatter XML into Discourse-flavored Markdown through a clean parse → AST → render pipeline. It's built for forum migrations into Discourse, but works for any job that needs predictable, repeatable conversion.
 
-## How it works
+Full documentation lives at **[markbridge.dev](https://markbridge.dev)**.
 
-1. **Parse BBCode** – `Markbridge::Parsers::BBCode::Parser` tokenizes input and builds an `AST::Document`, reconciling nesting and collecting raw content where needed.
-2. **Transform AST** – The AST captures semantic nodes such as text, formatting elements, lists, URLs, and code blocks that are renderer-agnostic.
-3. **Render to Markdown** – `Markbridge::Renderers::Discourse::Renderer` walks the tree with a tag library to emit Discourse-compatible Markdown, then normalizes spacing for final output.
+## How it works
 
-Refer to the component guides for more detail:
+Every conversion runs the same three steps:
 
-* [BBCode parser](docs/parsers/bbcode.md)
-* [Discourse renderer](docs/renderers/discourse.md)
+1. **Parse** – a format-specific parser turns the input into an `AST::Document`. Unknown tags are counted, not raised — the parser keeps going.
+2. **AST** – a renderer-agnostic tree of text, formatting, lists, links, and so on. The same tree comes out no matter which format went in.
+3. **Render** – `Markbridge::Renderers::Discourse::Renderer` walks the tree and emits Discourse-compatible Markdown.
 
 ## Installation
 
@@ -33,33 +32,29 @@ gem install markbridge
 require "markbridge/bbcode"
 
 bbcode = "[b]Hello[/b] [url=https://example.com]world[/url]!"
-markdown = Markbridge.bbcode_to_markdown(bbcode)
+result = Markbridge.bbcode_to_markdown(bbcode)
 
-puts markdown
+puts result.markdown
 # => "**Hello** [world](https://example.com)!"
 ```
 
-## Configuration
+Swap `bbcode` for `html`, `mediawiki`, or `textformatter` for the other formats, or `require "markbridge/all"` to load everything.
 
-```ruby
-Markbridge.configure do |config|
-  # Strip trailing spaces before newlines to prevent hard line breaks (<br/>).
-  # Defaults to false (Discourse has this disabled by default).
-  config.escape_hard_line_breaks = true
-end
-```
+`*_to_markdown` returns a `Markbridge::Conversion`, not a plain string. The rendered Markdown is on `.markdown` (and `.to_s` delegates to it, so `puts result` works). The same object also carries `.unknown_tags`, `.diagnostics`, and `.errors` — handy when you're migrating a forum and want to know what showed up.
+
+## Customizing output
 
-Configuration applies to all `*_to_markdown` convenience methods (`bbcode_to_markdown`, `html_to_markdown`, etc.).
+Build a renderer once with `Markbridge.discourse_renderer(...)` and pass it via `renderer:` — custom tags, a custom escaper, dropping tags, and more. See [Customizing the renderer](https://markbridge.dev/customization/customizing-renderer/), and [Migrating to Discourse](https://markbridge.dev/migrating/overview/) for the full forum-migration workflow.
 
 ## Learn more
 
-* See `examples/` for runnable scripts such as `examples/basic_usage.rb`.
-* Browse integration and unit coverage under `spec/` to understand supported tags and edge cases.
-* Use `bin/console` during development for interactive exploration.
+* [markbridge.dev](https://markbridge.dev) – guides, format references, and the architecture deep-dive.
+* `spec/` – executable documentation of every supported tag and edge case.
+* `bin/console` – an interactive prompt for poking at things during development.
 
 ## Development
 
-This repository is set up to run inside [silo](https://github.com/gschlager/silo), a lightweight dev-environment tool. The `.silo.yml` file provisions a Fedora container with JRuby and multiple CRuby versions (via [rv](https://rv.dev)), installs dependencies, and starts the playground daemon. If you prefer your own setup, `bin/setup` and `bundle install` are all you need.
+This repository is set up to run inside [silo](https://github.com/gschlager/silo), a development environment tool. The `.silo.yml` file provisions a Fedora container with CRuby, JRuby, TruffleRuby, Node.js, and pnpm. It installs dependencies and starts the playground on port 4567 and the docs site on port 4321. For a Ruby setup outside Silo, use `bin/setup` and `bundle install`. See [docs/README.md](docs/README.md) to run the documentation site.
 
 ## Playground