Markdown Space Site Generator

Turn markdown / MDX documents into complete, styled websites. This is the site generation engine behind markdown.space — it renders markdown with YAML frontmatter into full HTML pages with Bootstrap or Bulma themes, navbars, syntax highlighting, PWA support, and MDX/React components.

Install

npm i @markdownspace/site-generator

Usage

import SiteGenerator, {
    parseFrontmatter,
    AvailableBootstrapThemes,
    AvailableBulmaThemes
} from '@markdownspace/site-generator'

const html = SiteGenerator.generate(
    project, // { id, name, slug, pwa_support, documents? }
    doc,     // { id, name, slug }
    [],      // template contents to prefix (usually `_templates/*` docs)
    rawMarkdown, // the document body, optionally starting with YAML frontmatter
    baseURL  // e.g. 'https://example.com/'
)

generate() returns a complete HTML document string.

The same package runs in the browser (live previews), in Node, and in Cloudflare Workers.

Frontmatter options

Control the generated site from YAML frontmatter at the top of the document:

---
title: My Page
description: A page about something
theme: litera            # bootswatch/bulmaswatch theme name, or a full CSS URL
cssFramework: bulma      # 'bulma' (default) or 'bootstrap'
navbar: true
navbarTheme: dark
navbarLogo: /logo.png
navbarAutoLinks: true    # navbar links to every document in the project
overrideNavLinks:        # or explicit links
  - text: Home
    href: /
mdx: true                # compile MDX/JSX (React via esm.sh)
autoclasses:             # extra classes for rehype-add-classes
  h2: title is-4
favicon: /favicon.ico
ogImage: /og-image.png
filesHost: https://files.example.com      # override asset host (default: https://files.markdown.space)
defaultFaviconBase: https://cdn.example.com  # default favicon set base (default: markdown.space R2)
codeTheme: atom-dark-one
headPrepend: '<!-- ... -->'
headAppend: ''
bodyPrepend: ''
bodyAppend: ''
---

MDX imports

With mdx: true, import/export statements in the document are compiled into a browser module that renders the page client-side. Specifiers are resolved so everything on the page shares one React instance:

• bare npm specifiers (import { Button } from '@markdownspace/components', import _ from 'lodash') are rewritten to https://esm.sh/<pkg> with React pinned to the site's reactVersion (default 18.3.1)
• react / react-dom imports are always pinned to the site's reactVersion
• imports of @markdownspace/components (bare, any esm.sh URL, any pinned version) always resolve to the current published build with React pinned
• full URLs to other packages (e.g. https://esm.sh/reactstrap@8) are kept as-is

Import/export statements never appear in the server-rendered HTML; MDX components render client-side, and if the client script fails for any reason the server-rendered content is revealed with an error banner instead of a blank page.

Development

npm i
npm run build    # esbuild bundle to dist/ + type declarations to dist-types/
npm test         # vitest
npm run build:w  # watch mode

The bundle inlines the mustache layout templates (src/templates/*.mustache) and polyfills node built-ins so the output runs in browsers and workers.

Releasing

Releases are published to npm automatically when a GitHub release is created (.github/workflows/publish-npm.yml).