@mindfiredigital/mdslide-core

v0.0.3

Published

2 months ago

The core compilation, normalization, and rendering engine for `mdslide`. It orchestrates the transformation of a parsed Markdown AST into interactive, styled slide decks.

0High
0Medium
0Low

mindfire

lakinmindfire

@mindfiredigital/mdslide-core

The core compilation, normalization, and rendering engine for mdslide. It orchestrates the transformation of a parsed Markdown AST into interactive, styled slide decks.

Quick Start

Install the package:

npm install @mindfiredigital/mdslide-core
# or
bun add @mindfiredigital/mdslide-core

Use the Compiler class to compile a Markdown string into an HTML slide deck:

import { Compiler } from '@mindfiredigital/mdslide-core';

const compiler = new Compiler();
const html = await compiler.compile(`
# Hello World

Welcome to mdslide!

---

## Slide Two

- Bullet one
- Bullet two
`);

console.log(html); // Full HTML presentation output

Compiler Architecture & Pipeline Flow

The compilation process is managed by the central Compiler class and flows through the following pipeline:

flowchart TD
    A[Markdown Input] --> B[YAML Parser]
    B -->|Content| C[Parser & Lexer]
    C -->|Raw Slide Blocks| D[AST Normalizer]
    D -->|Slide-Level Properties| E[Layout/Split Transformer]
    E -->|Structured AST| F[Overflow Engine]
    F -->|Budget-Normalized AST| G[HTML/Theme Engine]
    G --> H[Final Web presentation HTML]

Key Core Modules

1. Parser & Lexer (`src/parser/`)

Translates raw Markdown source string into slide chunks. Slicing boundaries are detected using a three-phase boundary resolution model:

Phase 1 (Explicit Dividers): Identifies thematic breaks (---), the explicit  marker, or level-2 headings (##) to split slides.  always means "start a new slide here," and — like --- — it suppresses the ## heuristic elsewhere in the same document, so an agent generating one slide at a time never has to guess which mode the rest of the file is in.
Phase 2 (Heading Boundaries): If none of the above are present, it splits the document at every major header level H1 (#) or H3 (###).
Phase 3 (Fallback Budget Chunking): If the document is flat text with no headers or dividers, it accumulates node layout weights until it crosses MAX_SLIDE_SCORE (100) and splits to maintain legibility.

2. Normalizer & Metadata Extractor (`src/normalizer/`)

Translates standard MDAST nodes into custom Slide AST representations. It parses and filters slide configurations declared in HTML comments:

Layout Overrides:  overrides layout classification (title, bullets, code, visual, table, quote, statement, split). A slide containing a ::split::/::col:: boundary skips this whole-slide extraction entirely (it's a no-op there) — layout is instead resolved per column by the transformer, below.
Background Images:  mounts custom backgrounds.
Title Positioning:  (horizontal alignment) and  (vertical alignment) are normalized and appended to slide data attributes.
Content Alignment:  is normalized with the same top/center/bottom helper as titlePosition, but controls how the body content packs within its own box rather than where the title+content block sits as a group.
Column Hints:  is parsed into a columnsConfig (count/ratio) carried on the slide for the transformer (below) to validate against the actual ::col:: markers.
Speaker Notes: Text inside ... is extracted as slide notes.
Admonition Detection (normalizeAdmonition.ts): a blockquote whose first paragraph starts with a recognized [!KIND] marker gets an admonition field, with the marker text stripped from its content (the marker-only paragraph is dropped entirely; inline marker+text keeps the paragraph with just the prefix removed).
Chart Annotations (parseChartAnnotations in normalizeLayout.ts): unlike every other annotation here, this one is node-scoped rather than slide-scoped — a  comment is paired with the table node immediately following it (by array adjacency, before column-splitting), attaching a chart field to that specific table.
Image Fit/Position (parseImageConfig in normalizeLayout.ts):  and  are parsed together, validated against a fixed value set (an invalid value is dropped with a warning), and carried on the slide.
Accent Color (parseAccentColor in normalizeLayout.ts):  captures a freeform CSS color value verbatim (no fixed value set — validating full CSS color syntax is left to the CLI's validate command's lightweight shape check).

3. Layout & Column Transformer (`src/transformers/`)

Handles advanced multi-column transformations:

Manual Splits (::split::): Locates the ::split:: separator block, groups nodes on the left and right, wraps them in column sub-containers, and applies the split layout. Always exactly two, unratioed columns — unchanged from before.
N-Column Splits (::col::): Generalizes the above to any number of columns — count(::col::) + 1 columns, checked before ::split::. Applies the columnsConfig ratio hint (from the normalizer, above) to each column when its length matches the actual column count, warning and falling back to equal widths otherwise.
Per-Column Layout Override: Both column-building paths (::split:: and ::col::) resolve each column's own layout independently via resolveColumnLayout, which reuses the same resolveSlideLayout the whole-slide path uses (hasTitle: false, restricted to VALID_COLUMN_LAYOUT_TYPES — the full VALID_SLIDE_TYPES set minus title/split). A  comment inside a column's own segment forces that column's layout; otherwise it auto-detects from its own content, exactly like a whole slide would.
Auto-Splits: If a slide contains exactly one image alongside text, the engine automatically splits them into a two-column layout (text on left, image on right). If a slide contains only an image, it transforms it to a full-screen visual layout.

4. Visual Overflow Engine (`src/overflow/`)

To prevent contents from bleeding out of the viewport, the overflow engine calculates the vertical size of each node in pixels:

Height Heuristics:
- Code Block: 50px header + 24px * number of lines.
- Table: 35px header + 38px * number of rows.
- Bullet List Item: text wrapping count (evaluated at 55 chars per line) * 30px + 10px margin.
- Image: 350px.
- Paragraph: text wrap count (at 65 chars/line) * 30px + 15px.
- Headings: H1: wrap count _ 65px + 20px; H2/H3: wrap count _ 45px + 15px.
Splitting Rules: If the total height exceeds 680px, it splits lists and code blocks. Remaining items are pushed onto a new continuation slide, retaining the parent settings and appending (Cont.) to the title.

5. Theme Engine (`src/themes/`)

Injects styling systems:

Resolves base styles (like 1080p slide margins, transitions, and docks) and integrates custom CSS variables for predefined themes:

| Theme | Description | |--------------|----------------------------------------------------------| | light | Clean white background with dark text. Default theme. | | dark | Dark background with light text for low-light settings. | | notion | Minimal, Notion-inspired serif typography. | | terminal | Monospace green-on-black terminal aesthetic. | | gradient | Vibrant gradient backgrounds with bold typography. | | corporate | Professional, neutral palette for business presentations.| | solarized | Warm solarized color scheme, easy on the eyes. |

Slide Syntax & Layout Customization

mdslide compiles standard Markdown files. You control structure, layout, typography, animations, and overflow behaviors using YAML frontmatter (for global defaults) and HTML comment annotations (for slide-specific overrides).

1. Settings Inheritance & Overrides

Settings can be defined both globally and locally:

Global Defaults: Defined at the very top of your presentation file using YAML frontmatter. These settings apply to all slides.
Slide-Specific Overrides: Declared inside individual slides using HTML comment annotations. When a slide-specific setting is present, it overrides the global default for that slide only.

2. Slide Separation

: Always starts a new slide, independent of heading structure — recommended when generating one slide at a time.
Manual Separation: Add --- on a blank line to start a new slide.
Automatic Separation: Level-2 headings (##) automatically start a new slide unless the above are used.

3. Layout Comments & Overrides

You can manually force a specific layout style on any slide using an HTML comment:

 (Main title layout)
 (Bumps font size and styles lists nicely)
 (Full-width preformatted syntax highlighted code block)
 (Displays images prominently)
 (Stylized blockquote focus)
 (Formats tables centrally)
 (Giant centered message layout)
 (Multi-column content structure layout)

4. Advanced Layouts & Column Splitting

Manual Column Split (`::split::`)

To split a slide into two equal side-by-side columns:

# Columns Layout

Left Column contents.

- Item A
- Item B

::split::

Right Column contents.

- Item C
- Item D

N-Column Split (`::col::`)

For more than two columns, use ::col:: between each column instead of ::split::, optionally with  for unequal widths:

<!-- columns: 3 ratio:2:1:1 -->

Build stuff

::col::

Test stuff

::col::

Deploy stuff

The declared count/ratio are validated against the actual number of ::col::-delimited segments; a mismatch falls back to equal-width columns (and mdslide validate warns about it).

Per-Column Layout Override

Each column resolves its own layout independently, the same way a whole slide does. Placing  inside a specific column's segment forces that column's layout without touching its siblings:

<!-- columns: 3 ratio:2:1:1 -->
<!-- layout: code -->

\`\`\`bash
npm run build
\`\`\`

::col::

- Smoke tests

::col::

Deploy stuff, no special layout here.

The first column is forced to code; the others auto-detect (bullets, content). Valid values exclude title/split.

Automatic Split Detection

If a slide contains exactly one image and text block, mdslide automatically generates a split layout with the text on one side and the image on the other. If the slide contains only a single image, it renders as a full-screen image cover slide.

5. Slide Title Alignments, Positions & Content Alignment

Override default alignments for any slide's title block:

 - Horizontal alignment: left | center | right
 - Vertical position: top | center | bottom

Independently,  controls how the body content packs within its own space (top | center | bottom) — unlike titlePosition, it doesn't move the title, just how content sits below it. Useful for a short statement slide that shouldn't sit glued to the top.

6. Dynamic Background Images & Smart Contrast

To apply a background image to an individual slide:

<!-- backgroundImage: url('https://example.com/image.jpg') -->

Smart Contrast Detection: mdslide evaluates the image on render. If the background image is dark, slide text flips to light; if the background is light, text shifts to dark gray.
Forced Override: Force a theme contrast by adding dark or light inside the comment:
```

```

7. Speaker Notes (Presenter View)

Wrap notes inside comment blocks anywhere on a slide. These will be visible in the synced Presenter console window during delivery:

<!-- notes -->

Here are my speaker notes for this slide.

<!-- /notes -->

8. Mathematical Equations, GFM & Mermaid Diagrams

mdslide includes full support for GitHub Flavored Markdown (GFM), math formatting, and diagramming out of the box:

Mathematical Equations (KaTeX):
- Inline Math: Wrap LaTeX formulas in single dollar signs $, e.g., $E = mc^2$ .
- Block Math: Wrap formulas in double dollar signs $$ for centered display math:
```
$$
f(x) = \int_{-\infty}^{\infty} e^{-x^2} dx
$$
```
Mermaid Diagrams:
- Render flowcharts, sequence diagrams, state diagrams, and more directly on your slides using mermaid fenced code blocks. This integration leverages Mermaid.js for dynamic, text-based diagram generation:
```
```mermaid
  graph TD
      A[Start] --> B(Process)
      B --> C{Decision}
      C -->|Yes| D[Success]
      C -->|No| E[Fail]
```
```
GitHub Flavored Markdown (GFM):
- Tables: Design aligned comparison and data tables.
- Task Lists: Create checkboxes with - [ ] and - [x].
- Strikethrough: Cross out text using ~~strikethrough~~.
Admonitions / callouts: a blockquote starting with [!KIND] (note, tip, important, warning, caution) renders as an icon + colored callout box instead of a plain blockquote.
Stats / metric grid: a fenced code block tagged stats, with one Label: value pair per line, renders as a row of big-number metric cards.
Chart from a table:  immediately above a table renders it as an inline-SVG chart instead of a grid — the first column is the category axis, additional columns become chart series (a pie chart uses only the first value column).
Image fit/position:  overrides the scaling of every image/video on a slide;  controls which side the image sits on in the auto-detected image+text split layout.
Video/GIF embed: .mp4/.webm URLs in ordinary image syntax render as an autoplaying, looping, muted <video> instead of an <img>; .gif is left as a plain <img> since it already autoplays/loops on its own.
Per-slide accent color:  overrides the theme's accent color (list markers, links, borders, chart palette) for just that one slide.

9. Custom Typography, Colors & CSS Overrides

Customize the theme styling using standard CSS variables inside a <style> block:

Example Override

<style>
  /* Import distinct display fonts: Creepster (spooky) and Press Start 2P (8-bit pixel) */
  @import url('https://fonts.googleapis.com/css2?family=Creepster&family=Press+Start+2P&display=swap');

  :root {
    /* Override default fonts */
    --slide-font: 'Creepster', cursive;
    --slide-mono: 'Press Start 2P', monospace;

    /* Customize colors and styling */
    --slide-accent: #ff007f; /* Bright neon pink */
    --slide-text: #111111; /* Dark charcoal */
    --slide-radius: 12px; /* Rounder borders */
  }
</style>

10. Presentation Navigation & Controls

When presenting your compiled HTML slides in the browser, you can use the following keyboard shortcuts and interactive actions:

Programmatic Usage

You can invoke the compiler programmatically by importing the Compiler class:

import { Compiler } from '@mindfiredigital/mdslide-core';

const compiler = new Compiler();
const result = compiler.compile(
  `# Slide 1
Content with Math: $E = mc^2$

<style>
:root {
  --slide-accent: #ff007f;
}
</style>
---
# Slide 2`,
  { theme: 'gradient' }
);

console.log(result.html); // Standalone HTML slide deck with CSS styles injected
console.log(result.slides); // Normalized Slide AST array
console.log(result.meta); // Parsed frontmatter configuration metadata

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@mindfiredigital/mdslide-core

Quick Start

Compiler Architecture & Pipeline Flow

Key Core Modules

1. Parser & Lexer (src/parser/)

2. Normalizer & Metadata Extractor (src/normalizer/)

3. Layout & Column Transformer (src/transformers/)

4. Visual Overflow Engine (src/overflow/)

5. Theme Engine (src/themes/)

Slide Syntax & Layout Customization

1. Settings Inheritance & Overrides

2. Slide Separation

3. Layout Comments & Overrides

4. Advanced Layouts & Column Splitting

Manual Column Split (::split::)

N-Column Split (::col::)

Per-Column Layout Override

Automatic Split Detection

5. Slide Title Alignments, Positions & Content Alignment

6. Dynamic Background Images & Smart Contrast

7. Speaker Notes (Presenter View)

8. Mathematical Equations, GFM & Mermaid Diagrams

9. Custom Typography, Colors & CSS Overrides

Example Override

10. Presentation Navigation & Controls

Programmatic Usage

1. Parser & Lexer (`src/parser/`)

2. Normalizer & Metadata Extractor (`src/normalizer/`)

3. Layout & Column Transformer (`src/transformers/`)

4. Visual Overflow Engine (`src/overflow/`)

5. Theme Engine (`src/themes/`)

Manual Column Split (`::split::`)

N-Column Split (`::col::`)