### Quick Start: Clone, Configure, Install, and Run Web Dev

Source: https://github.com/doocs/md/blob/main/CONTRIBUTING.md

Commands to fork and clone the repository, add the upstream remote, install dependencies with pnpm, and start the local development server for the @md/web workspace.

```bash
git clone https://github.com/<你的用户名>/md.git
cd md

git remote add upstream https://github.com/doocs/md.git

pnpm install

pnpm web dev
```

--------------------------------

### Run Wrangler Dev Server

Source: https://github.com/doocs/md/blob/main/docs/examples/wechat-openapi-worker/README.md

Navigate to the example directory and start a local development server for the Worker using Wrangler.

```bash
cd docs/examples/wechat-openapi-worker
npx wrangler dev worker.js
```

--------------------------------

### Install and run @doocs/md-cli via npm

Source: https://github.com/doocs/md/blob/main/README-EN.md

Install the CLI globally with npm, then start the server on the default port 8800 or specify a custom port with the 'port' option. The CLI supports additional options like 'spaceId' and 'clientSecret' for dcloud service configuration.

```sh
npm i -g @doocs/md-cli

# Start (default port: 8800)
md-cli

# Start with a custom port
md-cli port=8899
```

--------------------------------

### Install and run @doocs/md-cli via npm

Source: https://github.com/doocs/md/blob/main/README.md

Install the @doocs/md-cli package globally and start the server. The default listening port is 8800, and you can specify a different port with the port argument. If the port is occupied, a random port is automatically selected.

```sh
# 全局安装
npm i -g @doocs/md-cli

# 启动（默认端口 8800）
md-cli

# 指定端口启动
md-cli port=8899
```

--------------------------------

### Example prompts for the MCP server

Source: https://github.com/doocs/md/blob/main/packages/mcp-server/README.md

Example prompts to use with the MCP server once connected. They ask the AI assistant to render Markdown with a specific theme, list available themes, explain Markdown extensions, and find an AI service supporting DeepSeek-V3.

```text
使用 grace 主题将下面的 Markdown 渲染为 HTML，开启代码行号：
# Hello World
```

```text
列出所有可用主题，并解释每个主题的风格特点。
```

```text
render_markdown 支持哪些 Markdown 扩展？给我每个扩展的示例写法。
```

```text
列出所有内置 AI 服务，帮我找一个支持 DeepSeek-V3 的接入点。
```

--------------------------------

### Root directory pnpm commands

Source: https://github.com/doocs/md/blob/main/AGENTS.md

Root-level pnpm commands for installing dependencies, starting the dev server, linting, type-checking, building the CLI, releasing the CLI, packaging the uTools plugin, and inspecting the dependency tree.

```bash
pnpm install          # 安装所有依赖
pnpm start            # 等同于 `pnpm web dev`
pnpm run lint         # ESLint --fix 全项目检查
pnpm run type-check   # vue-tsc 类型检查
pnpm run build:cli    # 构建 web + 复制到 md-cli + npm pack
pnpm run release:cli  # 通过 scripts/release.js 发布 CLI
pnpm utools:package   # 打包 uTools 插件
pnpm run inspector    # node-modules-inspector 查看依赖树
```

--------------------------------

### POST /marketplace/:id/install

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Installs a marketplace item, incrementing download count and returning the payload.

```APIDOC
## POST /marketplace/:id/install

### Description
Installs a marketplace item, incrementing download count and returning the payload.

### Method
POST

### Endpoint
/marketplace/:id/install

### Parameters
#### Path Parameters
- **id** (string) - Required - The marketplace item ID.

### Response
#### Success Response (200)
- **payload** (object) - The item payload.
```

--------------------------------

### Install md-cli locally

Source: https://github.com/doocs/md/blob/main/packages/md-cli/README.md

Installs the md-cli package locally for use in a specific project.

```bash
npm install @doocs/md-cli
```

--------------------------------

### Install md-cli globally

Source: https://github.com/doocs/md/blob/main/packages/md-cli/README.md

Installs the md-cli package globally for access across all projects.

```bash
npm install -g @doocs/md-cli
```

--------------------------------

### Local Environment Configuration: VITE_LAUNCH_EDITOR

Source: https://github.com/doocs/md/blob/main/CONTRIBUTING.md

Example .env.local content to set the VITE_LAUNCH_EDITOR environment variable to 'cursor' for debugging in the apps/web directory.

```plaintext
VITE_LAUNCH_EDITOR=cursor
```

--------------------------------

### Run the MCP server with pnpm

Source: https://github.com/doocs/md/blob/main/packages/mcp-server/README.md

Commands to run the MCP server directly or in watch mode. The start command connects to stdin/stdout for manual testing; the dev command enables auto-restart on changes.

```bash
# Run server directly (connects to stdin/stdout — for manual testing)
pnpm --filter @md/mcp-server start

# Watch mode (auto-restart on changes)
pnpm --filter @md/mcp-server dev
```

--------------------------------

### GET /marketplace/components

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Lists approved components. Public endpoint.

```APIDOC
## GET /marketplace/components

### Description
Lists approved components. Public endpoint.

### Method
GET

### Endpoint
/marketplace/components

### Response
#### Success Response (200)
- **items** (array) - List of approved components.
```

--------------------------------

### Clone and install doocs/md

Source: https://github.com/doocs/md/blob/main/packages/mcp-server/README.md

Clone the doocs/md monorepo and install dependencies with pnpm. Requires Node.js ≥ 22.22.2 and pnpm ≥ 9.

```bash
git clone https://github.com/doocs/md.git
cd md
pnpm install
```

--------------------------------

### GET /me

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Returns the current authenticated user's information, including plan, plan expiration, and admin status.

```APIDOC
## GET /me

### Description
Returns the current authenticated user's information, including plan, plan expiration, and admin status.

### Method
GET

### Endpoint
/me

### Authentication
Bearer JWT required.

### Response
#### Success Response (200)
- **user** (object) - Current user details.
  - **plan** (string) - User's plan (free or pro).
  - **planExpiresAt** (string) - Plan expiration timestamp.
  - **isAdmin** (boolean) - Whether the user is an admin.
```

--------------------------------

### CLI & MCP pnpm commands

Source: https://github.com/doocs/md/blob/main/AGENTS.md

Commands for the CLI and MCP server: run commands in @doocs/md-cli, run commands in @md/mcp-server (including MCP tools like render_markdown), and start the MCP server in watch mode.

```bash
pnpm cli <cmd>        # 在 @doocs/md-cli 中执行命令
pnpm mcp <cmd>        # 在 @md/mcp-server 中执行命令（render_markdown 等 MCP 工具）
pnpm mcp dev          # MCP Server 监听模式
```

--------------------------------

### VS Code MCP server configuration

Source: https://github.com/doocs/md/blob/main/packages/mcp-server/README.md

Configuration for the MCP server in VS Code. Add to `.vscode/mcp.json` in the project root (already included in this repo). Then open the MCP panel in VS Code and start the `md` server.

```json
{
  "servers": {
    "md": {
      "type": "stdio",
      "command": "node",
      "args": ["--import", "tsx/esm", "${workspaceFolder}/packages/mcp-server/run.mjs"],
      "cwd": "${workspaceFolder}/packages/mcp-server"
    }
  }
}
```

--------------------------------

### Development and Build Commands

Source: https://github.com/doocs/md/blob/main/README-EN.md

Shell commands for setting up the environment, running the dev server, building for production, and packaging extensions. Requires Node.js and pnpm. The dev server runs at http://localhost:5173/md/. Production builds are served under /md/ or at the root path. Chrome extension dev mode requires loading the unpacked extension from apps/web/.output/chrome-mv3-dev. Firefox extension output is apps/web/.output/md-{version}-firefox.zip. uTools plugin output is apps/utools/release/md-utools-v{version}.zip.

```sh
# Install the required Node version
nvm i && nvm use

# Install dependencies
pnpm i

# Start the dev server, available at http://localhost:5173/md/
pnpm web dev

# Production build, served under /md/
pnpm web build

# Production build, served at the root path
pnpm web build:h5-netlify

# Chrome extension dev mode
# After starting, open chrome://extensions/, enable Developer mode,
# then load the unpacked extension from apps/web/.output/chrome-mv3-dev
pnpm web ext:dev

# Package the Chrome extension
pnpm web ext:zip

# Package the Firefox extension — output: apps/web/.output/md-{version}-firefox.zip
pnpm web firefox:zip

# Package the uTools plugin — output: apps/utools/release/md-utools-v{version}.zip
pnpm utools:package

# Cloudflare Workers development and deployment
pnpm web wrangler:dev
pnpm web wrangler:deploy
```

--------------------------------

### GET /emojis/me

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Gets or creates the current user's personal emoji pack. Requires authentication.

```APIDOC
## GET /emojis/me

### Description
Gets or creates the current user's personal emoji pack. Requires authentication.

### Method
GET

### Endpoint
/emojis/me

### Authentication
Bearer JWT required.

### Response
#### Success Response (200)
- **pack** (object) - The user's emoji pack.
```

--------------------------------

### Pull Request Title Example

Source: https://github.com/doocs/md/blob/main/CONTRIBUTING.md

Example of a conventional commit style PR title with a scope, matching the first commit message.

```plaintext
feat(editor): add custom keyboard shortcuts
```

--------------------------------

### Development Workflow: Run Checks

Source: https://github.com/doocs/md/blob/main/CONTRIBUTING.md

Commands to run linting, type checking, and build verification for the web app.

```bash
pnpm run lint        # ESLint + Prettier
pnpm run type-check  # TypeScript 类型检查
pnpm web build       # 产物验证
```

--------------------------------

### Run md-cli with default settings

Source: https://github.com/doocs/md/blob/main/packages/md-cli/README.md

Launches md-cli with default settings.

```bash
md-cli
```

--------------------------------

### 创建 D1 数据库

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

使用 wrangler d1 create 创建 D1 数据库，输出中的 database_id 需填入 wrangler.toml。

```bash
pnpm api exec wrangler d1 create md-sync
```

--------------------------------

### 打包 uTools 插件命令

Source: https://github.com/doocs/md/blob/main/apps/utools/README.md

运行 `pnpm utools:package` 会依次构建前端资源、写入版本号、复制图标并生成安装包。需要 Node.js 22+ 和 pnpm 10+。

```sh
pnpm utools:package
```

--------------------------------

### GET /auth/github

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Redirects the user to GitHub for OAuth authorization.

```APIDOC
## GET /auth/github

### Description
Redirects the user to GitHub for OAuth authorization.

### Method
GET

### Endpoint
/auth/github

### Response
#### Success Response (302)
Redirect to GitHub authorization page.
```

--------------------------------

### GET /emojis/default

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Returns the default emoji list. Public endpoint.

```APIDOC
## GET /emojis/default

### Description
Returns the default emoji list. Public endpoint.

### Method
GET

### Endpoint
/emojis/default

### Response
#### Success Response (200)
- **emojis** (array) - List of default emojis.
```

--------------------------------

### 设置 GitHub 上传令牌

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

设置 GitHub 上传令牌，逗号分隔 PAT。可选变量包括 UPLOAD_GITHUB_USERNAME、UPLOAD_GITHUB_REPO_LIST、UPLOAD_GITHUB_BRANCH、UPLOAD_GITHUB_USE_CDN。

```bash
pnpm api exec wrangler secret put UPLOAD_GITHUB_TOKENS_BUCKETIO   # 逗号分隔 PAT
```

--------------------------------

### GET /marketplace/admin/pending

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Lists pending marketplace items for admin review.

```APIDOC
## GET /marketplace/admin/pending

### Description
Lists pending marketplace items for admin review.

### Method
GET

### Endpoint
/marketplace/admin/pending

### Authentication
Bearer JWT required. Admin only.

### Response
#### Success Response (200)
- **items** (array) - List of pending items.
```

--------------------------------

### GET /marketplace/me

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Lists the current user's marketplace items. Requires authentication.

```APIDOC
## GET /marketplace/me

### Description
Lists the current user's marketplace items. Requires authentication.

### Method
GET

### Endpoint
/marketplace/me

### Authentication
Bearer JWT required.

### Response
#### Success Response (200)
- **items** (array) - List of user's marketplace items.
```

--------------------------------

### Basic usage of initRenderer and renderMarkdown

Source: https://github.com/doocs/md/blob/main/packages/core/README.md

Initializes the renderer with options for Mac-style code blocks and line numbers, then renders Markdown and post-processes the HTML for WeChat compatibility.

```ts
import { initRenderer, renderMarkdown } from '@md/core'
import { postProcessHtml } from '@md/core/utils'

const renderer = initRenderer({
  isMacCodeBlock: true,
  isShowLineNumber: true,
})

const html = postProcessHtml(renderMarkdown(renderer, markdown))
```

--------------------------------

### Web application (@md/web) pnpm commands

Source: https://github.com/doocs/md/blob/main/AGENTS.md

Commands for the @md/web application: Vite dev server, production build, Netlify deployment build, bundle analysis, Chrome/Firefox extension development and packaging, and Cloudflare Workers development and deployment.

```bash
pnpm web dev          # 启动 Vite 开发服务器
pnpm web build        # 生产构建 + 类型检查
pnpm web build:h5-netlify   # 构建用于 Netlify 根目录部署
pnpm web build:analyze      # 构建并生成 rollup-plugin-visualizer 分析
pnpm web ext:dev      # WXT Chrome 扩展开发模式
pnpm web ext:zip      # 打包 Chrome 扩展
pnpm web firefox:dev  # WXT Firefox 扩展开发模式
pnpm web firefox:zip  # 打包 Firefox 扩展
pnpm web wrangler:dev    # Cloudflare Workers 开发
pnpm web wrangler:deploy   # Cloudflare Workers 部署
```

--------------------------------

### GET /sync/pull

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Pulls changes since a given cursor (timestamp) for incremental sync.

```APIDOC
## GET /sync/pull

### Description
Pulls changes since a given cursor (timestamp) for incremental sync.

### Method
GET

### Endpoint
/sync/pull

### Parameters
#### Query Parameters
- **since** (number) - Required - Timestamp in milliseconds to fetch changes after.

### Authentication
Bearer JWT required.

### Response
#### Success Response (200)
- **changes** (array) - List of changes since the cursor.
```

--------------------------------

### 容器语法（::: tip）

Source: https://github.com/doocs/md/blob/main/apps/web/src/assets/example/markdown.zh-CN.md

容器语法示例，效果与警告块相同。

```markdown
::: tip
这是一个使用容器语法的提示框。
:::
```

--------------------------------

### GET /marketplace/themes

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Lists approved themes. Public endpoint. Supports search, sort, and pagination.

```APIDOC
## GET /marketplace/themes

### Description
Lists approved themes. Public endpoint. Supports search, sort, and pagination.

### Method
GET

### Endpoint
/marketplace/themes

### Parameters
#### Query Parameters
- **q** (string) - Optional - Search query.
- **sort** (string) - Optional - Sort order.
- **page** (number) - Optional - Page number.
- **limit** (number) - Optional - Items per page.

### Response
#### Success Response (200)
- **items** (array) - List of approved themes.
```

--------------------------------

### 开发命令：pnpm vscode watch/build/test/package

Source: https://github.com/doocs/md/blob/main/apps/vscode/README.md

在仓库根目录执行这些命令来开发、构建、测试和打包 VS Code 扩展。`pnpm vscode watch` 用于监听编译，`pnpm vscode build` 用于生产构建，`pnpm vscode test` 运行渲染路径 smoke test，`pnpm vscode package` 打包 .vsix 文件。

```sh
pnpm vscode watch      # webpack 监听编译
pnpm vscode build      # 生产构建
pnpm vscode test       # 渲染路径 smoke test
pnpm vscode package    # 打包 .vsix
```

--------------------------------

### GET /s/:shareId

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Returns a read-only share page. If password-protected, must be unlocked first.

```APIDOC
## GET /s/:shareId

### Description
Returns a read-only share page. If password-protected, must be unlocked first.

### Method
GET

### Endpoint
/s/:shareId

### Parameters
#### Path Parameters
- **shareId** (string) - Required - The share ID.

### Response
#### Success Response (200)
- **html** (string) - The rendered HTML snapshot.
```

--------------------------------

### 执行数据库迁移

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

执行本地或生产数据库迁移。

```bash
pnpm api db:migrate:local    # 本地开发库
pnpm api db:migrate:remote   # 生产库
```

--------------------------------

### GET /emojis/assets/:id

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

Returns an emoji asset. Public endpoint. System resources are cached long-term as immutable.

```APIDOC
## GET /emojis/assets/:id

### Description
Returns an emoji asset. Public endpoint. System resources are cached long-term as immutable.

### Method
GET

### Endpoint
/emojis/assets/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The emoji asset ID.

### Response
#### Success Response (200)
- **body** (binary) - The emoji image data.
```

--------------------------------

### 本地运行与部署

Source: https://github.com/doocs/md/blob/main/apps/api/README.md

本地运行或部署到 Cloudflare。首次生产发布顺序：创建两个 R2 bucket → 应用 D1 迁移 → 运行经确认的远程种子 → 部署 Worker。

```bash
pnpm api dev      # 本地 http://localhost:8787
pnpm api deploy   # 部署到 Cloudflare
```