docToolchain / docToolchain/docToolchain
Enable STEM (math) rendering: MathJax for HTML/microsite + native PDF, both asciimath and latexmath
- 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
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