prepyrus 0.1.2

Parsing and writing to MDX files for Chicago author-date citaitons using BibTeX
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

# Prepyrus

[![Build status](https://github.com/systemphil/prepyrus/workflows/Continuous%20integration/badge.svg)](https://github.com/systemphil/prepyrus/actions)
[![Current crates.io release](https://img.shields.io/crates/v/prepyrus)](https://crates.io/crates/prepyrus)

Prepyrus is a tool for verifying and processing MDX files
that contain citations in Chicago author-date style and certain metadata.

## Usage

Add the crate to your `Cargo.toml` and use it as shown below:

```toml
[dependencies]
prepyrus = "0.1"
```

Main API interface is the `run_prepyrus` function. Example usage:

```rust
use prepyrus::run_prepyrus;
fn main() {
    let args: Vec<String> = std::env::args().collect();
    if args.len() < 4 {
        eprintln!(
            "Expected more args. Usage: prepyrus <bibliography.bib> <target_dir_or_file> <mode>"
        );
        std::process::exit(1);
    }
    if let Err(e) = run_prepyrus(&args[1], &args[2], &args[3]) {
        eprintln!("Error: {}", e);
        std::process::exit(1);
    }
    println!("===Prepyrus completed successfully!");
}
```

The function takes three arguments: `<bibliography.bib> <target_dir_or_file> <mode>`

- a bibliography file (.bib),
- a target directory or .mdx file,
- and a mode (either `verify` or `process`).

`verify` mode only verifies the citations in the MDX files against the bibliography.

**⚠️ NOTE: `process` mode modifies the MDX files.**  
`process` mode _additionally_ processes the MDX files by injecting bibliography and other HTML details into the MDX files.

## Description

The tool is designed to work with MDX files that contain citations in Chicago author-date style. Examples:

```markdown
"...nowhere on heaven or on earth is there anything which does not contain both being and nothing in itself" (Hegel 2010, 61).
```

The tool parses and verifies the citations in the MDX files against a
bibliography file in BibTeX format (using Biblatex).
If the citations are valid, the tool processes the MDX files
by adding a bibliography section at the end of the file.
It also adds author, editor, and contributor from the MDX file metadata if available.
Finally, it also adds a notes heading at the end if footnotes are present in the file.

The tool has two modes: `verify` and `process`.

In `verify` mode, the tool only verifies the citations in the MDX files
and matches them against the bibliography.  
In `process` mode, the tool _additionally_ processes the MDX files by injecting bibliography
and other details into the MDX files.

## Limitations

The tool currently only supports citations in Chicago author-date style.

Only book entries are currently supported (plans to support more types in the future).

Only the following metadata fields are supported:

- author
- editor
- contributor

## Examples

To see a working implementation of prepyrus, please visit the [sPhil repo](https://github.com/systemphil/sphil).

## Acknowledgements

Thanks to Typst's [biblatex](https://github.com/typst/biblatex) package for providing an awesome library for parsing BibTex files, the people behind serde and regex Rust crates and the Rust community!

## License

Apache-2.0