# mdbook-trace

A traceable document preprocessor for mdbook.

`mdbook-trace` provides a markdown extension to define a *trace* from the current document to a record in some external document. Each trace generates a footnote in the current page and is added to a *trace table* for the target document.

## Installation
```sh
cargo install mdbook-trace
```

## Usage

Add an entry to `book.toml` for each target document you'll be tracing to:

```toml
[preprocessor.trace.targets.mydoc]
name = "My Document"
```

Then, in your markdown add a new trace:
```markdown
Some traceable text {{#trace mydoc:ID-1.2 }}
```

This will be rendered as

> Some traceable text[^1]
>
> ---
>
> [^1]: My Document ID-1.2

Finally, update your markdown to generate a trace table for the target:
```markdown
# My Document
{{#tracematrix mydoc }}
```

This will be rendered as

> | Record | Traces |
> |--------|--------|
> | ID-1.2 | [1.1]() |


## Configuration
Below is the full set of preprocessor configuration options and their default values:
```toml
[preprocessor.trace]
# Use fully-qualified trace number as in-page footnote number
# e.g. "Some text^1" becomes "Some text^1.2.1"
qualified-footnotes = false
# Add chapter numbers to page titles
# e.g. "My Chapter" becomes "1.1 My Chapter"
chapter-numbers = false
# Insert a horizontal rule between the body of a page and the list of generated footnotes.
footnote-divider = false
# Heading used for the first column of generated trace tables.
record-heading = "Record"
# Heading used for the second column of generated trace tables.
trace-heading = "Traces"
# The trace numbering strategy for a page with subchapters.
# If "allow-duplicates", number traces as normal.
# This will result in traces with the same number as subchapters.
# (e.g. the first trace and first subchapter of chapter 1 will both be numbered 1.1)
# If "offset", offset trace numbers from the last subchapter.
# (e.g. if chapter 1 has 2 subchapters, the first trace will be numbered 1.3)
# If "zero", insert a ".0" qualifier before traces in a page with subchapters.
# (e.g. if chapter 1 has 1 subchapter, the first trace will be 1.0.1).
parent-numbering = "zero"
```