mini-docs 0.4.2

A minimal, secure build-time Markdown to HTML generator for the mini-* family.
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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127

use std::fs;
use std::thread::sleep;
use std::time::Duration;

use mini_docs::Builder;

/// mtime resolution varies by filesystem; sleeping past it keeps the "did this file
/// change" comparison from racing a same-tick write.
const MTIME_SETTLE: Duration = Duration::from_millis(50);

/// A base template's change must fan out to every page that (in principle) extends
/// it — mini-docs doesn't parse the `{% extends %}` graph, so it conservatively
/// rebuilds every page whenever any template file's mtime changes.
#[test]
fn template_change_rebuilds_all_dependent_pages_on_next_tick() {
    let input = tempfile::tempdir().expect("create input tempdir");
    let templates = tempfile::tempdir().expect("create templates tempdir");
    let output = tempfile::tempdir().expect("create output tempdir");

    fs::write(input.path().join("guide.md"), "# Guide\n\nBody text.\n").expect("write guide.md");
    fs::write(
        templates.path().join("base.html"),
        "<body>v1: {% block content %}{% endblock %}</body>",
    )
    .expect("write base.html");
    fs::write(
        templates.path().join("page.html"),
        "{% extends \"base.html\" %}{% block content %}{{ page.content | safe }}{% endblock %}",
    )
    .expect("write page.html");

    let builder = Builder::new(input.path())
        .templates(templates.path())
        .output(output.path())
        .default_template("page.html");

    let mut watcher = builder.watch().expect("initial watch build should succeed");

    let before = fs::read_to_string(output.path().join("guide.html")).expect("read initial output");
    assert!(
        before.contains("v1:"),
        "initial build should use the v1 base template: {before}"
    );

    sleep(MTIME_SETTLE);
    fs::write(
        templates.path().join("base.html"),
        "<body>v2: {% block content %}{% endblock %}</body>",
    )
    .expect("rewrite base.html");

    let changed = watcher.tick().expect("tick should succeed");
    assert_eq!(
        changed.len(),
        1,
        "the one .md page should be reported rebuilt: {changed:?}"
    );

    let after = fs::read_to_string(output.path().join("guide.html")).expect("read rebuilt output");
    assert!(
        after.contains("v2:"),
        "base template change should fan out to the page: {after}"
    );
    assert!(
        !after.contains("v1:"),
        "stale v1 content should not remain: {after}"
    );
}

/// Only the `.md` file that actually changed is rebuilt when no template changed.
#[test]
fn unchanged_md_file_is_not_rebuilt_alongside_a_changed_one() {
    let input = tempfile::tempdir().expect("create input tempdir");
    let templates = tempfile::tempdir().expect("create templates tempdir");
    let output = tempfile::tempdir().expect("create output tempdir");

    fs::write(input.path().join("a.md"), "# A\n").expect("write a.md");
    fs::write(input.path().join("b.md"), "# B\n").expect("write b.md");
    fs::write(
        templates.path().join("page.html"),
        "{{ page.content | safe }}",
    )
    .expect("write page.html");

    let builder = Builder::new(input.path())
        .templates(templates.path())
        .output(output.path())
        .default_template("page.html");

    let mut watcher = builder.watch().expect("initial watch build should succeed");

    sleep(MTIME_SETTLE);
    fs::write(input.path().join("a.md"), "# A changed\n").expect("rewrite a.md");

    let changed = watcher.tick().expect("tick should succeed");

    assert_eq!(changed.len(), 1, "only a.md should be rebuilt: {changed:?}");
    assert_eq!(changed[0].file_name().unwrap(), "a.md");
}

/// A tick with no filesystem changes at all rebuilds nothing.
#[test]
fn tick_with_no_changes_rebuilds_nothing() {
    let input = tempfile::tempdir().expect("create input tempdir");
    let templates = tempfile::tempdir().expect("create templates tempdir");
    let output = tempfile::tempdir().expect("create output tempdir");

    fs::write(input.path().join("a.md"), "# A\n").expect("write a.md");
    fs::write(
        templates.path().join("page.html"),
        "{{ page.content | safe }}",
    )
    .expect("write page.html");

    let builder = Builder::new(input.path())
        .templates(templates.path())
        .output(output.path())
        .default_template("page.html");

    let mut watcher = builder.watch().expect("initial watch build should succeed");

    let changed = watcher.tick().expect("tick should succeed");
    assert!(
        changed.is_empty(),
        "nothing changed, so nothing should rebuild: {changed:?}"
    );
}