Jektex

Jektex is a Jekyll plugin that renders LaTeX math server-side during site generation using KaTeX, producing static HTML pages with zero client-side JavaScript. It runs as a Ruby gem and works with Jekyll's native Markdown pipeline, automatically converting inline and display formulas written in either Kramdown's dollar-sign notation or LaTeX's escaped-bracket notation.

What is Jektex?

Jektex is a RubyGem-installed plugin for the Jekyll static site generator that processes LaTeX expressions at build time and outputs pre-rendered HTML plus MathML. It takes Markdown source files containing formulas in two supported notations — kramdown's $$...$$ and LaTeX's \(...\) / \[...\] — and uses KaTeX to produce server-side output, so visitors never download a JavaScript math engine. The project is endorsed by KaTeX.org and maintained by yagarea on GitHub, with the source hosted at github.com/yagarea/jektex.

Key Features

• Server-side rendering — LaTeX is converted into HTML and MathML during the Jekyll build; the final site contains no client-side JavaScript for math.
• Two math notations — Supports both kramdown's $$ inline/display convention and the LaTeX-only \( \) / \[ \] syntax, including formulas inside raw HTML blocks that kramdown skips.
• Macro support — Users can define global macros in _config.yml (e.g., \Q for \mathbb{Q}) and even macros with parameters that simulate \newcommand behavior.
• I/O-efficient caching — Rendered expressions are cached in .jekyll-cache by default, with configurable cache_dir; changing any KaTeX option invalidates the cache so stale output is never served.
• Configurable KaTeX options — Pass any documented KaTeX rendering option through the katex_options key, including trust, output, maxExpand, and strict; invalid values fall back to KaTeX's defaults.
• Smart file ignoring — Exclude whole files or directories from processing with wildcard patterns (e.g., *.xml, _drafts/*), or disable per-post via jektex: false in front matter.
• Error reporting — Invalid expressions are marked in the document and their location is printed during rendering, making it easy to find broken formulas.
• Leaves code blocks untouched — LaTeX inside code blocks and inline code stays unrendered, so you can write documentation about LaTeX itself.

Who is it for?

• Jekyll bloggers writing math-heavy posts — Convert formulas in Markdown without making readers execute heavy JavaScript; the output is plain static HTML with KaTeX CSS.
• Academic or technical static-site authors — Use macros to define domain-specific notation (e.g., \Q for rationals) and render complex display equations with \[ \] blocks.
• Site maintainers who care about performance — Server-side rendering means no KaTeX bundle in the browser, and the caching system avoids re-rendering unchanged expressions on rebuilds.

Use cases

• Math tutorials on Jekyll blogs: Write formulas using kramdown's $$ convention and get pre-rendered math that appears instantly on page load.
• Documentation sites with LaTeX: Define project-specific macros once in _config.yml and reuse them across hundreds of pages without repeating definitions.
• RSS feeds mixed with math: Use the ignore option to skip XML files so excerpts containing LaTeX don't break feed readers, while posts still render fully on the site.

How does Jektex work?

Jektex hooks into Jekyll's render pipeline and runs after the kramdown converter. It scans the generated HTML for leftover $$ formulas (and, if enabled, the \(\) / \[\] forms), calls KaTeX to render them server-side, and caches each result on disk. On subsequent builds, cached expressions are reused unless a KaTeX option or macro changes, which triggers a one-time full re-render.

FAQ

Is Jektex free?

Yes. Jektex is released as an open-source RubyGem on rubygems.org under a standard open-source license. You install it with gem install jektex or through Bundler in your Jekyll project's Gemfile.

Does Jektex require JavaScript on the client?

No. All LaTeX is rendered to HTML and MathML at build time. The only extra asset you need is KaTeX's stylesheet, which you can either load from a CDN or host locally; visitors do not run any JavaScript for math display.

What notations does Jektex support?

It supports two notations: kramdown's built-in $$ for both inline and display formulas, and the newer LaTeX-only \( \) for inline and \[ \] for display. A formula standing alone on a line renders in display mode, while one inside text flow renders inline.

What happens if a LaTeX expression is invalid?

The invalid expression is left in the document and its location is printed during rendering, so you can identify the problematic formula in your source. This behavior is controlled by KaTeX's throwOnError, which Jektex manages.