# DocEngine

Configurable markdown-to-HTML rendering library with sanitization presets. Built on pulldown-cmark (GFM) and ammonia.

Used by MNW (site docs, blog posts, user-generated content), Multithreaded (forum posts), and the desktop apps (descriptions, notes).

## Presets

Four rendering presets, each with different security/feature tradeoffs:

| Preset | Use case | Tables | Images | Raw HTML | Dangerous scheme filter | Sanitization |
|--------|----------|:------:|:------:|:--------:|:-----------------------:|--------------|
| **Permissive** | Docs, blog posts (trusted) | Y | Y | Y | N | Default ammonia |
| **Standard** | App text fields (descriptions) | Y | N | Y | N | Default ammonia |
| **Strict** | User-generated content (forums) | N | N | N | Y | nofollow on links |
| **Sanitize-only** | External HTML (RSS feeds) | -- | -- | -- | -- | Default ammonia, no markdown parsing |

```rust
use docengine::{render_permissive, render_standard, render_strict, sanitize_html};

// Convenience functions
let html = render_permissive("# Hello\n\n**Bold** text");
let html = render_standard("A description with [link](https://example.com)");
let html = render_strict("User post with @mentions and `code`");
let html = sanitize_html("<p>Pre-rendered</p><script>stripped</script>");

// Builder pattern for custom configurations
use docengine::{Renderer, SanitizePreset};

let html = Renderer::permissive()
    .with_strip_images(true)       // override: strip images even in permissive
    .with_footnotes(false)
    .render("# Custom config");

// Render with metadata (word count, reading time)
let result = Renderer::standard().render_with_meta("Some article text...");
println!("{} words, ~{} min read", result.word_count, result.reading_time_minutes);
```

## Feature Flags

All optional features are off by default. Enable what you need:

| Flag | Dependencies | Provides |
|------|-------------|----------|
| `doc-loader` | regex | `DocLoader` -- load a directory of `.md` files into an in-memory page store |
| `directives` | regex-lite | `post_process_directives` -- `[!NOTE]`/`[!TIP]`/`[!TABS]` blockquote alerts and code tabs |
| `frontmatter` | toml | `parse_frontmatter` -- extract TOML frontmatter delimited by `+++` |
| `mentions` | regex-lite | `extract_mentions`, `resolve_mentions` -- `@username` parsing and linking |
| `quotes` | regex-lite, uuid | `post_process_quotes` -- replace `[quote:POST_ID:HASH]` markers with author attribution |
| `media-urls` | regex-lite | `rewrite_media_paths`, `img_to_video` -- CDN path rewriting and video tag conversion |
| `assumptions` | toml, regex-lite | `Assumptions` -- load a TOML source-of-truth file, compute derived values, validate, substitute `{{ dotted.path \| filter(args) }}` markers in markdown with an extensible filter pipeline (built-ins: `int`, `ceil`, `floor`, `round`, `money`, `percent`, `upper`, `lower`) |
| `full` | all of the above | Enable everything |

```toml
# In Cargo.toml
docengine = { path = "../shared/docengine" }                    # Core only (from MNW/server/)
docengine = { path = "../../MNW/shared/docengine" }              # From Apps/
```

## Core API

### Types

- **`Renderer`** -- configurable markdown renderer with builder pattern
- **`RenderResult`** -- rendered HTML plus `word_count` and `reading_time_minutes`
- **`SanitizePreset`** -- `Permissive`, `Standard`, `Strict`, `Minimal`
- **`TocEntry`** -- heading level, text, and anchor for table of contents

### Functions

| Function | Description |
|----------|-------------|
| `render_permissive(md)` | Render with full GFM features |
| `render_standard(md)` | Render without images |
| `render_strict(md)` | Render with all restrictions (UGC-safe) |
| `sanitize_html(html)` | Clean pre-rendered HTML without markdown parsing |
| `word_count(text)` | Count words in raw text |
| `reading_time_minutes(wc)` | Estimate reading time (200 wpm) |
| `extract_title(md)` | Pull the first `# Heading` from markdown |
| `strip_first_heading(md)` | Remove the first `# Heading` (for template-rendered titles) |
| `extract_toc(md)` | Build a `Vec<TocEntry>` from all headings |
| `render_toc_html(entries)` | Render TOC entries as a `<nav class="toc">` HTML list |

### Feature-gated

| Function / Type | Feature | Description |
|-----------------|---------|-------------|
| `DocLoader::load(path, config)` | `doc-loader` | Load `.md` files from disk, render to HTML, build searchable index |
| `DocPage`, `DocIndexEntry` | `doc-loader` | Page and index entry types |
| `post_process_directives(html)` | `directives` | Convert `[!NOTE]`/`[!TIP]`/etc. blockquotes to alert divs, `[!TABS]` to tabbed code blocks |
| `parse_frontmatter(input)` | `frontmatter` | Parse `+++`-delimited TOML frontmatter |
| `Frontmatter` | `frontmatter` | Struct with `title`, `date`, `tags`, `section`, `draft`, `extra` |
| `extract_mentions(md)` | `mentions` | Find unique `@username` mentions (skips code blocks) |
| `resolve_mentions(md, valid, template)` | `mentions` | Replace `@user` with `[@user](/path/to/user)` for known usernames |
| `post_process_quotes(html, authors)` | `quotes` | Replace `[quote:UUID:HASH]` with clickable attribution |
| `rewrite_media_paths(md, base, user)` | `media-urls` | Rewrite relative image paths to absolute CDN URLs |
| `img_to_video(html)` | `media-urls` | Convert `<img>` tags pointing to video files into `<video>` elements |
| `Assumptions::load(path)` / `::parse(text)` | `assumptions` | Load and parse a TOML assumptions file |
| `Assumptions::validate()` | `assumptions` | Check internal consistency (sums, bounds, founding ≤ standard) |
| `Assumptions::substitute(md)` | `assumptions` | Replace `{{ dotted.path \| filter(args) }}` placeholders with raw or derived values, optionally piped through filters |
| `Assumptions::with_filter(name, impl Filter)` | `assumptions` | Register a custom filter for use in the substitution pipeline |

## Consumers

| Project | Features used | Preset |
|---------|--------------|--------|
| MNW | `doc-loader`, `directives`, `frontmatter`, `media-urls`, `assumptions` | Permissive (docs/blog), Standard (descriptions) |
| Multithreaded | `mentions`, `quotes` | Strict (forum posts) |
| GoingsOn | core only | Standard (notes, descriptions) |
| Balanced Breakfast | core only | Sanitize-only (RSS feed content) |

## Security

All presets sanitize output through ammonia. The strict preset additionally:
- Strips all raw HTML and images at the parser level (before ammonia)
- Replaces `javascript:`, `data:`, `vbscript:` URLs with `#`
- Adds `rel="noopener noreferrer nofollow"` to all links

Zero unsafe code.

## License

PolyForm Noncommercial 1.0.0