docToolchain / docToolchain/docToolchain

Enable STEM (math) rendering: MathJax for HTML/microsite + native PDF, both asciimath and latexmath

Open
#1,675 0 comments 0 reactions 0 assignees View on GitHub
enhancement next-gen
Dominant language
Groovy
Stars
864
Forks
240
Avg merge
2m
Merged PRs (30d)
2

Description

## Context

AsciiDoc supports **STEM** content (mathematical/scientific formulas via `asciimath` and `latexmath`). docToolchain does **not** enable it yet: there is no `stem` / MathJax / `latexmath` / `asciimath` attribute anywhere in `scripts/AsciiDocBasics.gradle` (the asciidoctorj attribute block, ~lines 171-186, configures highlighting, icons and images, but no STEM).

As a result, `[stem]`, `stem:[...]`, `[asciimath]` and `[latexmath]` blocks/inlines are not rendered.

## Proposal

Enable STEM across the main output formats:

- **HTML / microsite:** set the `stem` attribute and wire up **MathJax** so formulas render in the browser.
- **PDF:** enable STEM so `asciidoctor-pdf` renders math **natively**.
- Support **both notations**: `asciimath` and `latexmath`.

## Goals

- **G-1** `stem:[...]` inline and `[stem]` / `[asciimath]` / `[latexmath]` blocks render correctly in HTML and the microsite.
- **G-2** The same sources render correctly in PDF (native asciidoctor-pdf STEM).
- **G-3** Both `asciimath` and `latexmath` are accepted.

## Scope

- Set the `stem` attribute in the asciidoctorj configuration (`scripts/AsciiDocBasics.gradle`) for HTML and PDF.
- Ship/enable **MathJax** for HTML and the microsite (bundled locally in the theme, no CDN, consistent with the self-contained-assets approach).
- Verify PDF math rendering via asciidoctor-pdf.
- Add a small documentation page / section with a worked example (both notations).

## Acceptance criteria

```gherkin
Feature: STEM rendering

Scenario: Render math in HTML and microsite
Given a document with stem:[sqrt(4) = 2] and a [latexmath] block
When I run generateHTML and generateSite
Then the formulas render as math in the browser via MathJax

Scenario: Render math in PDF
Given the same document
When I run generatePDF
Then the formulas render as math natively in the PDF

Scenario: Both notations work
Given an [asciimath] block and a [latexmath] block
Then both render correctly
```

## Out of scope

- Server-side pre-rendering of math to images (browser-side MathJax is enough for HTML/microsite).

## Affected files (starting points)

- `scripts/AsciiDocBasics.gradle` (asciidoctorj attributes: `stem`)
- `src/site/templates/` + `src/site/assets/` (bundle MathJax for the microsite)
- docs: a short STEM usage page with examples

## Notes

Bundle MathJax locally rather than loading it from a CDN, to keep generated sites self-contained and offline-capable.

Contributor guide

Open the contributing guide

Research direction

Start in scripts/AsciiDocBasics.gradle, especially the asciidoctorj attribute block around lines 171-186, then inspect src/site/templates/ and src/site/assets/ for the microsite theme. Run generateHTML, generateSite, and generatePDF with examples using stem, asciimath, and latexmath. Done means both notations render in HTML and the microsite through locally bundled MathJax and render natively in PDF, with a short documentation example.

Written by the indexing model from the issue text.

Assessment

Tech stack
groovy, latex
Domain
build-system, documentation, web-dev
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.