@docmd/core

v0.6.5

Published

4 days ago

The minimalist, zero-config documentation generator.

Features

Zero Config: Intelligent auto-routing scans your folders and builds navigation trees instantly.
Versioning: Enterprise-grade versioning (v1, v2) with sticky context switching and smart routing.
Super Fast: Generates pure static HTML. No hydration gap. No heavy React/Vue overhead.
AI-Ready: Automatically generates llms.txt and llms-full.txt context for AI agents.
PWA: Native Progressive Web App support for offline access and smart background caching.
Smart Search: Built-in, privacy-friendly offline search with deep-linking to exact headers.
Isomorphic: Runs seamlessly in Node.js (CLI) or directly in the browser via Live Editor.
Rich Content: Native Markdown support for Tabs, Steps, Callouts, and Mermaid diagrams.
SEO Optimized: Auto-generates sitemaps, canonical tags, 404 pages, and static HTML redirects.

Getting Started

You can run docmd on-the-fly without installing, or add it permanently to your long term projects.

Option 1: Zero-Config (Try it instantly)

Run docmd inside any folder containing markdown files. It will automatically extract your headers and build a nested navigation sidebar.

# Start local dev server
npx @docmd/core dev -z

# Generate production static site
npx @docmd/core build -z

Note: Zero-Config (-z) is currently in beta. It is fantastic for quick previews, but for production sites, we recommend initializing a standard configuration file for maximum control.

Option 2: Project Installation (Recommended)

For permanent projects, install docmd as dependency to lock your versions.

# 1. Install locally
npm install @docmd/core

# 2. Initialize your configuration
npx docmd init

# 3. Start developing
npx docmd dev

Option 3: Global Installation

Install once and use the docmd command anywhere on your machine.

npm install -g @docmd/core

docmd dev        # Start the local dev server
docmd build      # Generate the production static site

Project Structure

docmd keeps your repository clean. Your content lives in docs/, your config in docmd.config.js.

my-docs/
├── docs/                  # Your Markdown Files
│   ├── index.md           # Homepage
│   └── guide.md           # Content Page
├── assets/                # Images and Custom JS/CSS
├── docmd.config.js        # The docmd Configuration
└── package.json           # Node.js Dependencies

Configuration

docmd provides a highly flexible API. Customize your site in seconds via docmd.config.js. Here is a robust example showing off our most powerful features:

const { defineConfig } = require('@docmd/core');

module.exports = defineConfig({
  title: 'My Project',
  url: 'https://mysite.com',
  src: 'docs',
  out: 'site',
  
  // Enterprise Versioning
  versions: {
    current: 'v2', // Builds to root (/) for optimal SEO
    all:[
      { id: 'v2', dir: 'docs', label: 'v2.x (Latest)' },
      { id: 'v1', dir: 'docs-v1', label: 'v1.x' }
    ]
  },

  // Layout & UI Architecture
  layout: {
    spa: true,  // Enable buttery-smooth page transitions
    header: { enabled: true },
    sidebar: { collapsible: true },
    
    optionsMenu: {
      position: 'header',
      components: {
        search: true,
        themeSwitch: true
      }
    },

    footer: {
      style: 'minimal'
    }
  },
  
  // Custom Navigation (If not using Zero-Config)
  navigation:[
    { title: 'Home', path: '/', icon: 'home' },
    {
      title: 'Guide',
      icon: 'book-open',
      children:[
        { title: 'Installation', path: '/installation' },
        { title: 'API Reference', path: '/api' },
      ],
    }
  ],

  // Theme Settings
  theme: {
    name: 'sky',           // 'default', 'sky', 'ruby', 'retro'
    appearance: 'system',  // 'light', 'dark', 'system'
  },

  // Powerful Plugins (Zero setup required)
  plugins: {
    search: {},
    pwa: { themeColor: '#0097ff' },  // Makes your docs installable!
    llms: { fullContext: true },     // Generates llms-full.txt
    mermaid: {}
  },

  // SEO & Error Handling
  redirects: { '/old-guide': '/installation' },
  notFound: { title: 'Page Not Found', content: 'This page has moved.' }
});

Advanced Usage

Programmatic API

docmd exports its core engine, allowing you to build documentation programmatically within your own Node.js scripts or CI/CD pipelines.

const { build, buildLive } = require('@docmd/core');

// Trigger a standard documentation build
await build('./docmd.config.js', { 
  isDev: false, 
  offline: false 
});

// Build the Live Editor standalone bundle
await buildLive();

Live Editor (`docmd live`)

docmd features an isomorphic architecture. Running npx @docmd/core live builds a standalone web application where you can write Markdown and see the preview instantly without any server-side processing.

You can also try our docmd live editor online.

Comparison

Community & Support

Contributing: We welcome PRs! See CONTRIBUTING.md.
Support: If you find docmd useful, please consider sponsoring the project or giving it a star ⭐.

The `docmd` Ecosystem

docmd is a modular system. Here are the official packages:

The Engine

@docmd/core - The CLI runner and build orchestrator.
@docmd/parser - The pure Markdown-to-HTML logic.
@docmd/live - The browser-based Live Editor bundle.

Interface & Design

@docmd/ui - Base EJS templates and assets.
@docmd/themes - Official themes (Sky, Ruby, Retro).

Plugins

@docmd/plugin-installer - Plugin installer for docmd.
@docmd/plugin-search - Offline full-text search.
@docmd/plugin-pwa - Progressive Web App support.
@docmd/plugin-mermaid - Diagrams and flowcharts.
@docmd/plugin-seo - Meta tags and Open Graph data.
@docmd/plugin-sitemap - Automatic sitemap generation.
@docmd/plugin-llms - AI context generation.
@docmd/plugin-analytics - Google Analytics integration.

License

Distributed under the MIT License. See LICENSE for more information.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme