MarS-Doc

MARkdown to Slide with panDOC — Slides as Code

RAYA Christian

(Press the spacebar or click on the right edge of the screen)

Welcome

What You Are About To See

This deck is a live feature catalogue for MarS-Doc. Every slide that follows is built from real Markdown — the same file you would write yourself — and demonstrates one concrete capability of the tool: no screenshots, no mock-ups.

Use this map to jump around later (press M for the menu, or O for the full overview):

🛠️ Getting Started — requirements, build pipeline, presenter tools, timer
🧱 Layouts — columns, rows, alerts, toggles, the guided stepper
📊 Data & Diagrams — CSV tables, ECharts (JSON, RF .sNp, Gnuplot, MDM), Mermaid, Graphviz, nomnoml, function-plot
⏱️ Timing Diagrams — WaveDrom, including direct .vcd hardware-log extraction
🎬 Recordings & Maps — Asciinema terminal replays, Porphyry mind maps
✨ Text Effects — Rough-Notation sketches, dynamic highlight marks, fragments
🎼 Music — ABC notation with an interactive audio player

Tip: try the ⚙️ toolbar in the bottom-left corner at any time — it works the same way throughout the whole deck.

Introduction

Welcome to MarS-Doc

MarS-Doc (Markdown to Slide with panDoc)

This tool is a presentation system designed for engineers, developers, and scientists.

It solves the chronic problems of traditional presentations:

🔀 Version control — Plain text files readable by Git.
🎨 Content vs. Form separation — You write the content, the engine handles the style.
🔒 Independence — Generate self-contained or connected HTML archives.

“If it’s not in version control, it doesn’t exist.”

System Requirements

To build this project locally, ensure your environment meets the following specifications:

Pandoc 3.8.+ : Required for advanced AST manipulation and latest Reveal.js template support.
GNU Make: Used to automate the build process, asset synchronization, and dual-target generation (Online/Offline).
Browser-Sync: Allows you to automatically update your slide as you edit it.

graph LR %% Nœuds principaux A["slides.md
(source)"] B["slides.html
(artifact)"] C["Reveal.js
(runtime)"] %% Connexions horizontales A -- "pandoc" --> B B -- "browser" --> C

Build Pipeline

make Commands

# Generate both versions
make 

# CDN-dependent version
make online

# Self-contained version
make offline

# Live-reload
make watch

Two distribution modes:

Online (slides_online.html): Uses CDNs for Reveal.js, ECharts, etc. Ideal for keeping the Git repository lightweight.
Offline (slides_offline.html): Embeds the LUA/JS runtime and fonts locally. Perfect for conferences without a reliable internet connection.

Presenter Tools

Look at the bottom left of your screen: a small gear wheel (⚙️) gives you access to a retractable toolbar containing essential functions:

⛶ Toggle Fullscreen: Enable/disable fullscreen mode.
📱 Remote Control: Displays the WebSocket QR Code.
⏱️ Timer: Displays the presentation stopwatch.
🖨️ PDF Print: Launches a clean export of the presentation.
⊞ Overview (O): Zooms out to see all slides at a glance.
✏️ Pen (C): Annotate directly on the current slide.
🂠 Chalkboard (B): Opens an interactive chalkboard.
🧽 Eraser: Clears your annotations.

Smartphone Remote (WebSocket)

Forget capricious USB clickers.

Click the 📱 icon in the bottom left toolbar.
A QR Code appears on the right side of the screen.
Scan it with your smartphone.
Your phone becomes an instant remote control (Next, Prev, Start, End) connected via WebSocket.

No app to install, everything happens directly in your phone’s browser.

Time Management (Timer)

Markdown Syntax

To define the time allocated to a slide (in seconds), insert this comment anywhere in the section:

   <!-- timing: 10 -->

How it works

The global timer (bottom right) activates on the first slide change. It automatically calculates the expected cumulative time. The colored dot indicates your pacing:

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

Layouts & Components

Multi-Column Layout

Image 1

Column 1

Image 2

Column 2

Image 3

Column 3

Image 4

Column 4

Image 5

Column 5

Custom Grids and Rows

Use the .rows-full class combined with background colors
(.bg-blue, .bg-yellow, width=30%, height=35%, etc.) to structure space without writing any HTML:

.bg-green .rounded-tl

.bg-red .rounded-bl

.bg-orange .rounded-tr

.bg-black .rounded-br

Custom Grids and Columns

Use the .cols-full class combined with background colors
(.bg-blue, .bg-yellow, width=25%, height=30%, etc.) to structure space without writing any HTML:

.bg-green .rounded-tl

.bg-orange

.bg-black .rounded-tr

.bg-blue .rounded-bl

.bg-yellow

.bg-red .rounded-br

Alpine.js: Alerts & Toggles

The .warning and .info classes automatically generate semantic callouts.

⚠️ Warning: This is a critical alert generated by LUA + Alpine.js.

ℹ️ Information: The toggle component hides text to avoid cluttering the slide.

::: {.toggle label="▶ Show Toggle source code"}
Here is the hidden content!
:::

The Stepper (Guided Workflow)

This uses Reveal.js’s native fragments: click through the list below, each step lights up in turn while the previous ones dim — a simple way to narrate a workflow without extra slides.

Write: Author your content in plain Markdown.
Compile: Run make online or make offline.
Present: Open the generated file in any modern browser.
Control: Scan the QR Code to navigate via your mobile device.

Data-Viz & Diagrams

CSV File Import

The LUA script directly reads your .csv files and generates the appropriate Pandoc tables on the fly.

Composant	Boîtier	Fonction principale	Statut
LFCN-80+	`FV1206`	Filtre Passe-Bas (DC - 80 MHz); Tolérance serrée	Validé
GALI-39+	`SOT-89`	Amplificateur RF gain élevé (20 dB @ 1 GHz)	En test
BAT15-04W	`SOT-323`	Diode Schottky pour détection de puissance RF	À valider

{.csv src="assets/table.csv" sep=";" header="true" align="l,c,l,r" limit=3}

The default separator is ; but you can specified de separator with sep=“;”
You can display only the first N rows using the ‘limit’ parameter
You can control the alignment of the columns using the ‘align’ parameter

Image zoom

Double click on the image to view it in full screen

ECharts: JSON Charts

Drop a standard Apache ECharts JSON configuration straight into a {.echarts} block — no external file, no build step. The chart below is fully interactive (hover for tooltips, click the legend to toggle series) and mixes lines, an area fill, and a bar series in one config.

ECharts: SNP Files. Directly reading your RF data files (.s2p, .s3p, .s4p).

Touchstone .sNp files are the standard format RF/microwave engineers use to store S-parameter measurements from a Vector Network Analyzer. MarS-Doc parses .s1p–.s4p files in MA, DB, or RI formats natively.

S2P Smith Chart

Plot magnitude in dB

ECharts: SNP Files

The same file, viewed through two other modes= selections — a polar diagram and linear-scale magnitudes:

S2P Polar Chart

Plot magnitude in linear

ECharts: Gnuplot conversion to echarts.js

MarS-Doc converts .gnu file to an interactive ECharts figure

Polar S-parameters from Gnuplot

XY Gnuplot Script

ECharts: Gnuplot conversion to echarts.js histogram

The converter also recognises Gnuplot’s smooth frequency + boxes histogram idiom.

Histogram from Gnuplot

Histogram with Gaussian function from Gnuplot

ECharts: MDM Support

Directly reading your Keysight IC-CAP .mdm files.

Ic(Vce) plot from mdm file

-Ic(Ib) plot from mdm file

ECharts: MDM Support SMITH_PLOT and POLAR_PLOT

Support also SMITH_PLOT or POLAR_PLOT directly from .mdm files

S parameters plot from mdm file

ECharts: MDM Support RI_GRAPH

Support also Real vs. Imaginary parts on plain RI_GRAPH directly from .mdm files

S parameters plot from mdm file

Support Nomnoml

nomnoml is a lightweight text-to-UML DSL: describe boxes and arrows on one line each, and the JS renderer lays the graph out for you — no coordinates to compute by hand.

Support Markmap

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.

Click a node to collapse/expand its branch, scroll to zoom, drag to pan.

Support Graphwiz - 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, no binary install, just a fenced .dot block:

function-plot support

Need to plot a mathematical function live? The .function-plot block wraps the function-plot/D3 library: list one or more fn: expressions and get a pannable, zoomable graph — no image export needed.

f(x) = x^3 ; g(x) = x^2 - 4 ; h(x) = sin(x) * 2

WaveDrom - Diagrams

WaveDrom draws digital timing diagrams and bit-field/logic schematics from a compact JSON description — no drawing tool required.

Wavedrom in markdown

Support of WaveDrom diagrams — hand-written JSON, describing each signal’s waveform as a short string (p=clock pulse, 0/1=levels, x=don’t-care, ==data value):

WaveDrom - External File

Prefer keeping diagrams in their own file? Point external= at a .json file with the same WaveDrom structure — handy for diagrams you reuse across several decks.

Include WaveDrom: ./assets/wavedrom.json

WaveDrom - VCD Support

Beyond hand-written JSON, MarS-Doc can extract a real timing diagram straight out of 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 (start=/stop=); the filter figures out the sampling grid on its own, using clock= to lock resolution onto your fastest reference clock and clocks= to draw clean rising/falling edge arrows on the clock traces.

Include vcd=“./assets/input.vcd”

Wavedrom in markdown

Support of WaveDrom symbols — the same JSON syntax can also describe logic/bitfield schematics (here, an 8-input XOR-then-AND-enable network) instead of a time-based waveform:

Asciinema - fake terminal

Asciinema - External File

Terminal session recordings (.cast files, made with the asciinema CLI) replay as a real, character-by-character terminal — perfect for CLI demos without the risk of a live terminal. The file is embedded directly as base64 at compile time, so there’s no separate asset to ship.

Include asciinema: ./assets/asciinema.cast

Porphyry - Mindmap

Porphyry in markdown

Porphyry.js turns a simple JSON tree into an interactive, collapsible mind map — great for brainstorms, taxonomies, or breaking a big topic into digestible branches. Try panning, zooming, and collapsing nodes below.

Include porphyry: ./assets/porphyry.json

Rough-notation Examples

Rough-Notation draws hand-sketched annotations — underline, box, circle, highlight, strike-through — around any span of text, and can be synchronised with Reveal.js fragments so the sketch appears exactly when you click.

This is an important point.

The key concept is highlighted right here.

Step A Step B

A highly positive outcome

And a completely negative result

Visual Emphasis via the `.mk` Class

A second, independent emphasis system — lighter-weight than Rough-Notation, with no sketch animation, just clean CSS-driven marks (box, underline, highlight, strike-through) in a colour of your choosing.

This framework delivers mission-critical metrics instantly.

Always focus on the core system architecture.

Achieved a 45% performance boost in the latest build.

We no longer support legacy ANSI C80 styles.

Tippy.js — Tooltips

Hover over any word to reveal a contextual tooltip, powered by Tippy.js.

Example with a hoverable word inside a regular paragraph.

Options: bottom placement, light theme, interactive mode.

Mermaid Diagrams

Mermaid.js renders flowcharts, sequence diagrams, and Gantt charts straight from text — version-controlled architecture diagrams that update as fast as you can edit a fenced ```mermaid block.

flowchart TD A([Start]) --> B{Input valid?} B -->|Yes| C[Process data] B -->|No| D[Return error] C --> E{Result OK?} E -->|Yes| F([✅ Done]) E -->|No| G[Log & retry] G --> B D --> F

sequenceDiagram autonumber actor User participant MarS-Doc participant Browser User->>MarS-Doc: make all MarS-Doc-->>Browser: slides_online.html User->>Browser: Opens the presentation Browser->>User: Renders HTML5 + ECharts

gantt title Project Timeline dateFormat YYYY-MM-DD section Research Requirements :done, r1, 2026-01-01, 2026-01-15 State of the art :done, r2, 2026-01-10, 2026-01-25 section Development Architecture :done, d1, 2026-01-20, 2026-02-10 Implementation :active, d2, 2026-02-05, 2026-03-15 Testing : d3, 2026-03-10, 2026-04-01 section Delivery Documentation : v1, 2026-03-25, 2026-04-10 Final review : v2, 2026-04-08, 2026-04-15

2D Navigation Model

Reveal.js organises slides on a 2D grid:

Direction	Key	Meaning in this deck
→ Right	`→`	Next thematic section
↓ Down	`↓`	Deeper technical detail
← Left	`←`	Previous section
↑ Up	`↑`	Previous slide (same section)

Tip: press O for the Overview to visualise the full grid at a glance.

Essential Keyboard Shortcuts

Key	Mode	Description
`S`	Speaker	Opens speaker view with notes + timer
`O`	Overview	Full 2D grid of all slides
`F`	Fullscreen	Hides browser chrome
`B`	Blackout	Black screen — refocuses audience
`V`	Pause	Pause without leaving the slide
`G`	Jump	Jump directly to a slide number
`P`	Previous	Previous slide
`N`	Next	Next slide
`M`	Menu	Table of Contents
`Esc`	Back	Exits current mode

Visual Features

Fragments — Step-by-Step Reveal

The most useful fragment classes in practice:

.fade-in — soft appearance (default)
.fade-in-then-out — appears, then disappears on next click
.highlight-red — red highlight without shifting layout
.highlight-current-blue — blue on active item, grey on others
.fade-out — gradual disappearance

Advanced Sequencing with `data-fragment-index`

[Text]{.fragment .fade-in data-fragment-index=1}

Live demonstration — multiple elements share the same index:

🔵 Object A — visible between click 1 and click 3
🟢 Object B — appears at click 2

🔴 Object C — grow at click 3, exactly when A disappears

Per-Slide Dynamic Backgrounds

Each slide can declare its own background:

Attribute	Example
`data-background-color`	`"#1a1a2e"`
`data-background-image`	`"./assets/bg.png"`
`data-background-video`	`"./assets/loop.mp4"`
`data-background-iframe`	`"https://example.com"`
`data-background-gradient`	`"linear-gradient(...)"`

Pandoc syntax — inline attribute on the heading:

## My Section {data-background-color="#1a1a2e"}

Code & Mathematics

Progressive Syntax Highlighting

Thanks to highlight.js and the fix-highlight.lua script, you can animate code line by line.

def demo_pipeline():
    print("🚀 Initializing MarS-Doc...")

    tools = ["Pandoc", "Reveal.js", "ECharts", "Mermaid", "Alpine.js"]
    for tool in tools:
        print(f"  ✅ Loading: {tool}")

data-line-numbers="all|1-2|4|5-6"

“all” : all lines highlighted on first click
“1-2” : lines 1 and 2 on second click
“4” : line 4 on third click
“5-6” : lines 5 and 6 on fourth click

MathJax Equations

Native LaTeX rendering is enabled via the --mathjax flag:

Schrödinger equation:

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

Fourier transform:

\[\hat{f}(\xi) = \int_{-\infty}^{\infty} f(x)\ e^{-2\pi i x \xi}\,dx\]

Partition ABC

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 — not just read it.

End of presentation

Ready to compile!

Your complete, versionable, and interactive presentation environment is now operational.

Useful links:

MarS-Doc

💡 Touch Navigation Tip

Welcome

Introduction

System Requirements

Build Pipeline

Presenter Tools

Smartphone Remote (WebSocket)

Time Management (Timer)

Layouts & Components

Custom Grids and Rows

Custom Grids and Columns

Alpine.js: Alerts & Toggles

The Stepper (Guided Workflow)

Data-Viz & Diagrams

Image zoom

ECharts: JSON Charts

ECharts: SNP Files. Directly reading your RF data files (.s2p, .s3p, .s4p).

ECharts: SNP Files

ECharts: Gnuplot conversion to echarts.js

ECharts: Gnuplot conversion to echarts.js histogram

ECharts: MDM Support

ECharts: MDM Support SMITH_PLOT and POLAR_PLOT

ECharts: MDM Support RI_GRAPH

Support Nomnoml

Support Markmap

Support Graphwiz - Diagrams (.dot)

function-plot support

WaveDrom - Diagrams

Wavedrom in markdown

WaveDrom - External File

WaveDrom - VCD Support

Wavedrom in markdown

Asciinema - fake terminal

Porphyry - Mindmap

Rough-notation Examples

Visual Emphasis via the .mk Class

Tippy.js — Tooltips

Mermaid Diagrams

2D Navigation Model

Essential Keyboard Shortcuts

Visual Features

Advanced Sequencing with data-fragment-index

Per-Slide Dynamic Backgrounds

Code & Mathematics

MathJax Equations

Partition ABC

End of presentation

Visual Emphasis via the `.mk` Class

Advanced Sequencing with `data-fragment-index`