Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 19 additions & 3 deletions .claude/skills/readme-cli/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ npx @readme/cli lint --fix # Automatically fix common issues
npx @readme/cli lint --json # Machine-readable output (good for CI)
```

Validates: frontmatter, ordering, duplicates, OAS references, OAS schema, MDX components, and recipes.
Validates: frontmatter, ordering, duplicates, OAS references, OAS schema, MDX components, recipes, and the `_readme.yaml` config.

Always try `lint --fix` before attempting manual fixes.

Expand All @@ -28,7 +28,7 @@ Always try `lint --fix` before attempting manual fixes.
npx @readme/cli oas:sync
```

Syncs `reference/` directory with OpenAPI specs. Creates, updates, or removes pages based on spec operations. Run this when you see `oas-reference` errors.
Syncs `reference/` directory (and any other reference section declared in `_readme.yaml`) with OpenAPI specs. Creates, updates, or removes pages based on spec operations. Run this when you see `oas-reference` errors.

### OpenAPI Bundle

Expand Down Expand Up @@ -67,10 +67,26 @@ Starts a local dev server to preview docs with live reload.
The CLI expects to be run inside a git repo that has:

- A version branch matching `v[0-9]*` (e.g., `v1`, `v2.0`)
- A `docs/` and/or `reference/` directory at the repo root
- A `docs/` and/or `reference/` directory at the repo root (or a section declared in `_readme.yaml`)

Use `--no-check` to skip this validation if needed.

## Sections and `_readme.yaml`

Every repo has the built-in sections: `docs/`, `reference/`, `recipes/`, `custom_pages/`. A project with multiple guides declares extra sections in an optional `_readme.yaml` at the repo root:

```yaml
navigation:
- kind: guide # guide or reference
directory: sdks # top-level folder; lowercase letters, numbers, - and _
name: SDKs
```

- A declared `guide` section is linted like `docs/`; a declared `reference` section like `reference/`, including `oas:sync` and `oas:validate`.
- Repos without `_readme.yaml` are fine: only the built-in sections apply.
- A new top-level folder of pages is ignored by ReadMe until it's declared here. `lint` warns about a folder that has an `_order.yaml` but isn't declared.
- `lint` reports problems in the file under the `config` rule. These have no `--fix`; edit `_readme.yaml` by hand.

## Typical Workflow

1. Run `npx @readme/cli lint` to check for issues
Expand Down
23 changes: 23 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,29 @@ npx @readme/cli oas:bundle path/to/openapi.yaml --out reference/api.json

Without `--out`, the bundled spec is printed to stdout. The output format follows the `--out` extension (`.yaml`/`.yml` for YAML, JSON otherwise). This command works from any directory, so you can run it in your API's source repo.

### Multiple guides (`_readme.yaml`)

Every project has the built-in sections: `docs/`, `reference/`, `recipes/` and `custom_pages/`. If your project has more than one guide or API reference, they're declared in a `_readme.yaml` file at the root of the repo, each with its own directory:

```yaml
navigation:
- kind: guide
directory: docs
name: Guides
- kind: guide
directory: sdks
name: SDKs
- kind: reference
directory: reference
- kind: reference
directory: partner-api
name: Partner API
```

The CLI reads this file and treats each declared section like the built-in one of its kind: `lint` checks `sdks/` the way it checks `docs/`, and `oas:sync` and `oas:validate` cover the specs in `partner-api/` as well as `reference/`. `lint` also checks the file itself.

The file is optional. If your repo doesn't have one, nothing changes: the CLI works with the built-in sections, same as always.

### Import

Imports content from an external folder and converts it into ReadMe's format using Claude. Great for migrating existing docs.
Expand Down
2 changes: 1 addition & 1 deletion action.yml
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ outputs:
skipped-count:
description: Reference pages skipped because the destination filename already exists (oas:sync only)
skipped:
description: JSON array of skipped pages, each { filename, path, operationId } (oas:sync only)
description: JSON array of skipped pages, each { section, filename, path, operationId } (oas:sync only)
runs:
using: node24
pre: src/gha-pre.js
Expand Down
Loading