jemdoc-rs

A Rust rewrite of jemdoc+MathJax, a light text-based markup language for creating static websites.

jemdoc-rs converts .jemdoc source files into clean, standards-compliant HTML5 pages with built-in support for MathJax 4.

Installation

Using cargo install

Requires Rust 1.87 or later.

cargo install jemdoc-rs

This installs jemdoc-rs to ~/.cargo/bin/, which is typically already on your PATH. You only need to do this once. To update to the latest version, run the same command again.

Pre-built Binaries

Pre-built binaries for Linux, macOS, and Windows are available on the releases page.

Building from Source

git clone https://github.com/haozhu10015/jemdoc-rs.git
cd jemdoc-rs
cargo build --release

The binary will be at target/release/jemdoc-rs. You can copy it to any directory on your PATH.

Quick Start

# Convert a single file (produces index.html from index.jemdoc)
jemdoc-rs index

# With a configuration file
jemdoc-rs -c mysite.conf index.jemdoc

# Multiple files
jemdoc-rs -c mysite.conf *.jemdoc

Usage

jemdoc-rs [OPTIONS] [SOURCEFILE...]

Example

The example/ directory contains a set of .jemdoc files demonstrating the full feature set. To generate and preview them:

cd example

# Generate all HTML pages
make jemdoc

# Preview locally at http://127.0.0.1:8000
make preview

make jemdoc runs jemdoc-rs -c mysite.conf *.jemdoc and writes the HTML output in place. make preview starts a local HTTP server using simple-http-server (installed automatically via Cargo if not already present). Run make help to see all available targets.

Markup Reference

Titles and Headings

= Page Title
== Section
=== Subsection

Text Formatting

Equations (MathJax)

MathJax 4 is always included. Inline math uses $...$ and display math uses \(...\):

Inline equation: $E = mc^2$.

Display equation:
\(
\nabla \times \mathbf{E} = -\frac{\partial\mathbf{B}}{\partial t}
\)

Numbered equations work with LaTeX equation, align, and \label/\eqref commands.

Links

[http://example.com]                  # URL as link text, opens in new tab
[http://example.com Example Site]     # Custom link text, opens in new tab
[/localpage.html Local Page]          # Leading / opens in the same tab
[user@example.com]                    # Mailto link

Images

[img{width}{height}{alt text} path/to/image.png Caption]

Lists

- Unordered item 1
- Unordered item 2

. Ordered item 1
. Ordered item 2

: {Term} Definition
: {Another term} Another definition

Nested lists use repeated markers (--, ...).

Code Blocks

~~~
{Title}{language}
def hello():
    print("world")
~~~

Supported languages for syntax highlighting: python/py, c, c++/cpp, ruby/rb, sh, matlab, commented, jemdoc, pyint.

Use {}{raw} to output content verbatim (no highlighting or wrapping).

Info Blocks

~~~
{Optional Title}
Block content here.
~~~

Tables

~~~
{}{table}{optional-id}
Cell 1 | Cell 2 | Cell 3
Row 2  | Cell 5 | Cell 6
~~~

Use || for row breaks within a cell.

Image Blocks

~~~
{}{img_left}{photo.jpg}{alt text}{width}{height}{link}
Description text goes here.
~~~

Raw HTML

Embed raw HTML with double braces: {{<span style="color:red">red</span>}}.

Comments

Lines starting with # are comments and are not included in the output.

# This is a comment

Header Directives

Directives are placed at the top of a .jemdoc file as special comments:

# jemdoc: menu{MENU}{thispage.html}
# jemdoc: addcss{custom.css}
# jemdoc: title{Custom Window Title}

Menu Files

A MENU file defines the navigation sidebar:

Menu Category
    Page One        [page1.html]
    Page Two        [page2.html]

Another Category
    External Link   [\http://example.com]

• Indented lines with [link] are menu items.
• Non-indented lines are category headers.
• Prefix a link with \ to open it in a new tab.

Configuration

jemdoc-rs uses a default HTML template that can be customized. Run jemdoc-rs --show-config to see all configurable sections. Override any section in a .conf file:

# mysite.conf — override the body start to add a favicon
[bodystart]
</head>
<link rel="icon" href="img/icon.png" type="image/x-icon" />
<body>

Use -c mysite.conf to apply the overrides. Multiple -c flags can be used; later files take precedence.