The compiler uses your local filesystem as the ground truth. Directories become navigation sections, Markdown files become content pages, and your filesystem hierarchy translates directly into web URLs.
1. Standard Project Scaffold
Run npx @docmd/core init to establish a minimal workspace layout. This structure keeps source content separated from assets and production builds.
my-docs/
├── docs/ ← Source directory containing your Markdown (.md) pages
│ └── index.md ← The landing page (resolves to /)
├── assets/ ← Static web assets loaded directly by the engine
│ ├── css/ ← Custom stylesheets for customising page layout
│ ├── js/ ← Custom scripts to extend browser-side logic
│ └── images/ ← Brand logos, icons, and inline illustrations
├── docmd.config.json ← Central configuration schema
├── package.json ← Node dependency manifest and scripts
└── site/ ← Optimised production build output directory
docmd.config.json (or docmd.config.ts) is the recommended, primary configuration format. The legacy docmd.config.js format acts strictly as a fallback when .json or .ts configuration files are missing.
2. Directory and URL Mapping
The compiler maps files within your source folder directly to public URLs. There are no trailing .html extensions or complex routing rules.
| Source File | Resolved URL Path | Purpose |
|---|---|---|
docs/index.md |
/ |
Home Landing Page |
docs/api.md |
/api |
Main API Reference |
docs/guides/setup.md |
/guides/setup |
Sub-section Technical Guide |
docs/getting-started/quick-start.md |
/getting-started/quick-start |
Multi-level deep page |
If a file lacks an explicit title in its YAML frontmatter, the engine automatically extracts the first H1 heading tag (# Heading). This title represents the page in breadcrumbs and search indexing.
3. Workspace Monorepo Structure
For complex layouts or large projects with multiple distinct products (such as a core platform, an SDK, and a CLI tool), docmd natively supports a Workspace Monorepo directory structure. This allows you to manage multiple independent documentation sites from a single root repository while maintaining unified branding.
my-docs-monorepo/
├── docmd.config.json ← Root configuration (defines global settings)
├── assets/ ← Shared global assets (inherited by all projects)
│ ├── css/ ← Shared global stylesheets
│ └── images/ ← Shared logos and icons
├── package.json ← Root dependency manifest
├── main-site/ ← Root project directory
│ ├── docmd.config.json ← Project-specific config overrides
│ └── docs/ ← Content for main-site (resolves to /)
│ └── index.md
└── sdk-reference/ ← Secondary project directory
├── docmd.config.json ← Project-specific config overrides
└── docs/ ← Content for sdk-reference (resolves to /sdk)
└── index.md
Key Workspace Directory Patterns
Any configuration defined in the root docmd.config.json (such as theme or menubar) acts as a fallback default. Individual projects selectively override these defaults in their local config files.
Shared logos, global custom styles, and common scripts sit in the root assets/ directory. Project-specific assets override root assets in the event of filename collisions.
During the build process (npx @docmd/core build), the engine merges all workspace projects into a single consolidated output directory (e.g. ./site/ and ./site/sdk/), removing the need for complex reverse proxy setups.
For complete setup steps and advanced cascading rules, refer to the Workspaces Configuration Guide.
