{
  "openapi": "3.1.0",
  "info": {
    "title": "Jostraca content API",
    "summary": "The machine-readable surface of the Jostraca documentation site.",
    "description": "Jostraca is a code and project generator distributed as an npm package\nand a Go module. It is a library, not a hosted service, so there is no\nproduct API to call and this document does not pretend otherwise.\n\nWhat it describes is the content API this site serves to programs:\nevery page has a markdown twin, an index enumerates the corpus, a\nversion document states what the site runs, and errors come back as\nJSON rather than HTML.\n\nRead `/llms.txt` first: it is the smallest complete map of the site.\nTo use Jostraca itself, install the package — see `externalDocs`.",
    "version": "1.0.0",
    "license": {
      "name": "MIT",
      "identifier": "MIT"
    },
    "contact": {
      "name": "Jostraca issues",
      "url": "https://github.com/jostraca/jostraca/issues"
    }
  },
  "externalDocs": {
    "description": "The generator itself: both implementations, published as npm `jostraca` and Go module `github.com/jostraca/jostraca/go`.",
    "url": "https://github.com/jostraca/jostraca"
  },
  "servers": [
    {
      "url": "https://jostraca.org",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "index",
      "description": "Documents that enumerate the site for an agent."
    },
    {
      "name": "content",
      "description": "The documentation itself, as markdown."
    },
    {
      "name": "meta",
      "description": "Documents describing the site rather than the product."
    }
  ],
  "paths": {
    "/llms.txt": {
      "get": {
        "operationId": "getSiteIndex",
        "tags": [
          "index"
        ],
        "summary": "The site index, written for agents",
        "description": "A short markdown index of every documentation page and how-to guide, each linked to its markdown twin, plus when to reach for Jostraca and where the package lives. Start here.",
        "responses": {
          "200": {
            "description": "The index.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/llms-full.txt": {
      "get": {
        "operationId": "getFullCorpus",
        "tags": [
          "index"
        ],
        "summary": "Every page, concatenated",
        "description": "The entire documentation corpus in one plain-text document, for a caller that would rather make one request than follow the index. Large; prefer `getSiteIndex` plus `getPageMarkdown` when you know what you need.",
        "responses": {
          "200": {
            "description": "The whole corpus.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/versions.json": {
      "get": {
        "operationId": "getVersions",
        "tags": [
          "meta"
        ],
        "summary": "What this site runs and what it documents",
        "description": "The `jostraca` version this site executes its examples against, the size of each surface, and the markdown convention. The running version and the documented version are stated separately because the synced documentation can be ahead of the published package.",
        "responses": {
          "200": {
            "description": "The version document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Versions"
                }
              }
            }
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "operationId": "getOpenApiSpec",
        "tags": [
          "meta"
        ],
        "summary": "This document",
        "description": "The OpenAPI 3.1 description of this site's machine surface.",
        "responses": {
          "200": {
            "description": "The specification.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/robots.txt": {
      "get": {
        "operationId": "getRobotsTxt",
        "tags": [
          "meta"
        ],
        "summary": "Crawler policy",
        "description": "The robots policy for this site, which also names the sitemap. Nothing here is disallowed to well-behaved agents.",
        "responses": {
          "200": {
            "description": "The policy.",
            "content": {
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/sitemap-index.xml": {
      "get": {
        "operationId": "getSitemapIndex",
        "tags": [
          "meta"
        ],
        "summary": "Sitemap index",
        "description": "The XML sitemap index for every page on this site.",
        "responses": {
          "200": {
            "description": "The sitemap index.",
            "content": {
              "application/xml": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/{page}.md": {
      "get": {
        "operationId": "getPageMarkdown",
        "tags": [
          "content"
        ],
        "summary": "One page, as markdown",
        "description": "The markdown twin of a page. Identical bytes to sending `Accept: text/markdown` to the page's own URL, and the form to prefer when you can build the path yourself. Answers cross-origin.",
        "parameters": [
          {
            "name": "page",
            "in": "path",
            "required": true,
            "description": "The page path without its leading slash and without the `.md` suffix, for example `docs/tutorial`. The enumeration is the complete set of pages that have a twin.",
            "schema": {
              "type": "string",
              "enum": [
                "index",
                "why",
                "about",
                "legacy",
                "contact",
                "privacy",
                "docs",
                "docs/tutorial",
                "docs/reference-components",
                "docs/reference-options",
                "docs/reference-utilities",
                "docs/reference-go",
                "docs/explanation",
                "how-to",
                "how-to/branch-and-loop",
                "how-to/call-jostraca-from-go",
                "how-to/copy-a-directory",
                "how-to/edit-a-file-you-did-not-generate",
                "how-to/extract-part-of-a-template",
                "how-to/fill-a-template-slot",
                "how-to/generate-in-memory",
                "how-to/indent-generated-content",
                "how-to/insert-model-values",
                "how-to/keep-a-backup-when-overwriting",
                "how-to/let-a-user-take-a-file-over",
                "how-to/make-a-reusable-component",
                "how-to/merge-generator-and-user-edits",
                "how-to/offer-a-new-version",
                "how-to/pass-data-to-children",
                "how-to/preview-a-run",
                "how-to/repeat-content-in-one-file",
                "how-to/replace-markers-in-a-template",
                "how-to/report-what-a-run-did",
                "how-to/set-file-permissions",
                "how-to/show-a-diff-instead-of-writing",
                "how-to/skip-files-when-copying",
                "how-to/test-a-generator",
                "how-to/write-a-file-tree"
              ]
            },
            "examples": {
              "tutorial": {
                "value": "docs/tutorial",
                "summary": "The tutorial"
              },
              "components": {
                "value": "docs/reference-components",
                "summary": "Every component and its props"
              }
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page, as markdown.",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such page, in whichever representation the caller asked for: JSON under `Accept: application/json`, the designed HTML page under `Accept: text/html`, and markdown otherwise — including for a caller that named nothing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "/{page}": {
      "get": {
        "operationId": "getPage",
        "tags": [
          "content"
        ],
        "summary": "One page, in the representation you ask for",
        "description": "A page URL. What comes back depends on `Accept`: `text/markdown` returns the same bytes as the `.md` twin with `Vary: Accept`, `application/json` turns an error into the structured shape, and anything else returns the HTML page. A caller that names nothing gets markdown for errors, because that is readable either way.",
        "parameters": [
          {
            "name": "page",
            "in": "path",
            "required": true,
            "description": "The page path without its leading slash, for example `docs/tutorial`. The home page is `/` itself and is not in this enumeration.",
            "schema": {
              "type": "string",
              "enum": [
                "why",
                "about",
                "legacy",
                "contact",
                "privacy",
                "docs",
                "docs/tutorial",
                "docs/reference-components",
                "docs/reference-options",
                "docs/reference-utilities",
                "docs/reference-go",
                "docs/explanation",
                "how-to",
                "how-to/branch-and-loop",
                "how-to/call-jostraca-from-go",
                "how-to/copy-a-directory",
                "how-to/edit-a-file-you-did-not-generate",
                "how-to/extract-part-of-a-template",
                "how-to/fill-a-template-slot",
                "how-to/generate-in-memory",
                "how-to/indent-generated-content",
                "how-to/insert-model-values",
                "how-to/keep-a-backup-when-overwriting",
                "how-to/let-a-user-take-a-file-over",
                "how-to/make-a-reusable-component",
                "how-to/merge-generator-and-user-edits",
                "how-to/offer-a-new-version",
                "how-to/pass-data-to-children",
                "how-to/preview-a-run",
                "how-to/repeat-content-in-one-file",
                "how-to/replace-markers-in-a-template",
                "how-to/report-what-a-run-did",
                "how-to/set-file-permissions",
                "how-to/show-a-diff-instead-of-writing",
                "how-to/skip-files-when-copying",
                "how-to/test-a-generator",
                "how-to/write-a-file-tree"
              ]
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "The representation you want back.",
            "schema": {
              "type": "string",
              "enum": [
                "text/markdown",
                "text/html",
                "application/json"
              ],
              "default": "text/html"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The page.",
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No such page, in whichever representation the caller asked for: JSON under `Accept: application/json`, the designed HTML page under `Accept: text/html`, and markdown otherwise — including for a caller that named nothing.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "description": "The structured error every machine-readable route returns. Also returned by any page URL requested with `Accept: application/json`.",
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message"
            ],
            "properties": {
              "status": {
                "type": "integer",
                "description": "HTTP status code.",
                "examples": [
                  404
                ]
              },
              "code": {
                "type": "string",
                "description": "Stable, machine-comparable error code.",
                "examples": [
                  "not_found"
                ]
              },
              "message": {
                "type": "string",
                "description": "One-line human-readable summary."
              },
              "hint": {
                "type": "string",
                "description": "How to recover, naming the routes that do exist."
              },
              "documentation": {
                "type": "string",
                "format": "uri",
                "description": "Where the documentation set starts."
              },
              "resources": {
                "type": "object",
                "additionalProperties": {
                  "type": "string",
                  "format": "uri"
                },
                "description": "The site's entry points, keyed by name."
              }
            }
          }
        }
      },
      "Versions": {
        "type": "object",
        "required": [
          "generator",
          "surfaces"
        ],
        "description": "What this site runs, and how big each surface is.",
        "properties": {
          "$comment": {
            "type": "string"
          },
          "generator": {
            "type": "object",
            "required": [
              "npm",
              "version"
            ],
            "properties": {
              "npm": {
                "type": "string",
                "description": "The npm package name.",
                "examples": [
                  "jostraca"
                ]
              },
              "version": {
                "type": "string",
                "description": "The exact version this site runs its examples against."
              },
              "go_module": {
                "type": "string",
                "description": "The Go module path of the port."
              },
              "source": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "surfaces": {
            "type": "object",
            "properties": {
              "docs": {
                "$ref": "#/components/schemas/SurfaceCount"
              },
              "howto": {
                "$ref": "#/components/schemas/SurfaceCount"
              },
              "llms": {
                "type": "array",
                "items": {
                  "type": "string",
                  "format": "uri"
                },
                "description": "The index documents."
              }
            }
          },
          "markdown": {
            "type": "string",
            "description": "The markdown-twin convention, in one line."
          }
        }
      },
      "SurfaceCount": {
        "type": "object",
        "required": [
          "count",
          "url"
        ],
        "properties": {
          "count": {
            "type": "integer",
            "description": "How many pages the surface holds."
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    }
  },
  "x-machine-surface": {
    "startHere": "https://jostraca.org/llms.txt",
    "markdownTwins": {
      "convention": "Append `.md` to any page path, or send `Accept: text/markdown` to the page URL.",
      "count": 38
    },
    "source": "https://github.com/jostraca/web"
  }
}