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
//! This crate demonstrates an approach to including [Typst](https://typst.app/docs/) in Rust docs. It tries to balance
//! readable source code, attractive rendered output, and ease of use.
//!
//! Docs with Typst can be generated locally and [on docs.rs](https://docs.rs/rustdoc-typst-demo).
//!
//! How it works
//! ============
//!
//! It downloads compilers, renderers, and fonts from CDNs and uses them to
//! render Typst code in the documentation. This will take a few seconds the
//! first time you open the documentation, but resources will be cached in your
//! browser, so subsequent visits will be much faster.
//!
//! Setup
//! =====
//!
//! You'll only need one file: just grab `typst-header.html` from this project
//! and put it into the root of your project.
//!
//! ## Rendering Locally
//!
//! This project can be documented locally with the following commands.
//! Dependencies are documented separately because you probably don't want your
//! dependencies' docs to use Typst. Also, dependencies would not build
//! correctly because of relative paths.
//!
//! ```bash
//! cargo doc
//! RUSTDOCFLAGS="--html-in-header typst-header.html" cargo doc --no-deps --open
//! ```
//!
//! ## Rendering on Docs.rs
//!
//! Include the following snippet in your `Cargo.toml`:
//!
//! ```toml
//! [package.metadata.docs.rs]
//! rustdoc-args = [ "--html-in-header", "typst-header.html" ]
//! ```
//!
//! Typst Compatibility
//! ===================
//!
//! To ensure that your Typst code will always render correctly, you should lock
//! the version of Typst used in your project. Please edit the
//! `typst-header.html` and replace the version numbers with the ones you want
//! to use:
//!
//! ```
//! @myriaddreamin/typst.ts@v0.7.0
//! @myriaddreamin/typst-ts-web-compiler@v0.7.0
//! @myriaddreamin/typst-ts-renderer@v0.7.0
//! ```
//!
//! The `@myriaddreamin/typst.ts@v0.7.0` should compile documents using
//! typst v0.13.1.
//!
//! How to Write Typst
//! ==================
//!
//! Here is some inline markup `{$integral f(x) dif x$}`.
//!
//! And now for a fancy math expression:
//!
//! $ f(x) = integral_(-oo)^oo hat(f)(xi) e^(2 pi i xi x) dif x $
//!
//! For complex markup, you can use the `typ-render`, `typc-render`, or
//! `typm-render` directive. This is a bit more robust:
//!
//! ````md
//! ```typm-render
//! f(x) = integral_(-oo)^oo hat(f)(xi) e^(2 pi i xi x) dif x
//! ```
//! ````
//!
//! ```typm-render
//! f(x) = integral_(-oo)^oo hat(f)(xi) e^(2 pi i xi x) dif x
//! ```
//!
//! ````md
//! ```typ-render
//! #import "@preview/fletcher:0.5.7" as fletcher: diagram, node, edge
//! #context {
//! set curve(stroke: text.fill)
//! diagram(
//! cell-size: 15mm,
//! $
//! G edge(f, ->) edge("d", pi, ->>) & im(f) \
//! G slash ker(f) edge("ur", tilde(f), "hook-->")
//! $,
//! )
//! }
//! ```
//! ````
//!
//! ```typ-render
//! #import "@preview/fletcher:0.5.7" as fletcher: diagram, node, edge
//! #context {
//! set curve(stroke: text.fill)
//! diagram(
//! cell-size: 15mm,
//! $
//! G edge(f, ->) edge("d", pi, ->>) & im(f) \
//! G slash ker(f) edge("ur", tilde(f), "hook-->")
//! $,
//! )
//! }
//! ```
//!
//! ## Todo List
//!
//! A online generator for `typst-header.html`:
//!
//! - Using specific typst version.
//! - Using fonts from "Google Fonts" or other font providers.