## app mdbook-trace

A traceable document preprocessor for mdbook

### 2 releases

 0.1.1 Aug 18, 2022 Aug 18, 2022

#721 in Text processing

18KB
386 lines

# 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

cargo install mdbook-trace


## Usage

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

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


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:

# 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:

[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.
# Heading used for the second column of generated trace tables.
# 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"


~9–16MB
~296K SLoC