🛠️ MarS Doc

MarS Doc is an expert production workflow to transform Markdown into interactive, professional and versatile Reveal.js presentations. MarS Doc (Markdown to Slide with Pandoc) generates two distinct versions depending on your distribution needs: a standalone (Offline) version and a lightweight (Online) version.

✨ A live demo is available here

🚀 You can find the full source code for MarS-doc here

---

📋 Prerequisites

To use this workflow, you need the following installed on your machine:

• Pandoc (>= 3.8.0.2 recommended): The universal conversion engine.
• GNU Make: To automate the build process and resource management.
• Node.js / npm: Required to install browser-sync.

🐧 Linux / macOS

make is usually pre-installed. Install Pandoc via your package manager:

# Debian/Ubuntu
sudo apt install pandoc make

# macOS (Homebrew)
brew install pandoc make

---

🪟 Windows — Full Installation

On Windows, the required tools are installed in three steps.

Step 1 — MSYS2 (provides make and a Bash shell)

MSYS2 is the simplest way to get make and a Bash environment on Windows.

1. Download and install MSYS2 from https://www.msys2.org/.
2. Open the MSYS2 UCRT64 terminal and install make:

# Update the package database
pacman -Syu

# Install make
pacman -S make

# Optional: full development toolchain (gcc, git, etc.)
pacman -S base-devel

Step 2 — Pandoc

Download and install Pandoc from https://github.com/jgm/pandoc/releases/latest (Windows .msi installer).

By default, Pandoc installs to C:\Program Files\Pandoc\.

Step 3 — Node.js / npm (for browser-sync)

Download and install Node.js (LTS) from https://nodejs.org. npm is included automatically.

By default, Node.js installs to C:\Program Files\nodejs\.

---

⚙️ PATH Configuration on Windows

MSYS2 manages its own PATH, independent from Windows. For pandoc, node, npm and browser-sync to be accessible from the MSYS2 terminal, they must be declared in the MSYS2 ~/.bash_profile file.

Open (or create) the file C:\msys64\home\<YourName>\.bash_profile and add the following blocks:

# Node.js
if [ -d "/c/Program Files/nodejs" ] ; then
   PATH=${PATH}:"/c/Program Files/nodejs"
fi

# npm global packages (browser-sync installs here)
if [ -d "/c/Users/${USER}/AppData/Roaming/npm" ] ; then
   PATH=${PATH}:"/c/Users/${USER}/AppData/Roaming/npm"
fi

# Pandoc
if [ -d "/c/Program Files/Pandoc" ] ; then
   PATH=${PATH}:"/c/Program Files/Pandoc"
fi

# MSYS2 MinGW64 / UCRT64
if [ -d "/mingw64/bin/" ] ; then
   PATH="${PATH}:/mingw64/bin/"
fi
if [ -d "/ucrt64/bin/" ] ; then
   PATH="${PATH}:/ucrt64/bin/"
fi

💡 A reference .bash_profile file is provided at the root of the project.

Reload the configuration without restarting:

source ~/.bash_profile

Verify everything is accessible:

make --version
pandoc --version
node --version
npm --version

Using PowerShell

If you prefer to use PowerShell instead of the MSYS2 terminal, manually add the following paths to your System Environment Variables (Control Panel → System → Environment Variables → Path):

C:\msys64\usr\bin          ← make
C:\Program Files\Pandoc    ← pandoc
C:\Program Files\nodejs    ← node, npm
C:\Users\<YourName>\AppData\Roaming\npm  ← browser-sync

---

💡 Recommendation (Comfort)

It is strongly recommended to install browser-sync for automatic live reload while editing your slides. Once Node.js is installed and the PATH is configured:

npm install -g browser-sync

---

🌟 Key Concepts

The project is built on the separation of content (slides.md) and rendering logic. It offers two generation modes:

1. Offline version (build/offline/index.html):
   • Total independence: Ideal for conferences with no guaranteed Wi-Fi.
   • Local dependencies: Uses the build/offline/runtime/ folder (Reveal.js, KaTeX, ECharts, etc.).
2. Online version (build/online/index.html):
   • Portability: The HTML file is self-contained and does not require a local folder for scripts.
   • Cloud access: Uses CDNs (cdnjs, jsDelivr) to load libraries. Requires an internet connection.

---

📂 Project Architecture

.
├── slides.md                # Your Markdown source (Content)
├── Makefile                 # Build automation (Online & Offline)
├── md2slides/               # System core (Default sources)
│   ├── assets/              # Standard images, icons and logos
│   ├── css/                 # Styles (slides.css, custom.css)
│   ├── lua/                 # Pandoc filters (Mermaid, Alpine, Rough-Notation, ECharts, CSV, timing)
│   ├── runtime/             # JS/CSS libraries for Offline mode
│   └── templates/           # Pandoc templates (Online & Offline)
├── assets/                  # Local copy (Auto-generated if absent)
├── css/                     # Local copy (Auto-generated if absent)
└── templates/               # Local copy (Auto-generated if absent)

Note: If the assets/, css/ or templates/ folders are missing from the root, the Makefile automatically initialises them by copying the content from the md2slides/ folder.

---

🚀 Production Workflow

1. Writing

Edit your slides.md file.

2. Build

Simply run the following command from the root:

make           # Generates both versions (online + offline)
make online    # CDN version only
make offline   # Standalone version only
make clean     # Deletes the build/ folder
make purge     # Deletes build/, assets/, css/ and templates/

💡 Lightweight offline build: feature detection is now fully automatic. Every make / make online / make offline run regenerates options.txt on the fly (whenever slides.md has changed) by scanning it for the features actually used, writing one use-<module>=true|false line per library. make offline then copies only the runtime modules your presentation really needs into build/offline/runtime/js/, keeping the standalone archive as small as possible — no manual step required. Delete options.txt (or run make purge) if you ever need to force a clean re-detection.

3. Development Mode (Live Watch)

To work in real time with automatic browser preview:

make watch

This command runs the watch.sh script which monitors changes to slides.md, templates and CSS, then triggers browser-sync.

---

🎯 Features in Detail

🗂️ 2D Navigation and Keyboard Shortcuts

Reveal.js organises slides on a 2D grid (horizontal sections, vertical sub-slides).

Key	Mode	Description
→ / ←	Navigation	Next / previous section
↓ / ↑	Navigation	Next / previous sub-slide
S	Speaker	Speaker view with notes and timer
O	Overview	2D grid of all slides
F	Fullscreen	Full screen
B	Blackout	Black screen (refocuses audience)
V	Pause	Pause without leaving the slide
G	Jump	Jump directly to a slide number
M	Menu	Table of contents
C	Draw	Annotate directly on the current slide (canvas)
B	Chalkboard	Open interactive chalkboard
Del	Erase	Clear annotations
Esc	Back	Exit current mode

---

👆 Invisible Touch Navigation Zones

For touchscreens and tablets, every slide includes four invisible clickable zones so the audience (or the presenter) can navigate without any visible button:

Zone	Action
Left edge	Previous slide
Right edge	Next slide
Top-left corner	Jump to the first slide
Top-right corner	Jump to the last slide

These zones are always active and require no configuration.

---

📱 WebSocket Remote Control (Smartphone)

A remote control system with no app to install:

1. Click the ⚙️ icon at the bottom left to open the toolbar.
2. Click 📱 to display the QR Code.
3. Scan it with your smartphone.
4. Your phone becomes a remote control (Next, Prev, Start, End) via WebSocket (ntfy.sh).

---

⏱️ Presentation Timer

A built-in stopwatch with pacing indicator:

<!-- timing: 90 -->

Place this HTML comment anywhere within a section to set the allocated time in seconds. The timer displays elapsed time and a colour indicator:

• 🟢 Green: On time or ahead.
• 🟠 Orange: Slightly behind.
• 🔴 Red: More than 10 seconds behind.

A global default time per slide can be set via the slide-timing: YAML variable in the Markdown file header.

---

📝 Extended Markdown Syntax

Multi-column layout

:::::::::::::: {.cols-full}
:::: {.bg-blue .rounded-left width=40%}
**Column 1** — 40% width
::::
:::: {.bg-black .rounded-right}
**Column 2** — remaining space
::::
::::::::::::::

Available background colour classes for .bg-*: black, white, blue, orange, yellow, green, red.

Rounded border classes: .rounded, .rounded-left, .rounded-right, .rounded-top, .rounded-bottom, .rounded-tl, .rounded-tr, .rounded-bl, .rounded-br.

Multi-row layout

:::::::::::::: {.rows-full}
:::: {.bg-green .rounded-tl height=30%}
Row 1 (30% height)
::::
:::: {.bg-black .rounded-bl}
Row 2 (remaining space)
::::
::::::::::::::

Width / height control

The width= and height= attributes (in %) can be applied to any container or column:

:::: {.bg-blue width=35% height=50%}
Content
::::

---

🎨 Interactive Components (Alpine.js)

Semantic alerts

::: {.warning}
⚠️ **Warning**: Critical text.
:::

::: {.info}
ℹ️ **Info**: Informational text.
:::

Toggle (collapsible content)

::: {.toggle label="▶ Show source code"}
Content hidden by default.
:::

Stepper (guided workflow)

::: stepper
 * **Step 1**: Write your content in Markdown.
 * **Step 2**: Compile with `make`.
 * **Step 3**: Present in any modern browser.
:::

Each step highlights on click, previous ones dim automatically.

---

✨ Fragments and Animations

Fine-grained control over element appearance using Reveal.js fragment classes:

*   [`.fade-in` — soft appearance (default)]{.fragment .fade-in}
*   [`.highlight-red` — red highlight]{.fragment .highlight-red}
*   [`.fade-out` — gradual disappearance]{.fragment .fade-out}

Advanced sequencing with data-fragment-index to synchronise multiple elements:

[Object A]{.fragment .fade-in data-fragment-index=1}
[Object B]{.fragment .grow data-fragment-index=2}

---

🖥️ Progressive Syntax Highlighting (highlight.js)

Thanks to the fix-highlight.lua filter, code blocks can be animated line by line:

```{.python data-line-numbers="all|1-2|4|5-6"}
def demo():
    print("Lines 1-2 on first click")
    # comment
    print("Line 4 on second click")
    print("Lines 5-6")
    print("on third click")
```

---

∫ Mathematical Equations (MathJax / KaTeX)

Native LaTeX rendering via the --mathjax flag:

$$i\hbar\frac{\partial}{\partial t} \Psi(\mathbf{r},t) = \hat{H} \Psi(\mathbf{r},t)$$

---

🗃️ CSV File Import

The csv-tables.lua filter reads your .csv files directly and generates Pandoc tables on the fly:

```{.csv src="assets/data.csv" sep=";" header="true" align="l,c,r" limit=10}
```

Available options:

Attribute	Description	Default
src	Path to the CSV file	Required
sep	Column separator	Auto-detected (; or ,)
header	Use first row as header	true
align	Column alignment (l, c, r, d)	d
limit	Maximum number of rows to display	All

---

📊 Data Visualisation — ECharts

Inline JSON charts

Insert an ECharts JSON configuration directly inside a {.echarts} block:

::: {.echarts}
{
  "xAxis": {"type": "category", "data": ["A","B","C"]},
  "yAxis": {"type": "value"},
  "series": [{"type": "bar", "data": [10, 20, 15]}]
}
:::

Touchstone sNp file import (RF)

The echarts.lua filter natively parses S-parameter files .s1p, .s2p, .s3p, .s4p in MA (Magnitude-Angle), DB (dB-Angle) and RI (Real-Imaginary) formats:

::: {.echarts external="assets/measurement.s2p" modes="magS11_dB,magS21_dB"}
:::

Available modes per chart type:

Mode	Description
magSij_dB	Magnitude in dB
magSij	Linear magnitude
angSij	Phase in degrees
reSij	Real part
imSij	Imaginary part
Sij_smith	Smith chart
Sij_polar	Polar diagram

Multiple modes can be combined in the same chart: modes="magS11_dB,magS22_dB".

Gnuplot script conversion (.gnu) to ECharts

Gnuplot 4.4 scripts (self-file or with external data) are automatically converted to interactive ECharts charts:

::: {.echarts external="assets/my_plot.gnu"}
:::

Supported Gnuplot chart types:

• Classic XY — set xlabel, set ylabel, set xrange, set yrange, set logscale
• Polar — detected via set grid polar, rendered in a polar coordinate system
• Smith Chart — detected via parametric functions lu(t), tu(t,r), grid generated automatically
• Histogram — detected via smooth frequency + boxes, automatic bin width calculation (Scott's rule), rendered with a custom renderItem
• Gaussian Histogram — if a using … gauss(…) clause is detected: ±1σ/±2σ/±3σ coloured zones, Gaussian curve, percentage labels and dynamic sigma lines

Parsed Gnuplot features:

• Variables (name = value or name = "value")
• set style line N lc rgb '#rrggbb' lw N pt N
• with lines, linespoints, points, dots, impulses
• every :::N::N (block selection)
• Inline data (plot '-' … e)
• set datafile separator
• Automatic engineering notation on axes (×10ⁿ)
• linetype, linecolor rgb, pointtype inline per clause

Gnuplot Histograms

The converter also recognises Gnuplot's smooth frequency + boxes histogram idiom and renders a normalised histogram automatically (bin width via Scott's rule, bins centred on the mean). Add a using … gauss(…) clause to superimpose a Gaussian fit curve, ±1σ/±2σ/±3σ coloured zones, percentage labels, and population points:

::: {.echarts external="assets/histogram.gnu"}
:::

Keysight IC-CAP MDM Files

MarS-Doc also reads .mdm (Measurement Data Member) files natively — no conversion step required. The Report_Type attribute selects the chart kind:

::: {.echarts external="assets/measurement.mdm" y="ic" Y_Axis_Type="LINEAR" title="Ic(Vc)"}
:::

Report_Type	Description
XY_GRAPH (default)	Y = f(X) curve(s), one series per block × column/expression
SMITH_PLOT	Complex S-parameters on a Smith chart
POLAR_PLOT	Complex S-parameters in polar coordinates
RI_GRAPH	Real vs. imaginary parts on independently-scaled cartesian axes
HISTOGRAM	Normalised distribution of a column/expression, with optional gauss="true"

The y= attribute accepts a plain column name, a signed arithmetic expression combining several columns (e.g. y="-ic+ib" or y="2*ib-0.5*ic"), or — for SMITH_PLOT/POLAR_PLOT/RI_GRAPH — an S-parameter selector (S, S(1,1), or a list like S11,S22). X_Axis_Type / Y_Axis_Type accept LINEAR, LOG10, or DB.

---

🕸️ Graphviz Diagrams (DOT)

Graphviz's DOT language is ideal for hierarchies, dependency graphs, and state machines. MarS-Doc renders DOT client-side via Viz.js — no server or binary install required:

```{.dot}
digraph G {
    A -> B;
    B -> C;
}
```

The .graphviz class is accepted as an alias for .dot. An external file can also be used via a Div:

::: {.graphviz external="./assets/diagram.dot" height="400px"}
:::

---

🧩 nomnoml — Lightweight UML Diagrams

nomnoml is a compact text-to-UML DSL: describe boxes and arrows one relation per line, and the JS renderer computes the layout automatically:

```{.nomnoml}
[Foo] -> [Bar]
[Bar] -> [Baz]
```

External files are supported the same way:

::: {.nomnoml external="./assets/diagram.nomnoml" width="600px" height="400px"}
:::

---

🗺️ Markmap — Interactive Mind Maps from Markdown

Markmap turns ordinary Markdown headings and lists straight into an interactive, zoomable, collapsible mind map — no coordinates, no separate DSL: the structure you already write is the diagram.

```{.markmap height="420px"}
# Root
## Branch A
- leaf 1
- leaf 2
## Branch B
- leaf 3
```

The .markmap class also works on a Div, either with an external Markdown file or inline content (a child code block is preferred when present, so the raw headings/lists survive untouched):

::: {.markmap external="./assets/mindmap.md" height="450px"}
:::

Attribute	Description	Default
external	Path to a .md/.markmap file (Div only)	—
width / height	CSS dimensions of the container	100% / 500px
initial-expand-level	Depth initially expanded (-1 = fully expanded)	-1
color-freeze	Freeze a branch's colour to its root node instead of varying it by depth	false
duration	Expand/collapse animation duration (ms)	500
dark	Use markmap-view's built-in dark colour palette (light text), matching Reveal's black theme	true

Click a node to collapse/expand its branch; scroll to zoom, drag to pan — both provided natively by markmap-view, no extra toolbar needed.

---

📈 function-plot — Interactive Function Plotting

The .function-plot block wraps the function-plot library (built on D3.js): list one or more fn: expressions and get a pannable, zoomable graph, no image export needed:

```{.function-plot width="650" height="400"}
grid: true,
xAxis: { domain: [-6, 6] },
yAxis: { domain: [-5, 8] },
data: [
  { fn: 'x^2 - 4', color: '#ff4081', graphType: 'interval' },
  { fn: 'sin(x) * 2', color: '#29b6f6', graphType: 'interval' }
]
```

External .js configuration files are also supported via a Div (external=), along with width= / height= attributes (in pixels).

---

💬 Tippy.js — Contextual Tooltips

Show a tooltip on hover over any word or group of words, powered by Tippy.js, using the standard Pandoc span syntax with a .tooltip class and a title attribute:

Example with a [hoverable word]{.tooltip title="This is the content of my tooltip!"} inside a regular paragraph.

Attribute	Description	Default
title	Tooltip text content (required)	—
placement	top, bottom, left, right, auto (plus -start/-end variants)	top
theme	"" (native dark Tippy theme), light, light-border, material	native
animation	fade, shift-away, shift-toward, scale, perspective	fade
arrow	Show the small arrow pointing to the element	true
delay	Delay in ms, e.g. "200" or "200,0" (show, hide)	0
interactive	Keep the tooltip open while hovering over it	false
trigger	mouseenter focus, click, manual…	mouseenter focus
maxwidth	Maximum width in pixels	350

Any extra attribute you add (e.g. data-fragment-index) is passed straight through to the generated <span> element, so tooltips can be synced with Reveal.js fragments the same way as .rn and .mk marks.

---

🔀 Mermaid Diagrams

mermaid code blocks are rendered natively:

```mermaid
flowchart TD
    A([Start]) --> B{Valid?}
    B -->|Yes| C[Process]
    B -->|No| D[Error]
```

Supported types: flowchart, sequenceDiagram, gantt, classDiagram, stateDiagram, etc.

---

🌊 WaveDrom — Timing & Logic Diagrams

Render digital timing diagrams and bitfield/logic schematics with WaveDrom, directly from a fenced code block:

```wavedrom
{ signal: [
  { name: "clk",  wave: "p....." },
  { name: "data", wave: "x.345x", data: ["head", "body", "tail"] },
  { name: "req",  wave: "0.1..0" }
],
  "config": { "hscale": 2.2, "skin": "dark" }
}
```

External JSON files are also supported through a fenced Div, and diagrams are automatically re-rendered on every slide change:

::: {.wavedrom external="./assets/wavedrom.json"}
:::

Extracting Timing Diagrams from .vcd Files

Beyond hand-written JSON, MarS-Doc can extract a real timing diagram directly from a hardware simulation dump (a .vcd — Value Change Dump — file from a logic simulator or test bench). Pick the signals you care about and a time window; the filter figures out the sampling grid automatically:

::: {.wavedrom vcd="./assets/input.vcd"
     signals="CLK1,CLK2,CLK3,DATA"
     clocks="CLK1,CLK2,CLK3"
     clock="CLK1"
     start="50000" stop="100000"
     hscale=1 skin="dark"}
:::

Attribute	Description	Default
vcd	Path to the .vcd file	Required
signals	Comma-separated list of signals/buses to draw	Required
clocks	Subset of signals drawn with rising/falling edge arrows (H/L) instead of plain levels (h/l)	—
clock	Reference signal used to compute the sampling grid (a quarter of its period)	—
start / stop	Time window — a raw tick count or a value with a unit suffix (e.g. 50ns), automatically snapped to the nearest real timestamp in the file	Required
step	Ticks per WaveDrom character, overrides automatic detection and clock=	Auto
hscale / skin	Passed through unchanged to the WaveDrom config	1 / —

---

🎬 Asciinema — Embedded Terminal Recordings

Play back .cast terminal recordings straight inside a slide, with no external dependency: the file is base64-encoded and inlined as a data-URL at compile time.

::: {.asciinema external="./assets/demo.cast" autoplay="true" loop="true" speed="1.5" theme="monokai"}
:::

Attribute	Description	Default
external	Path to the .cast file (omit to use inline JSON-Lines content instead)	—
autoplay	Start playback automatically	false
loop	Loop playback	false
speed	Playback speed multiplier	2.0
theme	Player colour theme	monokai
font-size	Player font size	medium

---

🧠 Porphyry — Interactive Mind Maps

Render interactive mind maps with Porphyry.js, either from an external JSON file or inline:

::: {.porphyry external="./assets/porphyry.json" layout="auto" theme="solid" spacing="0.2" height="400px" interactions-collapse="true"}
:::

Supported options: layout, theme, spacing, height, width, and the interactions-* family (pan, zoom, collapse, hud, download) to enable individual user interactions.

---

✏️ Rough-Notation — Hand-Drawn Annotations

Draw hand-sketched annotations (underline, box, circle, highlight, strike-through, crossed-off, bracket) around any piece of text using the .rn span class:

This is an [important point]{.rn type="box"}.
The [key concept]{.rn type="circle" color="#5b9bd5"}.
A [positive outcome]{.rn type="highlight" color="#FFF17699"}.

Attribute	Description	Default
type	underline, box, circle, highlight, strike-through, crossed-off, bracket	underline
color	Annotation colour (CSS)	#e8c547
animate	Animate the drawing	true
animationDuration	Animation duration (ms)	800
strokeWidth	Stroke thickness (px)	1
iterations	Number of hand-drawn passes	library default

Rough-Notation combines naturally with Reveal.js fragments: add .fragment to play the annotation when the fragment appears, and reuse the same data-fragment-index (or fragment-index) on several .rn spans to trigger multiple annotations at once.

[Step A]{.rn .fragment fragment-index=1}
[Step B]{.rn type="box" .fragment fragment-index=1}

---

🖍️ .mk Marks — Lightweight Visual Emphasis

A second, independent emphasis system, lighter-weight than Rough-Notation: no hand-sketched animation, just clean CSS-driven marks in a colour of your choosing.

This delivers [mission-critical metrics]{.mk type="box"} instantly.
Always focus on the [core system architecture]{.mk type="underline" color="#5b9bd5"}.
Achieved a [45% performance boost]{.mk type="highlight" color="#4ade8055"}.
We no longer support [legacy styles]{.mk type="strike-through"}.

Attribute	Description	Default
type	underline, box, circle, highlight, strike-through, bracket	underline
color	Mark colour (CSS; supports rgba alpha, e.g. for highlights)	#e8c547
strokeWidth	Stroke/outline thickness (px)	2
padding	Padding around the text (px)	4
animationDuration	CSS transition duration (ms)	500

.mk combines naturally with Reveal.js .fragment: without a fragment class the mark is shown immediately; combined with .fragment it reveals via a left-to-right clip-path animation driven by Reveal.js. Any extra attribute you add (e.g. data-fragment-index) is passed straight through to the generated <mark> element.

---

🖼️ Image Zoom (Lightbox)

Clicking on any image in a slide displays it full screen in a lightbox. ECharts charts are also clickable (PNG export).

---

🖨️ PDF Export

From the toolbar (⚙️ → 🖨️), the presentation opens in ?print-pdf mode. Use the browser print function (Chrome recommended) to generate a PDF. The footer, logo and page numbers are automatically injected on each page.

---

🎨 Dynamic Per-Slide Backgrounds

## My Section {data-background-color="#1a1a2e"}
### My Slide {data-background-image="./assets/bg.png" data-background-opacity="0.5"}
### Video {data-background-video="./assets/loop.mp4"}
### Live {data-background-iframe="https://example.com"}

A global parallax background can be defined in the YAML header:

parallaxBackgroundImage: "./assets/background_default.png"
parallaxBackgroundSize: "cover"

---

🎼 ABC Notation — Sheet Music with Audio Playback

ABC notation is a compact plain-text format for folk and traditional music. MarS-Doc renders the score with ABCJS and, with audio="true", adds an interactive MIDI player so the audience can actually hear the tune:

```{.abc audio="true"}
T: Cooley's
M: 4/4
L: 1/8
K: Emin
|:D2|EB{c}BA B2 EB|~B2 AB dBAG|FDAD BDAD|FDAD dAFD|
EBBA B2 EB|B2 AB defg|afe^c dBAF|DEFD E2:|
```

An external .abc file is also supported via a Div:

::: {.abc external="./assets/tune.abc" audio="true"}
:::

Attribute	Description	Default
external	Path to a .abc file (Div only)	—
audio	Show the interactive MIDI player	false
autoplay	Autoplay the tune (ignored if audio="false")	false
responsive	Value passed through to ABCJS	resize
width / height	CSS dimensions of the container	100% / auto

---

🛠️ Tech Stack

Component	Technology	Version
Slide engine	Reveal.js	5.2.0
Conversion	Pandoc + LUA filters	≥ 3.8
Interactivity	Alpine.js	3.13.10
Data-viz	Apache ECharts	6.0.0
Diagrams	Mermaid.js	11.16.0
Timing/logic diagrams	WaveDrom	3.5.0
Diagrams (DOT)	Graphviz (via Viz.js)	2.1.2
UML diagrams	nomnoml	1.7.0
D3	D3	7.9.0
Mind maps (Markdown)	markmap (markmap-lib + markmap-view)	0.18.12
Function plotting	function-plot	1.22.2
Sheet music	ABCJS	6.4.4
Terminal recordings	Asciinema Player	3.6.3
Mind maps	Porphyry.js	1.6.2
Hand-drawn annotations	Rough Notation	0.5.1
Tooltips	Tippy.js	6.3.7
Equations	MathJax / KaTeX	—
Syntax highlighting	highlight.js	11.9.0
Chalkboard	RevealChalkboard (rajgoel)	—
Menu	RevealMenu	2.1.0
Font	IBM Plex Mono	20

---

🎨 Customisation

• Design: Edit css/custom.css. The theme uses the IBM Plex Mono font by default. All design values (colours, font sizes, spacing) are centralised in the CSS :root variables in css/slides.css.
• Templates: Files in templates/ control the HTML structure and script loading order (online and offline versions).
• Assets: Add your resources to assets/ (background images, logos); they will be copied to build/online/assets/ and build/offline/assets/ on the next make.
• Footer: Customise the footer text via the slide-footer: YAML variable in the slides.md header.

---

🙏 References & Credits

MarS-Doc stands on the shoulders of the following open-source projects. Many thanks to their authors and contributors:

Project	Purpose	Link
Pandoc	Markdown → HTML conversion engine, Lua filters	pandoc.org
Reveal.js	Core presentation/slide framework	revealjs.com
Alpine.js	Lightweight reactivity for interactive components	alpinejs.dev
Apache ECharts	Data visualisation / charting	echarts.apache.org
Mermaid.js	Text-to-diagram rendering (flowcharts, sequence, Gantt…)	mermaid.js.org
Viz.js	Graphviz (DOT) rendering in the browser	github.com/mdaines/viz-js
nomnoml	Lightweight text-to-UML diagrams	github.com/skanaar/nomnoml
markmap-lib / markmap-view	Markdown-to-mind-map transformation and interactive rendering	markmap.js.org
function-plot	Interactive mathematical function plotting (built on D3.js)	github.com/mauriciopoppe/function-plot
D3.js	Data-driven documents, used by function-plot and markmap	d3js.org
WaveDrom	Digital timing diagrams and bit-field/logic schematics	wavedrom.com
Asciinema Player	Terminal session recording playback	asciinema.org
Porphyry.js	Interactive mind maps	github.com/antoniu86/porphyry.js
Rough Notation	Hand-sketched annotations	roughnotation.com
Tippy.js	Contextual tooltips on hover	atomiks.github.io/tippyjs
ABCJS	ABC music notation rendering and MIDI playback	github.com/paulrosen/abcjs
MathJax / KaTeX	LaTeX equation rendering	mathjax.org / katex.org
highlight.js	Syntax highlighting for code blocks	highlightjs.org
reveal.js-plugins (rajgoel)	Chalkboard, custom controls, fullscreen, and other Reveal.js plugins	github.com/rajgoel/reveal.js-plugins
reveal.js-menu	Table-of-contents side menu for Reveal.js	github.com/denehyg/reveal.js-menu
QRCode.js	QR code generation for the WebSocket remote control	github.com/davidshimjs/qrcodejs
ntfy.sh	Lightweight pub-sub used as the WebSocket transport for the remote control	ntfy.sh
IBM Plex Mono / Fira Code / JetBrains Mono	Monospace fonts used by the default theme	fontsource.org

Each library retains its own license; see the runtime/ folder (offline build) for the bundled copies.

---

📜 License

Project licensed under MIT. Libraries included in runtime/ retain their respective licenses.