gulp-md

Gulp plugin for parsing Markdown files and converting them to sanitized HTML using marked and DOMPurify. Supports both ESM and CommonJS.

Features

• Markdown to HTML: Uses marked for fast and extensible Markdown parsing.
• Security by default: Automatically sanitizes HTML output with isomorphic-dompurify to prevent XSS attacks.
• Stream & Buffer support: Handles both buffer and stream file contents seamlessly.
• TypeScript ready: Includes full TypeScript definitions.
• Zero configuration: Works out of the box, but allows custom marked options.
• Gulp 5 compatible: Built for the latest Gulp ecosystem.

Installation

npm install gulp-md --save-dev
# or
pnpm add -D gulp-md
# or
yarn add -D gulp-md

Quick Start

Create a gulpfile.js (or .mjs / .ts):

import { src, dest } from 'gulp'
import markdown from 'gulp-md'

export function compileMarkdown() {
  return src('src/**/*.md')
    .pipe(markdown())
    .pipe(dest('dist/html'))
}

Run with:

gulp compileMarkdown

API

markdown([options])

Returns a Transform stream that converts .md files to .html.

Parameters

• options (object, optional) – Configuration object passed to marked.setOptions(). If omitted, default marked options are used.

Returns

• Transform stream instance.

Examples

Basic usage with Gulp tasks

import { src, dest, series, watch } from 'gulp'
import markdown from 'gulp-md'

function build() {
  return src('docs/*.md')
    .pipe(markdown())
    .pipe(dest('public/docs'))
}

function watchFiles() {
  watch('docs/*.md', build)
}

export { build, watchFiles }
export default series(build, watchFiles)

Custom Markdown options

import markdown from 'gulp-md'

const customOptions = {
  gfm: true,
  breaks: false,
  headerIds: true,
}

function parse() {
  return src('src/*.md')
    .pipe(markdown(customOptions))
    .pipe(dest('out'))
}

Using with template engines (e.g., Twig)

You can combine gulp-md with other Gulp plugins to embed generated HTML into templates.

import markdown from 'gulp-md'
import replace from 'gulp-replace'

function generatePages() {
  return src('src/pages/*.md')
    .pipe(markdown())
    .pipe(replace('{{ content }}', (match) => match)) // example placeholder
    .pipe(dest('dist/pages'))
}

How it works

1. Reads each .md file from the Gulp stream.
2. Parses Markdown content into HTML using marked.
3. Sanitizes the HTML with DOMPurify to remove potentially dangerous elements/attributes.
4. Changes the file extension to .html and passes it downstream.

Both buffer and streaming modes are supported; the plugin automatically chooses the appropriate processing method.

Project structure

gulp-md/
├── ts/gulp-md.ts          # TypeScript source
├── lib/                   # Compiled output (ESM + CJS)
├── src/                   # Example/documentation sources
├── package.json
├── README.md
└── LICENSE

Development

Clone the repository and install dependencies:

git clone https://github.com/llcawc/gulp-md.git
cd gulp-md
pnpm install

Available scripts:

pnpm run build     # Compile TypeScript to lib/
pnpm run lint      # Run Biome linter
pnpm run fix       # Auto‑fix linting issues
pnpm run check     # Run Biome checks
pnpm run fmt       # Format code with Biome

Acknowledgments

• marked – Fast Markdown parser
• DOMPurify – HTML sanitizer
• Gulp – Streaming build system

License

MIT License. © 2025 llcawc. Made with ❤️ to beautiful architecture.