# DocEngine Architecture

## Overview

DocEngine is a markdown rendering library that wraps pulldown-cmark (parsing) and ammonia (sanitization) behind a preset system. Each preset configures which markdown features are enabled and how aggressively the output is sanitized.

## Module Map

```
src/
  lib.rs              Crate root, re-exports, convenience functions
  render.rs           Renderer struct (builder pattern, 4 presets, render/render_with_meta)
  sanitize.rs         SanitizePreset enum (Permissive, Standard, Strict, Minimal)
  text.rs             Text utilities (word_count, reading_time, extract_title, strip_first_heading)
  toc.rs              Table of contents extraction and HTML rendering
  escape.rs           HTML entity escaping for safe string interpolation
  code_spans.rs       Code span/block byte range detection (used by mentions to skip code)
  directives.rs       [directives] Alert/tabs blockquote post-processing
  doc_loader.rs       [doc-loader] Load .md files from disk into in-memory page store
  frontmatter.rs      [frontmatter] Parse +++delimited TOML frontmatter
  media_urls.rs       [media-urls] CDN path rewriting for images, img-to-video conversion
  mentions.rs         [mentions] @username extraction and resolution
  quotes.rs           [quotes] [quote:UUID:HASH] post-processing for forum attribution
```

## Design Decisions

### Presets over configuration

Rather than exposing every pulldown-cmark option, DocEngine provides named presets that bundle markdown features with sanitization levels. This prevents misconfiguration -- you can't accidentally enable raw HTML without appropriate sanitization.

Custom configurations are still possible via the builder pattern (`Renderer::permissive().with_strip_images(true)`).

### Two-phase rendering

Rendering happens in two phases:
1. **pulldown-cmark** parses markdown to HTML events, with optional filtering (strip images, strip raw HTML, neutralize dangerous URL schemes)
2. **ammonia** sanitizes the resulting HTML string

This means even the permissive preset strips `<script>` tags -- ammonia always runs.

Post-processing steps (directives, mentions, quotes, media URLs) are applied after sanitization by consumers, not built into the render pipeline.

### Feature-gated modules

DocEngine has zero required dependencies beyond pulldown-cmark, ammonia, and serde. Consumers that only need rendering don't pull in regex, toml, or uuid. The `full` feature enables everything.

The `regex` vs `regex-lite` split is intentional -- doc-loader's link rewriting needs the full regex engine while simpler patterns in directives, mentions, quotes, and media-urls use the lighter variant.

### DocLoader loads once at startup

`DocLoader::load()` reads all `.md` files from disk, renders them to HTML, and stores them in a `HashMap<String, DocPage>`. This happens once at application boot (MNW calls it during startup). Pages are served from memory with no disk I/O on request.

Link rewriting converts relative `.md` references to the configured URL prefix (e.g., `./faq.md` becomes `/docs/faq`). Links to unpublished docs are stripped to plain text.

### Mention resolution skips code

`extract_mentions` and `resolve_mentions` detect inline code (backticks) and fenced code blocks, skipping any @mentions inside them. This prevents false positives from code examples.

### Directive post-processing

Directives (`[!NOTE]`, `[!TIP]`, `[!TABS]`, etc.) are implemented as HTML post-processing rather than markdown parsing extensions. This keeps the core render pipeline simple and makes directives composable with any preset.

## Consumers

| Consumer | Features | How it's used |
|----------|----------|---------------|
| MNW | doc-loader, directives, frontmatter, media-urls | Site docs loaded at boot, blog posts with frontmatter, user descriptions (standard), item markdown (standard), CDN image rewriting |
| Multithreaded | mentions, quotes | Forum posts (strict), @username linking, quote attribution |
| GoingsOn | core | Task/event descriptions (standard) |
| Balanced Breakfast | core | RSS feed content (sanitize_only) |
| audiofiles | core | Sample descriptions (standard) |

## Key Paths

- `src/render.rs` -- the core rendering logic
- `src/sanitize.rs` -- ammonia preset configurations
- `src/directives.rs` -- alert and code tab processing
- `src/doc_loader.rs` -- document loading and link rewriting
- `src/media_urls.rs` -- CDN path rewriting