Framework guides

Markline doesn't ask you to describe your API twice. If your backend already produces an OpenAPI 3.0 or 3.1 document — and most do — that document is your reference. These guides cover the last mile: getting the document onto disk at build time, and annotating it so the generated site reads the way you'd write it by hand.

What each guide covers

Every guide walks the same six steps, so you can skim across frameworks:

1. Emit the document into api/openapi.json as a build step.
2. Tags become resources — including nested store/orders tags.
3. Order the sidebar with x-nav-order.
4. Document events with x-events.
5. Replace generated code samples with x-codeSamples.
6. Gotchas — the framework-specific traps.

The contract

The whole surface is four OpenAPI extensions plus your tags. Nothing here is Markline-specific plumbing: they're plain JSON keys on a standard document, so they survive $ref bundling, spec linting, and every other tool in the chain.

Pick your framework

Not listed?

You don't need a guide. Markline reads a standard document, so any generator works — Django REST with drf-spectacular, Laravel, Rails with rswag, ASP.NET with Swashbuckle, Go with huma or swaggo, or a hand-written YAML file.

The only thing a guide really buys you is the idiomatic way to attach an x- key in that framework. If yours has no clean hook, post-process the emitted document instead — the extensions are just JSON:

// scripts/annotate-spec.mjs — run after your generator, before `markline build`
import { readFileSync, writeFileSync } from "node:fs";
 
const spec = JSON.parse(readFileSync("api/openapi.json", "utf8"));
 
const order = {
  createSession: 1,
  endSession: 2,
};
 
for (const item of Object.values(spec.paths)) {
  for (const op of Object.values(item)) {
    const n = order[op.operationId];
    if (n !== undefined) op["x-nav-order"] = n;
  }
}
 
writeFileSync("api/openapi.json", JSON.stringify(spec, null, 2));