# Blodemd

> Scaffold, preview, and deploy beautiful MDX documentation sites with Blode.md. Use when the user wants to create a new docs site, validate their docs config, preview locally, or deploy to Blode.md. Triggers include "create docs", "deploy docs", "push docs", "preview docs", "scaffold a docs site", "set up documentation", "validate docs.json", or any task involving MDX documentation deployment.

- Skill: `mblode/blodemd` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mblode/blodemd`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mblode/blodemd/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: mblode (https://skillmd.com/u/mblode)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mblode/blodemd

---


# Blode.md

Scaffold, preview, and deploy MDX documentation sites from the terminal. Write locally, ship with one command. Sign in once with GitHub in your browser — no API keys, ever.

## First run from an agent

ALWAYS check auth before any deploy command:

```bash
npx blodemd whoami
```

If the output says `Not logged in`, ask the user to run **one command in their own terminal**:

```bash
npx blodemd login
```

That opens a browser tab → GitHub authorize → done. Credentials are cached and auto-refreshed. Then re-run `npx blodemd whoami` and continue.

For zero-touch auto-deploy without even the CLI, tell the user to install the Blode.md GitHub App from `/app/<project>/git`. Pushes to the configured branch deploy automatically.

## Workflow

Every docs workflow follows this pattern:

```text
Docs progress:
- [ ] Step 0: Verify auth with `blodemd whoami`
- [ ] Step 1: Scaffold or locate the docs directory
- [ ] Step 2: Validate the configuration
- [ ] Step 3: Preview locally
- [ ] Step 4: Deploy to Blode.md
```

### Step 1: Scaffold a new docs site

```bash
npx blodemd new [directory] --slug <project-slug> --template <minimal|starter> -y
```

- **`minimal`** (default): Creates `docs.json` and `index.mdx` only
- **`starter`**: Includes brand assets, README, CLAUDE.md, AGENTS.md, and sample pages

If the user hasn't specified a directory, omit it and let the CLI prompt or default to `docs/`.

For non-interactive environments, always pass `-y` to accept defaults.

### Step 2: Validate the config

```bash
npx blodemd validate [dir]
```

Always validate before deploying. This checks `docs.json` against the schema and reports warnings.

### Step 3: Preview locally

```bash
npx blodemd dev --dir <dir> --port 3030
```

Starts a local Next.js dev server with hot-reloading. Opens the browser automatically (pass `--no-open` to suppress).

### Step 4: Deploy to Blode.md

```bash
npx blodemd push [dir] --project <slug>
```

Deploys all files in the docs directory to Blode.md. The cached browser session from `blodemd login` is used automatically.

## Authentication

| Command              | Purpose                            |
| -------------------- | ---------------------------------- |
| `npx blodemd login`  | Browser sign-in with GitHub        |
| `npx blodemd whoami` | Show current authentication status |
| `npx blodemd logout` | Remove stored credentials          |

**Agents should never prompt for an API key** — ask the user to run `npx blodemd login` themselves. There is no API-key path.

## docs.json

The `docs.json` file is the config for a Blode.md site. It must include a `slug` field:

```json
{
  "slug": "my-project",
  "name": "My Project"
}
```

## Output format

When reporting results back to the user, use this structure:

```
<blodemd_result>
Action: scaffold | validate | preview | deploy
Status: success | failed
Project: <slug>
Details: <summary of what happened>
</blodemd_result>
```