MarpToPptx 1.0.0

MarpToPptx

MarpToPptx is a .NET 10 CLI and library for compiling Marp-flavored Markdown into editable PowerPoint presentations.

For a precise description of how this repo defines and implements Marp-style Markdown, see doc/marp-markdown.md.

For renderer and PowerPoint package requirements and compatibility reference material, see doc/pptx-compatibility-notes.md.

For the DocumentFormat.OpenXml 3.4.1 presentation-impact audit and related follow-up notes, see doc/openxml-3.4.1-audit.md.

For integrating MarpToPptx into a VS Code authoring workflow in a content repository, see doc/vscode-workflow.md.

For pre-release validation, hosted LibreOffice gate coverage, and the manual PowerPoint review checklist, see doc/release-validation.md.

Current Structure

• src/MarpToPptx.Core: semantic slide model, Markdown parsing, theme parsing, layout planning
• src/MarpToPptx.Pptx: Open XML PPTX rendering and template-aware presentation generation
• src/MarpToPptx.Cli: marp2pptx command-line entrypoint
• src/MarpToPptx.OpenXmlValidator: small .NET validation helper used by smoke tests and CI
• scripts/: PowerShell helpers for local generation, smoke tests, package inspection, and PowerPoint troubleshooting
• tests/MarpToPptx.Tests: xUnit v3 tests running on Microsoft Testing Platform
• samples/: Marp-style sample decks for smoke tests, feature coverage, theme parsing, and compatibility-gap repros
• .github/copilot-instructions.md: concise repo-specific Copilot guidance for PPTX compatibility, testing flow, and reference sources
• .github/prompts/: reusable prompts for PPTX compatibility investigation and implementation review workflows
• .github/workflows/ci.yml: Ubuntu build/test/pack plus an Ubuntu CI-safe PPTX smoke-test job

Usage

Preferred: DNX

dnx is the quickest way to run MarpToPptx without installing it as a persistent tool, but it requires .NET 10.

dnx MarpToPptx sample.md -o sample.pptx
dnx MarpToPptx sample.md --template theme.pptx
dnx MarpToPptx sample.md --theme-css theme.css

Install As A .NET Tool

If you prefer a persistent command, install the tool from NuGet:

dotnet tool install --global MarpToPptx
marp2pptx sample.md -o sample.pptx
marp2pptx sample.md --template theme.pptx
marp2pptx sample.md --theme-css theme.css

To update later:

dotnet tool update --global MarpToPptx

VS Code Task

Add a .vscode/tasks.json to your content repository to export the currently open file:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Export to PPTX",
      "type": "shell",
      "command": "dnx",
      "args": [
        "MarpToPptx",
        "${file}",
        "-o",
        "${fileDirname}/${fileBasenameNoExtension}.pptx"
      ],
      "group": "build",
      "presentation": { "reveal": "always", "panel": "shared" },
      "problemMatcher": []
    }
  ]
}

Run it from Terminal → Run Task while the Markdown file is open. The .pptx is written next to the source file.

For template-based export, theme CSS, version pinning, team sharing, and the full edit / preview / export loop with the Marp for VS Code extension, see doc/vscode-workflow.md.

Run From Source

If you are developing on the repo, you can still run the CLI project directly:

dotnet run --project src/MarpToPptx.Cli -- input.md -o output.pptx
dotnet run --project src/MarpToPptx.Cli -- input.md --template theme.pptx
dotnet run --project src/MarpToPptx.Cli -- input.md --theme-css theme.css

Local Packaging

Build a local tool package:

dotnet pack src/MarpToPptx.Cli -c Release

That produces a tool package under artifacts/nupkg/ with package ID MarpToPptx and command name marp2pptx.

Run it with dnx from the local package source:

dnx MarpToPptx --add-source ./artifacts/nupkg sample.md -o sample.pptx

You can also install it as a local tool from the package output:

dotnet new tool-manifest
dotnet tool install MarpToPptx --add-source ./artifacts/nupkg
dotnet tool run marp2pptx sample.md -o sample.pptx

Releases

NuGet publishing is handled by .github/workflows/publish.yml using nuget.org Trusted Publishing with GitHub OIDC.

Heavier pre-release validation is available separately through .github/workflows/release-gate.yml.

• Versioning is tag-based via MinVer.
• Stable release tags should use the form v1.2.3.
• The publish workflow builds, tests, packs, and then pushes the tool package from artifacts/nupkg/.

To cut a release:

git tag v1.2.3
git push origin v1.2.3

After the workflow finishes and NuGet indexing completes, install or run the published tool with:

dotnet tool install --global MarpToPptx
dnx MarpToPptx sample.md -o sample.pptx

Repository Conventions

• Solution format: MarpToPptx.slnx
• Centralized package management: Directory.Packages.props
• Test framework: xUnit v3
• Test runner: Microsoft Testing Platform via global.json
• CLI packaging direction: marp2pptx as a .NET tool, while preserving single-file publish as a deployment mode

Current Milestone

• Marp-style front matter and directive parsing
• Slide splitting on ---
• Semantic slide model independent from PPTX
• Theme extraction for fonts, colors, padding, background images, and core typography settings
• PPTX generation for headings, paragraphs, bullet lists, images, code blocks, native tables, and header/footer text
• Local audio and video embedding for supported media formats
• Template-copy workflow for reusing an existing .pptx theme/master

Steering Decisions

• ImageSharp is intentionally not used for image sizing unless it is explicitly re-approved after licensing review
• Intrinsic image sizing should prefer built-in platform capabilities or a minimal in-project metadata reader
• Remaining roadmap work should be evaluated against the current implemented baseline rather than an empty starting point

Roadmap

• Improve CSS coverage for more Marp theme features
• Refine layout heuristics for denser or highly designed decks
• Expand template integration to map multiple layouts intelligently
• Improve native PPTX table styling and layout fidelity
• Expand code block highlighting coverage and theme fidelity
• Support remote assets and additional image formats