wehub-resource-sync
277 lines
11 KiB
Markdown
277 lines
11 KiB
Markdown
|
||
<div align="center">
|
||
|
||
<a href="https://docmd.io">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://github.com/docmd-io/docmd/blob/main/packages/ui/assets/images/docmd-logo-dark.png?raw=true" />
|
||
<source media="(prefers-color-scheme: light)" srcset="https://github.com/docmd-io/docmd/blob/main/packages/ui/assets/images/docmd-logo-dark.png?raw=true" />
|
||
<img src="https://github.com/docmd-io/docmd/blob/main/packages/ui/assets/images/docmd-logo-dark.png?raw=true" alt="docmd" width="210" />
|
||
</picture>
|
||
</a>
|
||
|
||
<br/>
|
||
|
||
<p><b>Production-ready documentation from Markdown, in seconds.</b><br/>Zero config. AI-native. Built for developers.</p>
|
||
|
||
<p>
|
||
<a href="https://www.npmjs.com/package/@docmd/core"><img src="https://img.shields.io/npm/v/@docmd/core.svg?style=flat-square&color=CB3837" alt="npm version"></a>
|
||
<a href="https://www.npmjs.com/package/@docmd/core?activeTab=versions"><img src="https://img.shields.io/npm/dm/@docmd/core.svg?style=flat-square&color=38bd24" alt="monthly downloads"></a>
|
||
<a href="https://github.com/docmd-io/docmd"><img src="https://img.shields.io/github/stars/docmd-io/docmd?style=flat-square&logo=github" alt="GitHub stars"></a>
|
||
<a href="https://github.com/docmd-io/docmd/blob/main/LICENSE"><img src="https://img.shields.io/github/license/docmd-io/docmd.svg?style=flat-square&color=A31F34" alt="license"></a>
|
||
</p>
|
||
|
||
<h4>
|
||
<a href="https://docmd.io">Website</a> ·
|
||
<a href="https://docs.docmd.io">Documentation</a> ·
|
||
<a href="https://live.docmd.io">Live Editor</a> ·
|
||
<a href="https://github.com/docmd-io/docmd-skills">Agent Skills</a> ·
|
||
<a href="https://github.com/docmd-io/docmd/issues">Report a Bug</a>
|
||
</h4>
|
||
|
||
<br/>
|
||
|
||
<a href="https://docs.docmd.io">
|
||
<img width="820" alt="docmd default theme — light and dark mode preview" src="https://raw.githubusercontent.com/docmd-io/docmd/refs/heads/main/assets/docmd-cover.webp" />
|
||
</a>
|
||
|
||
<br/><br/>
|
||
|
||
</div>
|
||
|
||
## Quick Start
|
||
|
||
Run docmd in any folder with Markdown files — no install needed:
|
||
|
||
```bash
|
||
npx @docmd/core dev
|
||
```
|
||
|
||
<details>
|
||
<summary><b>Opens at <code>http://localhost:3000</code></b></summary><br>
|
||
|
||
```bash
|
||
_ _
|
||
_| |___ ___ _____ _| |
|
||
| . | . | _| | . |
|
||
|___|___|___|_|_|_|___|
|
||
|
||
v1.x.x
|
||
|
||
┌─ Build
|
||
│ Engine JS
|
||
│ Source docs/
|
||
│ Output site/
|
||
│ Versions 2 (06, 05)
|
||
│ Locales 7 (en, hi, zh, es, de, ja, fr)
|
||
└──────────────────────────────────────────────────────────
|
||
┌─ Data Indexing
|
||
│ [ DONE ] Syncing git metadata
|
||
│ [ DONE ] Building semantic search index (multi-version)
|
||
└──────────────────────────────────────────────────────────
|
||
┌─ Publishing
|
||
│ [ DONE ] Generated robots.txt
|
||
│ [ DONE ] Generated .nojekyll (disables Jekyll on GitHub Pages)
|
||
│ [ DONE ] Generated sitemap
|
||
│ [ DONE ] Generating LLMs context files
|
||
└──────────────────────────────────────────────────────────
|
||
|
||
⬢ Initial build completed in 1.2s.
|
||
|
||
┌─ Watching
|
||
│ Source ./docs
|
||
│ Config ./docmd.config.json
|
||
│ Assets ./assets
|
||
└──────────────────────────────────────────────────────────
|
||
┌─ Development Server Running
|
||
│ Local Access http://127.0.0.1:3000
|
||
│ Network Access http://192.168.1.6:3000
|
||
│ Serving from ./site
|
||
└──────────────────────────────────────────────────────────
|
||
```
|
||
</details>
|
||
|
||
<p align="center">
|
||
<img alt="docmd dev server preview" width="820" src="https://docmd.io/assets/images/dev-preview.gif">
|
||
</p>
|
||
|
||
Navigation is generated from your file structure. No config file, no frontmatter required, no framework to learn.
|
||
|
||
**When you're ready to ship:**
|
||
|
||
```bash
|
||
npx @docmd/core build
|
||
```
|
||
|
||
This outputs a highly optimized static site (SPA) ready for deployment to Vercel, Cloudflare Pages, Netlify, GitHub Pages, or any static host.
|
||
|
||
**Requirements:** Node.js 18+
|
||
|
||
<details>
|
||
<summary><b>Or install globally / via Docker</b></summary><br/>
|
||
|
||
```bash
|
||
# Install globally via npm
|
||
npm install -g @docmd/core
|
||
|
||
# Or via pnpm
|
||
pnpm add -g @docmd/core
|
||
|
||
# Run it
|
||
docmd dev # start dev server
|
||
docmd build # build for deployment
|
||
```
|
||
|
||
Or run via Docker:
|
||
|
||
```bash
|
||
docker run -p 3000:3000 ghcr.io/docmd-io/docmd:0.8.7
|
||
```
|
||
|
||
> Pin a version for reproducible builds.
|
||
|
||
</details>
|
||
|
||
## Why docmd?
|
||
|
||
| Feature | docmd | Docusaurus | MkDocs | VitePress | Mintlify |
|
||
| :--- | :---: | :---: | :---: | :---: | :---: |
|
||
| **Config required** | **None** | `docusaurus.config.js` | `mkdocs.yml` | `config.mts` | `docs.json` |
|
||
| **JS payload** | **~18 kb** | ~250 kb | ~40 kb | ~50 kb | ~120 kb |
|
||
| **Navigation** | **Instant SPA** | React SPA | Full reload | Vue SPA | Hosted SPA |
|
||
| **Versioning** | **Native** | Native (complex) | mike plugin | Manual | Native |
|
||
| **i18n** | **Native** | Native (complex) | Plugin-based | Native | Native |
|
||
| **Multi-project** | **Native** | Plugin | Plugin | - | - |
|
||
| **Search** | **Built-in** | Algolia (cloud) | Built-in | MiniSearch | Cloud |
|
||
| **AI context (`llms.txt`)** | **Built-in** | - | - | - | Built-in |
|
||
| **MCP server** | **Built-in** | - | - | - | Built-in |
|
||
| **Agent skills** | **Built-in** | - | - | - | - |
|
||
| **Docker image** | **Official** | - | Official | - | - |
|
||
| **Self-hosted** | **Yes** | Yes | Yes | Yes | - |
|
||
| **Cost** | **Free (OSS)** | Free (OSS) | Free (OSS) | Free (OSS) | Freemium |
|
||
|
||
## Features
|
||
|
||
### Zero config, instant start
|
||
Point docmd at any Markdown folder and it runs. Navigation is built automatically from your file structure. You can write your first doc and have it live in under a minute — no boilerplate, no build pipeline to configure, no decisions to make upfront.
|
||
|
||
### Tiny by default, fast everywhere
|
||
The default JavaScript payload is ~18 kb. Pages navigate as an instant SPA. The output is static HTML — SEO-optimised, with sitemap, canonical URLs, and Open Graph metadata included. Offline full-text search is built in, no cloud service required.
|
||
|
||
### AI-native
|
||
docmd is built for the way documentation is read and used today:
|
||
- **MCP Server** — `docmd mcp` exposes your docs to AI agents over stdio, letting them search, read, and validate content directly.
|
||
- **Context (`llms.txt` / `llms-full.txt`)** — complete documentation context generated at build time, ready for any LLM.
|
||
- **Agent Skills** — modular instruction sets for LLMs and IDE agents ([docmd-skills](https://github.com/docmd-io/docmd-skills)).
|
||
- **Copy as Markdown / Copy Context** — one-click buttons in the browser, optimised for pasting into AI chat.
|
||
|
||
### Built to scale
|
||
- Internationalisation with multi-locale builds
|
||
- Versioning for multiple doc releases
|
||
- Workspaces for monorepos and multi-project setups
|
||
- Plugin system for extending core behaviour
|
||
- Full theming support, built-in templates, custom CSS/JS, light/dark mode
|
||
|
||
## CLI
|
||
|
||
```bash
|
||
docmd dev # local development server
|
||
docmd build # build for deployment
|
||
docmd live # browser-based Live Editor
|
||
docmd migrate # import from Docusaurus, VitePress, MkDocs, or Starlight
|
||
docmd deploy # generate config for Docker, NGINX, Caddy, Vercel, Netlify
|
||
docmd validate # check all internal links
|
||
docmd mcp # run as an MCP server over stdio
|
||
docmd add <name> # install a plugin or template
|
||
```
|
||
|
||
## Plugins
|
||
|
||
Core functionality is powered by a robust plugin system. The essentials are included by default, while optional plugins can be added for specific needs.
|
||
|
||
| Plugin | Status | Description |
|
||
| :--- | :---: | :--- |
|
||
| `search` | ✅ Core | Offline full-text search with fuzzy matching |
|
||
| `seo` | ✅ Core | SEO tags and Open Graph metadata |
|
||
| `sitemap` | ✅ Core | Generates `sitemap.xml` |
|
||
| `git` | ✅ Core | Git commit history and last-updated dates |
|
||
| `analytics` | ✅ Core | Lightweight analytics integration |
|
||
| `llms` | ✅ Core | AI context generation (`llms.txt` / `llms-full.txt`) |
|
||
| `mermaid` | ✅ Core | Mermaid diagram support |
|
||
| `openapi` | ✅ Core | Build-time OpenAPI 3.x spec renderer |
|
||
| `pwa` | ➕ Optional | Progressive Web App — offline navigation |
|
||
| `threads` | ➕ Optional | Inline discussion threads *(by @svallory)* |
|
||
| `math` | ➕ Optional | KaTeX / LaTeX math rendering |
|
||
|
||
Install optional plugins:
|
||
|
||
```bash
|
||
docmd add <plugin-name>
|
||
```
|
||
|
||
Build your own: [Plugin Development Guide](https://docs.docmd.io/development/building-plugins/)
|
||
|
||
## Configuration
|
||
|
||
No configuration is required to get started. Add a `docmd.config.json` (or `.ts` / `.js`) in your project root only when you need more control:
|
||
|
||
```json
|
||
{
|
||
"title": "My Project",
|
||
"url": "https://docs.myproject.com",
|
||
"src": "./docs",
|
||
"out": "./dist"
|
||
}
|
||
```
|
||
|
||
TypeScript and JavaScript config files are supported for dynamic values.
|
||
|
||
Full reference: [Configuration Overview](https://docs.docmd.io/configuration/overview)
|
||
|
||
## Project Structure
|
||
|
||
```text
|
||
my-docs/
|
||
├── docs/ ← Your markdown files
|
||
├── assets/ ← Images and static files
|
||
├── docmd.config.json ← Optional configuration
|
||
└── package.json
|
||
```
|
||
|
||
## Live Editor
|
||
|
||
A browser-based editor for writing and previewing docs — no local setup required.
|
||
|
||
<p>
|
||
<img alt="docmd live editor preview" width="820" src="https://docs.docmd.io/assets/previews/live-editor-preview.webp">
|
||
</p>
|
||
|
||
**Try it at [live.docmd.io](https://live.docmd.io)**
|
||
|
||
## Programmatic API
|
||
|
||
Use docmd in Node.js scripts, CI pipelines, or custom build steps. (Supports both CommonJS and ESM).
|
||
|
||
```javascript
|
||
import { build } from '@docmd/core';
|
||
|
||
await build('./docmd.config.json', { isDev: false });
|
||
```
|
||
|
||
Full reference: [Node API](https://docs.docmd.io/development/node-api-reference/)
|
||
|
||
## Community
|
||
|
||
- **Bugs & issues** → [GitHub Issues](https://github.com/docmd-io/docmd/issues)
|
||
- **Questions & ideas** → [Discussions](https://github.com/orgs/docmd-io/discussions)
|
||
- **Contributing** → [CONTRIBUTING.md](.github/CONTRIBUTING.md)
|
||
- **Roadmap** → [GitHub Discussions](https://github.com/orgs/docmd-io/discussions/2)
|
||
|
||
## Support
|
||
|
||
- Getting the word out is the most direct way to support docmd's development. [Share it on X](https://twitter.com/intent/tweet?url=https://github.com/docmd-io/docmd&text=docmd%20-%20Production-ready%20docs%20from%20Markdown%20in%20seconds.) with friends or give it a star.
|
||
- If docmd saves you time, a [GitHub sponsorship](https://github.com/sponsors/mgks) goes a long way.
|
||
- Got ideas or bugs? Open an issue or PR, feel free to contribute your own plugins.
|
||
|
||
## License
|
||
|
||
MIT License. See `LICENSE` for details. |