Documentation files

You can write Markdown documentation at three levels: API, resource, and operation. These files are committed with the project, edited in the app's doc editor (with live preview) or by hand, and rendered with placeholders that pull live data from the spec.

Locations

Level	Path
API (main page)	`apis/<api>/docs/index.md`
API (extra pages)	`apis/<api>/docs/<name>.md`
Resource	`apis/<api>/resources/<resource>/docs/index.md`
Operation	`apis/<api>/resources/<resource>/docs/<operationName>.md`

The operation file's name matches the operation name (get.md documents Pet.get).

Frontmatter

YAML frontmatter, parsed with gray-matter. Recognized fields:

---
title: Get a pet
order: 2
visibility: public
tags: [pet, lookup]
---

Field	Description
`title`	Display title; overrides the derived one.
`order`	Sort order among sibling docs.
`visibility`	`public` or `private`.
`tags`	Free-form tags (metadata).

Placeholders

Inside the body, {{placeholder}} tokens are replaced at render time with data derived from the effective spec. Each placeholder is valid at a specific level (scope):

Placeholder	Scope	Renders
`{{api:title}}`	API	The API title.
`{{api:resources}}`	API	A linked list of the API's resources.
`{{resource:title}}`	Resource	The resource title.
`{{resource:operations}}`	Resource	A linked list of the resource's operations.
`{{operation:title}}`	Operation	The operation title.
`{{operation:parameters}}`	Operation	The operation's parameters.
`{{operation:requestExample}}`	Operation	First request-body example, fenced as JSON.
`{{operation:responseExample}}`	Operation	First response example, fenced as JSON.
`{{operation:responses}}`	Operation	The documented responses.
`{{operation:security}}`	Operation	The operation's security requirements.

Example operation doc:

---
title: Get a pet
---

# {{operation:title}}

Returns a single pet by its ID.

## Parameters
{{operation:parameters}}

## Example
{{operation:requestExample}}

A placeholder with no data (e.g. an operation with no request body) renders a small placeholder line such as _No request example._.

Cross-references

Link between docs with the apicraft:// scheme; each consumer translates it to its own navigation (app panel, or relative HTML at export):

apicraft://api/<apiSlug>
apicraft://api/<apiSlug>/resource/<resourceSlug>
apicraft://api/<apiSlug>/resource/<resourceSlug>/operation/<operationName>

Coming soonExport-time link translation

The apicraft:// scheme is defined and resolved in the app. Translating it to relative HTML links at documentation-export time isn't implemented yet.