rustdoc_typst_demo/
lib.rs

1//! This crate demonstrates an approach to including [Typst](https://typst.app/docs/) in Rust docs. It tries to balance
2//! readable source code, attractive rendered output, and ease of use.
3//!
4//! Docs with Typst can be generated locally and [on docs.rs](https://docs.rs/rustdoc-typst-demo).
5//!
6//! How it works
7//! ============
8//!
9//! It downloads compilers, renderers, and fonts from CDNs and uses them to
10//! render Typst code in the documentation. This will take a few seconds the
11//! first time you open the documentation, but resources will be cached in your
12//! browser, so subsequent visits will be much faster.
13//!
14//! Setup
15//! =====
16//!
17//! You'll only need one file: just grab `typst-header.html` from this project
18//! and put it into the root of your project.
19//!
20//! ## Rendering Locally
21//!
22//! This project can be documented locally with the following commands.
23//! Dependencies are documented separately because you probably don't want your
24//! dependencies' docs to use Typst. Also, dependencies would not build
25//! correctly because of relative paths.
26//!
27//! ```bash
28//! cargo doc
29//! RUSTDOCFLAGS="--html-in-header typst-header.html" cargo doc --no-deps --open
30//! ```
31//!
32//! ## Rendering on Docs.rs
33//!
34//! Include the following snippet in your `Cargo.toml`:
35//!
36//! ```toml
37//! [package.metadata.docs.rs]
38//! rustdoc-args = [ "--html-in-header", "typst-header.html" ]
39//! ```
40//!
41//! Typst Compatibility
42//! ===================
43//!
44//! To ensure that your Typst code will always render correctly, you should lock
45//! the version of Typst used in your project. Please edit the
46//! `typst-header.html` and replace the version numbers with the ones you want
47//! to use:
48//!
49//! ```
50//! @myriaddreamin/typst.ts@v0.6.1-rc1
51//! @myriaddreamin/typst-ts-web-compiler@v0.6.1-rc1
52//! @myriaddreamin/typst-ts-renderer@v0.6.1-rc1
53//! ```
54//!
55//! The `@myriaddreamin/typst.ts@v0.6.1-rc1` should compile documents using
56//! typst v0.13.1.
57//!
58//! How to Write Typst
59//! ==================
60//!
61//! Here is some inline markup `{$integral f(x) dif x$}`.
62//!
63//! And now for a fancy math expression:
64//!
65//! $ f(x) = integral_(-oo)^oo hat(f)(xi) e^(2 pi i xi x) dif x $
66//!
67//! For complex markup, you can use the `typ-render`, `typc-render`, or
68//! `typm-render` directive. This is a bit more robust:
69//!
70//! ````md
71//! ```typm-render
72//! f(x) = integral_(-oo)^oo hat(f)(xi) e^(2 pi i xi x) dif x
73//! ```
74//! ````
75//!
76//! ```typm-render
77//! f(x) = integral_(-oo)^oo hat(f)(xi) e^(2 pi i xi x) dif x
78//! ```
79//!
80//! ````md
81//! ```typ-render
82//! #import "@preview/fletcher:0.5.7" as fletcher: diagram, node, edge
83//! #context {
84//!   set curve(stroke: text.fill)
85//!   diagram(
86//!     cell-size: 15mm,
87//!     $
88//!       G edge(f, ->) edge("d", pi, ->>) & im(f) \
89//!       G slash ker(f) edge("ur", tilde(f), "hook-->")
90//!     $,
91//!   )
92//! }
93//! ```
94//! ````
95//!
96//! ```typ-render
97//! #import "@preview/fletcher:0.5.7" as fletcher: diagram, node, edge
98//! #context {
99//!   set curve(stroke: text.fill)
100//!   diagram(
101//!     cell-size: 15mm,
102//!     $
103//!       G edge(f, ->) edge("d", pi, ->>) & im(f) \
104//!       G slash ker(f) edge("ur", tilde(f), "hook-->")
105//!     $,
106//!   )
107//! }
108//! ```
109//!
110//! ## Todo List
111//!
112//! A online generator for `typst-header.html`:
113//!
114//! - Using specific typst version.
115//! - Using fonts from "Google Fonts" or other font providers.
rustdoc_typst_demo/lib.rs

rustdoc_typst_demo/
lib.rs
