https://github.com/termoshtt/katexit

Insert KaTeX autorender script into rustdoc
https://github.com/termoshtt/katexit

katex rust rustdoc

Last synced: 3 days ago
JSON representation

Insert KaTeX autorender script into rustdoc

• Host: GitHub
• URL: https://github.com/termoshtt/katexit
• Owner: termoshtt
• License: apache-2.0
• Created: 2021-06-07T16:57:46.000Z (over 3 years ago)
• Default Branch: main
• Last Pushed: 2024-02-27T11:07:39.000Z (9 months ago)
• Last Synced: 2024-10-28T22:27:52.177Z (16 days ago)
• Topics: katex, rust, rustdoc
• Language: Rust
• Homepage:
• Size: 37.1 KB
• Stars: 19
• Watchers: 2
• Forks: 2
• Open Issues: 1
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
[![Crate](https://img.shields.io/crates/v/katexit.svg)](https://crates.io/crates/katexit)

[![docs.rs](https://docs.rs/katexit/badge.svg)](https://docs.rs/katexit)

Insert KaTeX autorender script into rustdoc

Usage

-----

```rust

#[cfg_attr(doc, katexit::katexit)]

/// We can write $\LaTeX$ expressions

///

/// Display style

/// -------------

///

/// $$

/// c = \\pm\\sqrt{a^2 + b^2}

/// $$

pub fn my_func() {}

```

See rendered result on [docs.rs](https://docs.rs/katexit-example/0.1.0/katexit_example/fn.my_func.html).

[katex-functions]: https://katex.org/docs/supported.html

[katex-symbols]: https://katex.org/docs/support_table.html

On nightly rustc, you can use `#![katexit::katexit]` for module level document:

```rust

#![cfg_attr(doc, feature(prelude_import, custom_inner_attributes))]

#![cfg_attr(doc, katexit::katexit)]

//! Module level document example with $\KaTeX$!

```

Be sure that `cargo test` will runs `rustdoc` for executing doc-test,

and thus requires nightly compiler.

See [katexit-example-nightly](./katexit-example-nightly) for detail.

How it works

-------------

`#[katexit]` proc-macro inserts [KaTeX autorender script][autorender] as `#[doc = "{script}"]`.

Since the markdown to HTML translator of rustdoc do not touch HTML partitions embedded in markdown,

they will be passed as it is to the browser.

The autorender script starts rendering the math expression enclosed by `$` written in the document section

when you open the page generated by rustdoc, i.e. this does not work offline.

[autorender]: https://katex.org/docs/autorender.html

Links

------

- [rustdoc-katex-demo](https://github.com/paulkernfeld/rustdoc-katex-demo) and similar demo projects

  - They uses [`--html-in-header` option in rustdoc](https://doc.rust-lang.org/rustdoc/command-line-arguments.html#--html-in-header-include-more-html-in-head) to inserts [KaTeX auto-render script](autorender). But it requires some complicated setting in Cargo.toml.

- [aquamarine](https://github.com/mersinvald/aquamarine)

  - The idea using proc-macro for cargo-doc is based on this crate.

- [katex-rs](https://github.com/xu-cheng/katex-rs)

  - This is "Rust bindings to KaTeX". This crate aims to run KaTeX using [QuickJS](https://bellard.org/quickjs/) without external dependencies.