create-mdslides

A project scaffolding CLI for creating Markdown slide projects with Marp.

create-mdslides provides a ready-to-use project structure, including Marp themes, VS Code configuration, and supporting files.

Requirements

• Node.js 18 or later
• npm

Create a project

The recommended way to create a new project is:

npm create mdslides@latest

You will be prompted to enter the project directory.

You can also specify the directory directly:

npm create mdslides@latest my-slides

To create the project in the current directory:

npm create mdslides@latest .

Overwrite an existing directory

By default, create-mdslides refuses to create a project in a non-empty directory.

If you intentionally want to overwrite files provided by the template, use:

npm create mdslides@latest my-slides -- --force

or:

npm create mdslides@latest my-slides -- -f

Warning: Existing files with the same names as files in the template may be overwritten. Files that are not part of the template are preserved.

Project structure

A generated project has a structure similar to:

├── package.json
├── slides
│   ├── example.md
│   └── images
└── theme
    └── styles.css

The exact contents may change as the template evolves.

VS Code configuration

The generated project includes Marp configuration for VS Code.

For a standard presentation project:

{
    "markdown.marp.html": "all",
    "markdown.marp.themes": [
        "./template/themes/styles.css"
    ]
}

The custom theme is therefore available immediately after opening the project in VS Code.

Marp

The generated project is designed to work with Marp.

For the best editing experience in VS Code, install the Marp for VS Code extension.

After opening a Markdown file, you can use Marp's commands and preview features directly from VS Code.

Custom themes

Theme files are located under:

template/themes/

For example:

template/themes/styles.css

You can modify the theme to customize the appearance of your slides.

If you use the build process provided by the project, CSS files are minified while preserving the Marp theme declaration on the first line:

/* @theme eaut */

Typical workflow

Create a project:

npm create mdslides@latest my-slides

Enter the project:

cd my-slides

Open it in VS Code:

code .

Create or edit a Markdown slide file and use Marp's preview functionality.

Troubleshooting

Target directory is not empty

If you see:

Target directory is not empty.

the target directory already contains files.

Either use an empty directory or explicitly allow overwriting:

npm create mdslides@latest my-slides -- --force

License

MIT