asciidoc-parser 0.19.0

Parser for AsciiDoc format
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

use crate::{document::TocMode, tests::prelude::*};

track_file!("ref/asciidoc-lang/docs/modules/toc/pages/index.adoc");

non_normative!(
    r#"
= Automatic Table of Contents

A table of contents (TOC) is an index of section titles in an AsciiDoc document.
When the TOC is enabled, the AsciiDoc processor automatically generates the TOC from the document's structure and inserts it into the output document.
The number of levels (i.e., depth) of the TOC is configurable.

"#
);

#[test]
fn activate_the_toc() {
    verifies!(
        r#"
== Activate the TOC

To enable the autogenerated TOC, set the `toc` document attribute.
The `toc` attribute is activated with an attribute entry in the document header.

.Enable TOC with the toc attribute
[source#ex-default]
----
include::example$toc.adoc[tag=header]
:toc: <.>
include::example$toc.adoc[tag=body]
----
<.> Set the `toc` attribute in the header using an attribute entry.
When the value of `toc` is empty, the processor will use the attribute's default value.

"#
    );

    // Setting the `toc` attribute enables the table of contents.
    let doc = Parser::default().parse("= Title\n:toc:\n\n== First\n\nhi");
    assert_eq!(doc.toc_mode(), TocMode::Auto);
    assert_css(&doc, "#toc.toc", 1);

    // With no `toc` attribute, no table of contents is generated.
    let none = Parser::default().parse("= Title\n\n== First\n\nhi");
    assert_eq!(none.toc_mode(), TocMode::Disabled);
    assert_css(&none, ".toc", 0);
}

#[test]
fn default_appearance() {
    verifies!(
        r#"
By default, the TOC is rendered directly below the document header, is titled _Table of Contents_, and contains section 1 and section 2 level titles only.
The result of <<ex-default>> is displayed below.

"#
    );

    let doc = Parser::default()
        .parse("= Title\n:toc:\n\n== Level 1\n\n=== Level 2\n\n==== Level 3\n\ncontent");

    // Rendered directly below the document header (the first body child).
    let vdom = doc.to_virtual_dom();
    assert_eq!(vdom.children[0].id.as_deref(), Some("toc"));

    // Titled _Table of Contents_.
    assert_eq!(doc.toc_title(), "Table of Contents");

    // Contains level 1 and level 2 titles only (the default `toclevels` of 2).
    assert_eq!(doc.toc_levels(), 2);
    assert_css(&doc, "ul.sectlevel1", 1);
    assert_css(&doc, "ul.sectlevel2", 1);
    assert_css(&doc, "ul.sectlevel3", 0);
}

non_normative!(
    r#"
image::toc.png[Default table of contents,role=screenshot]

You can customize the xref:title.adoc[title of the TOC], the xref:levels.adoc[depth of the section levels], and the xref:position.adoc[position of the TOC in the document].
However, not all of the attributes are supported by all converters.
See xref:toc-ref.adoc[] for which attributes are available to each converter.

== Activate the TOC from the CLI

The `toc` attribute can also be specified via the command line (`-a toc`).

.TOC enabled via the CLI
 $ asciidoctor -a toc my-document.adoc
"#
);