@readme/cli 0.2.0 → 0.3.0

package/src/validators/content.js

@@ -28,12 +28,19 @@ export function validate({ filePath, content, relativePath }) {
     return null;
   }
   if (trimmed.length === 0) {
-    // index.md files that act as parent pages (have child .md siblings) can be empty.
+    // index.md files that act as parent pages (have child page siblings or nested page
+    // directories) can be empty. The backend accepts .md and .mdx in any case.
     if (path.basename(filePath) === 'index.md') {
-      const siblings = fs.readdirSync(path.dirname(filePath));
-      if (siblings.some(f => f.endsWith('.md') && f !== 'index.md')) {
-        return null;
-      }
+      const dir = path.dirname(filePath);
+      const isPage = f => /\.mdx?$/i.test(f);
+      const hasChildren = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .some(
+          e =>
+            (!e.isDirectory() && isPage(e.name) && !/^index\.mdx?$/i.test(e.name)) ||
+            (e.isDirectory() && fs.readdirSync(path.join(dir, e.name)).some(isPage)),
+        );
+      if (hasChildren) return null;
     }
 
     return {

package/src/validators/frontmatter.js

@@ -1,13 +1,10 @@
 import fs from 'node:fs';
-import { createRequire } from 'node:module';
-import path from 'node:path';
 
 import Ajv from 'ajv';
 
+import frontmatterSchema from '../../vendor/git-format/frontmatter.schema.json' with { type: 'json' };
 import { parseFrontmatter } from '../utils/markdown.js';
 
-const require = createRequire(import.meta.url);
-
 export const name = 'frontmatter';
 
 function getNestedValue(obj, instancePath) {
@@ -77,18 +74,15 @@ const DIR_SCHEMA_INDEX = {
   custom_blocks: 4,
 };
 
-// Load the schema and compile a validator for each directory type.
-const schemaPath = require.resolve('@readmeio/git-format/frontmatter.schema.json');
-const fullSchema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
-
+// Compile a validator for each directory type from the vendored schema.
 const ajv = new Ajv({ allErrors: true, strict: false, logger: false, verbose: true });
 
 const validators = {};
 const knownProperties = {};
 for (const [dir, index] of Object.entries(DIR_SCHEMA_INDEX)) {
-  const subSchema = { defs: fullSchema.defs, ...fullSchema.oneOf[index] };
+  const subSchema = { defs: frontmatterSchema.defs, ...frontmatterSchema.oneOf[index] };
   validators[dir] = ajv.compile(subSchema);
-  knownProperties[dir] = collectPropertyNames(subSchema, fullSchema.defs);
+  knownProperties[dir] = collectPropertyNames(subSchema, frontmatterSchema.defs);
 }
 
 export function validate({ content, filePath, relativePath, fix }) {

package/src/validators/oas-reference.js

@@ -9,6 +9,7 @@ import {
   operationKey,
   findIgnoredInternalExtensions,
 } from '../commands/oas-sync.js';
+import { PathEscapeError } from '../utils/containment.js';
 import { parseFrontmatter } from '../utils/markdown.js';
 
 export const name = 'oas-reference';
@@ -103,11 +104,24 @@ export function validateAll(files, gitRoot, { fix } = {}) {
   // reference files, which is far too much to do on the strength of an
   // unfixable warning (`x-readme.internal`, a page pointing at a missing spec).
   if (fix && results.some(r => r.fixable)) {
-    const syncResults = syncOas(gitRoot);
-    if (syncResults) {
-      for (const r of results) {
-        if (r.fixable) r.message += ' (fixed)';
+    try {
+      const syncResults = syncOas(gitRoot);
+      if (syncResults) {
+        for (const r of results) {
+          if (r.fixable) r.message += ' (fixed)';
+        }
       }
+    } catch (err) {
+      if (!(err instanceof PathEscapeError)) throw err;
+
+      // Don't mark the other fixes applied — sync stopped before it could.
+      results.push({
+        file: path.relative(gitRoot, err.target) || 'reference',
+        rule: name,
+        severity: 'error',
+        message: err.message,
+        fixable: false,
+      });
     }
   }
 

package/vendor/git-format/CLAUDE.md

@@ -0,0 +1,352 @@
+# ReadMe Git-Based Docs Format
+
+This repo is the reference implementation of ReadMe's Git-based documentation format. It defines how documentation is structured when syncing with ReadMe via Git.
+
+Any LLM modifying a repo that uses this format should reference this file and the examples in this repo.
+
+## Directory structure
+
+```
+your-repo/
+├── frontmatter.schema.json   # Frontmatter validation schema
+├── docs/                      # Guides and documentation pages
+│   ├── {Category Name}/       # Category folders (Title Case with spaces)
+│   │   ├── _order.yaml        # Page ordering within this category
+│   │   ├── page-slug.md       # Documentation pages (kebab-case filenames)
+│   │   └── parent-page/       # Parent page with children
+│   │       ├── index.md       # The parent page content
+│   │       └── child-page.md  # Child page nested under parent
+│   └── {Another Category}/
+│       └── ...
+├── reference/                 # API reference documentation
+│   ├── oas.json               # OpenAPI spec file(s)
+│   └── {API Title}/           # Matches info.title from OAS
+│       └── {Tag}/             # Matches OAS operation tags
+│           ├── index.md       # Optional category landing page
+│           └── operationId.md # Endpoint page linked to OAS operation
+├── recipes/                   # Code recipe/tutorial pages
+│   ├── _order.yaml
+│   └── recipe-slug.md
+├── custom_pages/              # Standalone pages (markdown or HTML)
+│   └── page-slug.md
+├── custom_blocks/             # Reusable content snippets and components
+│   ├── snippet.md             # Markdown snippet
+│   └── Component.mdx          # React component (single-file)
+└── reusable_content/          # (also valid top-level directory)
+```
+
+**Valid top-level directories:** `docs/`, `reference/`, `custom_pages/`, `recipes/`, `custom_blocks/`, `reusable_content/`
+
+## Frontmatter
+
+Every page uses YAML frontmatter. The full schema is in `frontmatter.schema.json`. Here's a summary by content type:
+
+### Doc pages (`docs/`)
+
+```yaml
+---
+title: Page Title        # Required
+excerpt: One-sentence summary
+hidden: true             # Hides page from navigation
+deprecated: true         # Marks page as deprecated
+icon: star               # Icon identifier
+metadata:
+  title: SEO Title
+  description: SEO description
+  keywords: [keyword1, keyword2]
+  image: https://example.com/image.png
+  robots: noindex         # "index" or "noindex"
+next:
+  description: What's next
+  pages:
+    - slug: page-slug
+      title: Display Title
+      type: basic          # basic, endpoint, changelog, custom_page
+    - title: External Link
+      type: link
+      url: https://example.com
+link:
+  url: https://example.com  # Redirect page to this URL
+  new_tab: true
+---
+```
+
+Only `title` is required. All other fields are optional — don't add fields you don't need.
+
+### API reference pages (`reference/`)
+
+Same fields as doc pages, plus:
+
+```yaml
+---
+title: Get a Pet
+excerpt: Fetch a specific pet by ID
+api:
+  file: oas.json           # Path to OAS file (relative to reference/)
+  operationId: getPet      # Matches operationId in the OAS spec
+  webhook: false           # Set true for webhook operations
+api_config: authentication # Special page type: "authentication", "getting-started", or "my-requests"
+recipes:                   # Related recipe slugs
+  - publish-all-docs-in-category
+---
+```
+
+Set `api` to `null` to detach a reference page from its API operation (makes it a plain page within `reference/`).
+
+### Recipe pages (`recipes/`)
+
+```yaml
+---
+title: Publish all Docs in Category          # Required
+description: Update each doc as published.   # Optional
+hidden: true
+recipe:                                       # Required
+  color: '#018FF4'                            # Hex color, required
+  icon: circle-play                           # Icon string, required
+---
+```
+
+### Custom pages (`custom_pages/`)
+
+```yaml
+---
+title: My Custom Page    # Required
+hidden: true
+fullscreen: true         # Renders page without sidebar/nav chrome
+metadata:
+  description: ...
+  keywords: ...
+  title: ...
+  image: ...
+---
+```
+
+Custom pages support markdown (`.md`) and HTML (`.html`). They cannot use `deprecated`.
+
+### Custom blocks (`custom_blocks/`)
+
+Markdown snippets (`.md`):
+```yaml
+---
+name: my-snippet         # Required
+---
+Content here...
+```
+
+React components (`.mdx`) — export a component and include a usage example:
+```yaml
+---
+name: MyComponent        # Required
+---
+```
+
+## Ordering with `_order.yaml`
+
+Every directory containing pages needs an `_order.yaml` to control display order.
+
+**Category ordering** — lists folder names (Title Case with spaces):
+```yaml
+# docs/_order.yaml (if it existed — currently categories display alphabetically without one)
+- Documentation
+- More Documentation
+```
+
+**Page ordering within a category** — lists page slugs (kebab-case, no `.md`):
+```yaml
+# docs/Documentation/_order.yaml
+- hello-world
+- parent-page
+- another-page
+```
+
+**Recipe ordering:**
+```yaml
+# recipes/_order.yaml
+- publish-all-docs-in-category
+```
+
+## Parent-child pages
+
+Create a folder named after the parent page slug, with `index.md` as the parent and additional `.md` files as children:
+
+```
+docs/Documentation/
+└── parent-page/
+    ├── index.md       # Parent page (title: "Parent Page")
+    └── child-page.md  # Child page nested underneath
+```
+
+## Linking between pages
+
+### Published URL structure
+
+On the published ReadMe site, pages have flat URL paths based on their content type:
+
+| Content type | Published URL |
+|---|---|
+| Doc pages (`docs/`) | `/docs/{slug}` |
+| API reference (`reference/`) | `/reference/{slug}` |
+| Recipes (`recipes/`) | `/recipes/{slug}` |
+| Custom pages (`custom_pages/`) | `/page/{slug}` |
+
+The slug comes from the filename (without `.md`). Category folders do **not** appear in published URLs — `docs/Getting Started/quickstart.md` becomes `/docs/quickstart`. Child pages nest under their parent: `docs/Category/parent-page/child-page.md` becomes `/docs/parent-page/child-page`.
+
+**Important:** Site URLs may include a prefix (e.g., `/lang-en/docs/slug`), so never use absolute paths when linking between pages. Use relative links instead.
+
+### Relative links (preferred)
+
+Always use relative links based on the published URL structure above (not the file structure in this repo). Do not include `.md` extensions in links.
+
+```markdown
+<!-- Link to a page in the same section -->
+[Link text](./other-page)
+
+<!-- Link from a doc page to a reference page -->
+[Link text](../reference/some-endpoint)
+
+<!-- Link from a child page to a sibling -->
+[Link text](./sibling-page)
+
+<!-- Link from a child page up to another doc -->
+[Link text](../other-page)
+
+<!-- HTML anchor tags also work with relative links -->
+<a href="./other-page">Link text</a>
+```
+
+### `doc:` protocol links
+
+ReadMe supports a special `doc:slug` protocol that resolves to doc pages regardless of URL prefix. This is convenient but only works in markdown links (not in `<a>` tags or component `href` attributes):
+
+```markdown
+[Link text](doc:hello-world)
+```
+
+**Use relative links as the default.** The `doc:` protocol is an acceptable alternative for markdown-only links to doc pages.
+
+## Markdown content conventions
+
+- Write in active voice, address the reader as "you"
+- Use sentence case for headings
+- Category folder names: Title Case with spaces (e.g., `Getting Started`, `Core Features`)
+- Page filenames: lowercase kebab-case (e.g., `quickstart.md`, `error-handling.md`)
+
+### MDX components
+
+These built-in components are available in markdown content:
+
+**Tabs** — for non-code tabbed content:
+```markdown
+<Tabs>
+  <Tab title="First Tab">
+    Content for tab 1
+  </Tab>
+  <Tab title="Second Tab">
+    Content for tab 2
+  </Tab>
+</Tabs>
+```
+
+**Tabbed code blocks** — place fenced code blocks back-to-back with NO blank lines between them:
+
+````markdown
+```javascript
+const pet = await sdk.getPet({ petId: 123 });
+```
+```python
+pet = sdk.get_pet(pet_id=123)
+```
+````
+
+**Accordion:**
+```markdown
+<Accordion title="Click to expand" icon="info">
+  Hidden content here
+</Accordion>
+```
+
+**Cards:**
+```markdown
+<Cards columns={3}>
+  <Card title="Getting Started" icon="rocket" href="./getting-started">
+    Quick intro to the platform
+  </Card>
+  <Card title="API Reference" icon="code" href="../reference/">
+    Explore the API
+  </Card>
+</Cards>
+```
+
+**Columns:**
+```markdown
+<Columns>
+  <Column>
+    Left side content
+  </Column>
+  <Column>
+    Right side content
+  </Column>
+</Columns>
+```
+
+Only these components are valid. Convert any other components (e.g., `<Callout>`, `<Note>`, `<Info>`, `<Steps>`) to plain markdown or blockquotes.
+
+### Recipe line highlighting
+
+Recipes can highlight specific code lines per language using HTML comments:
+
+```markdown
+<!-- node@L0-L4,L6 -->
+<!-- python@L2-L3,L9 -->
+```
+
+These comments go after a markdown heading and before the explanatory text for that step. They reference the code blocks at the top of the recipe.
+
+## API reference structure
+
+OAS (OpenAPI) spec files go in `reference/`. The directory structure maps to the API:
+
+```
+reference/
+├── oas.json                    # The OpenAPI spec
+└── Simple Pet API/             # Matches spec's info.title
+    ├── Pet/                    # Matches a tag name
+    │   ├── index.md            # Optional: landing page for this tag
+    │   └── getPet.md           # Endpoint page (filename = operationId)
+    └── Pets/
+        ├── index.md
+        └── randomPet.md
+```
+
+If you only need the auto-generated endpoint pages (no custom markdown), you can just have the OAS file with no subdirectories — ReadMe creates "virtual" categories from the spec's tags.
+
+Endpoint pages link to their OAS operation via frontmatter:
+```yaml
+api:
+  file: oas.json
+  operationId: getPet
+```
+
+You can also add **conceptual guide pages** inside `reference/` (authentication, error handling, pagination, etc.) by creating pages without an `api` frontmatter field, or by setting `api: null`.
+
+## Validation rules
+
+When attempting to validate the repo, these are the common issues to check for and how to fix them:
+
+- **frontmatter** — Invalid or unknown frontmatter properties. Unknown properties should either be removed or prefixed with `x-` (e.g., `category` → `x-category`). Typos are flagged with the closest valid property name.
+- **ordering** — Every file and subdirectory should be listed in its directory's `_order.yaml`. Slugs that YAML interprets as non-strings (numbers like `404`, booleans like `true`/`false`/`yes`/`no`) must be quoted (e.g., `- "404"`). Never remove quotes from existing entries.
+- **numbering** — Files ending in `-1`, `-2`, etc. where no base name exists should be renamed (e.g., `setup-1.md` → `setup.md`). These suffixes are holdovers from an old bug.
+- **duplicates** — Slugs must be unique across all `docs/` and `reference/` pages. Never rename files inside `ReadMeConfig/` — these have special internal names.
+- **oas-reference** — Reference pages with `api.file` frontmatter must point to a valid OAS file. The `api.operationId` must exist in the spec.
+- **oas-schema** — OAS files must be valid OpenAPI or Swagger specs. Error messages include line numbers and context.
+- **components** — MDX component tags (`<Name>`) must reference a built-in or custom block. Custom block `.md` snippets should use PascalCase filenames (e.g., `MySnippet.md` for `<MySnippet />`).
+- **recipes** — Must have code blocks at the top, then `# Heading` sections. Snippet references (`<!-- lang@lines -->`) must reference existing code blocks with valid line ranges.
+
+## Key rules when editing
+
+1. **Don't add frontmatter fields not in the schema.** Check `frontmatter.schema.json` if unsure.
+2. **Every directory with pages needs `_order.yaml`** to control ordering.
+3. **Category folders use Title Case with spaces.** Page files use kebab-case.
+4. **Don't modify auto-generated endpoint files** in `reference/` unless adding custom markdown to existing ones. You can add new conceptual pages alongside them.
+5. **Prefer more focused pages over fewer long ones.** Split distinct concepts into separate files.
+6. **Don't create changelog/release-notes content** — ReadMe handles that separately.

package/vendor/git-format/frontmatter.schema.json

@@ -0,0 +1,199 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "ReadMe frontmatter shapes",
+  "oneOf": [
+    {
+      "title": "Page",
+      "description": "This is the shape for files within the `docs/` directory.",
+      "$ref": "#/defs/filetype-page"
+    },
+    {
+      "title": "Custom Page",
+      "description": "This is the shape for files within the `custom_pages/` directory.",
+      "allOf": [
+        { "$ref": "#/defs/common-page" },
+        { "type": "object", "properties": { "fullscreen": { "type": ["boolean", "null"] } } }
+      ],
+      "required": ["title"],
+      "not": {
+        "type": "object",
+        "properties": { "deprecated": { "type": "boolean" } },
+        "description": "Custom pages have everything that a common page has except that they can't be deprecated."
+      }
+    },
+    {
+      "title": "API Reference",
+      "description": "This is the shape for files within the `reference/` directory.",
+      "allOf": [
+        { "$ref": "#/defs/filetype-page" },
+        {
+          "type": "object",
+          "properties": {
+            "api": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": {
+                    "file": { "type": "string" },
+                    "operationId": { "type": "string" },
+                    "webhook": { "type": ["boolean", "null"] }
+                  },
+                  "required": ["file", "operationId"]
+                },
+                { "type": "null" }
+              ],
+              "description": "Information about the API operation that this page is documenting. Setting this to `null` will detach it from the API operation and make it a standard page."
+            },
+            "api_config": {
+              "anyOf": [
+                { "type": "string", "enum": ["authentication", "getting-started", "my-requests"] },
+                { "type": "null" }
+              ],
+              "description": "Describes a Reference config page of a particular type."
+            },
+            "recipes": {
+              "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }],
+              "description": "A collection of recipes that are related to this API operation."
+            }
+          }
+        }
+      ]
+    },
+    {
+      "title": "Recipe",
+      "description": "This is the shape for files within the `recipes/` directory.",
+      "allOf": [
+        { "$ref": "#/defs/core" },
+        {
+          "type": "object",
+          "properties": {
+            "description": { "type": ["string", "null"] },
+            "recipe": {
+              "type": "object",
+              "properties": {
+                "color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" },
+                "icon": { "type": "string" }
+              },
+              "required": ["color", "icon"]
+            }
+          }
+        }
+      ],
+      "required": ["title", "recipe"]
+    },
+    {
+      "title": "Custom Block",
+      "description": "This is the shape for custom blocks in the `custom_blocks/` directory.",
+      "type": "object",
+      "properties": { "name": { "type": ["string", "null"] } },
+      "required": ["name"]
+    }
+  ],
+  "defs": {
+    "core": {
+      "title": "Core properties that are available on all file types.",
+      "type": "object",
+      "properties": { "hidden": { "type": ["boolean", "null"] }, "title": { "type": "string" } }
+    },
+    "metadata": {
+      "title": "Properties that control file metadata.",
+      "type": "object",
+      "properties": {
+        "description": { "type": ["string", "null"] },
+        "image": { "type": ["string", "null"] },
+        "keywords": { "anyOf": [{ "type": "array", "items": { "type": "string" } }, { "type": "null" }] },
+        "robots": { "anyOf": [{ "type": "string", "enum": ["index", "noindex"] }, { "type": "null" }] },
+        "title": { "type": ["string", "null"], "description": "This is the title that's used for SEO metadata." }
+      }
+    },
+    "common-page": {
+      "allOf": [
+        { "$ref": "#/defs/core" },
+        {
+          "type": "object",
+          "properties": {
+            "deprecated": { "type": ["boolean", "null"] },
+            "excerpt": { "type": ["string", "null"] },
+            "icon": { "type": ["string", "null"] },
+            "table_of_contents": { "type": ["boolean", "null"] },
+            "x-import": {
+              "type": ["string", "null"],
+              "description": "Set during the docs site import flow. This is a link to the external page that needs to be imported and signifies this page has not yet been imported. It is removed once the page content is imported."
+            },
+            "metadata": { "$ref": "#/defs/metadata" },
+            "next": {
+              "type": "object",
+              "properties": {
+                "description": { "type": ["string", "null"] },
+                "pages": {
+                  "anyOf": [
+                    {
+                      "type": "array",
+                      "items": {
+                        "anyOf": [
+                          {
+                            "type": "object",
+                            "properties": {
+                              "slug": { "type": "string" },
+                              "title": { "type": ["string", "null"] },
+                              "type": { "type": "string", "enum": ["basic", "endpoint", "changelog", "custom_page"] }
+                            },
+                            "description": "A page within the developer site. Does not support multiguides and is generally deprecated in favor of `type: page`."
+                          },
+                          {
+                            "type": "object",
+                            "properties": {
+                              "slug": { "type": "string" },
+                              "directory": {
+                                "type": "string",
+                                "pattern": "^[a-z0-9][a-z0-9_-]{0,29}$",
+                                "description": "The section directory of the page."
+                              },
+                              "title": { "type": ["string", "null"] },
+                              "type": { "type": "string", "const": "page" }
+                            },
+                            "description": "A page within the developer site. Multiguides compatible."
+                          },
+                          {
+                            "type": "object",
+                            "properties": {
+                              "title": { "type": ["string", "null"] },
+                              "type": { "type": "string", "const": "link" },
+                              "url": { "type": "string" }
+                            }
+                          }
+                        ]
+                      }
+                    },
+                    { "type": "null" }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      ]
+    },
+    "filetype-page": {
+      "allOf": [
+        { "$ref": "#/defs/common-page" },
+        {
+          "type": "object",
+          "properties": {
+            "link": {
+              "anyOf": [
+                {
+                  "type": "object",
+                  "properties": { "new_tab": { "type": ["boolean", "null"] }, "url": { "type": ["string", "null"] } }
+                },
+                { "type": "null" }
+              ],
+              "description": "Information about where this page should redirect to. Setting this to `null` will make the page a standard page."
+            }
+          }
+        }
+      ],
+      "required": ["title"]
+    }
+  }
+}