# Configuration and themes

> Presets, themes, the renderer protocols you can replace, and diagnostics counters.

## Presets

`MarkdownRendererConfiguration.document` is for reading documents. `.compactChat` uses tighter spacing for chat transcripts. Both come with selection across the whole document, the safe default policies, code highlighting, math, diagrams, and link icons turned on.

```swift
var configuration = MarkdownRendererConfiguration.document
configuration.theme.mermaidAffordances.maximumViewportHeight = 360
configuration.copyProvider = MarkdownCopyProvider(markdownSource: "# My document")
```

Preparation caches reuse unchanged content. Settings that affect the whole document, such as its font, invalidate the corresponding prepared content.

## Replaceable renderers

Code highlighting, math, diagrams, images, and link icons each have a default you can replace with your own:

| Protocol | Default | Replace it if |
|---|---|---|
| `MarkdownCodeHighlighter` | `DefaultMarkdownCodeHighlighter`, covering common languages | you have your own highlighter, or want plain text everywhere |
| `MarkdownMathRenderer` | `DefaultMarkdownMathRenderer` | you want source text (`PlainMarkdownMathRenderer`) or your own typesetter |
| `MarkdownMermaidRenderer` | `DefaultMarkdownMermaidRenderer`, on macOS, iOS, iPadOS, and visionOS | you draw diagrams yourself. Return `nil` to show the source instead. |
| `MarkdownImageResolver` | `DefaultMarkdownImageResolver`, backed by bounded remote loading | you supply image data yourself, or need document-relative files |
| `MarkdownLinkMetadataResolver` | the built-in site-icon resolver | you want to turn it off (set it to `nil`) or supply your own metadata for citations |

If you write your own renderer, also adopt its cache-identity protocol, such as `MarkdownMathRendererCacheIdentifying`, so its results are cached.

## Themes

`MarkdownTheme` holds typography, spacing, colors, the syntax-highlighting palette, and diagram settings. The package ships `.document` and `.compactChat` themes. `MarkdownDocumentStyle` and the per-block styles, such as `MarkdownCodeBlockStyle`, `MarkdownTableStyle`, and `MarkdownMathBlockStyle`, let you restyle one kind of block without touching the rest.

## Diagnostics

Attach a `MarkdownDiagnosticsRecorder` to a configuration to count what the renderer did: parses, relayouts, highlighting, diagram and math renders, fallbacks, and cache hits and misses. It's useful in tests, for example to check that no equation fell back to source text.

```swift
let recorder = MarkdownDiagnosticsRecorder()
var configuration = MarkdownRendererConfiguration.document
configuration.diagnosticsRecorder = recorder
_ = configuration.prepare(snapshot: stream.snapshot())
let counters = recorder.snapshot()
precondition(counters.mathFallbackCount == 0)
```

## Prepared snapshots

`prepare(snapshot:)` returns a `MarkdownPreparedSnapshot`, which is what the views, the print exporter, and selection documents take. It's `Sendable`, so you can prepare on a background task and publish the result on the main actor.

[Document interactions](https://github.com/mikhutchinson/siriusmarkdown-commercial/blob/main/Docs/document-interactions.md)