Custom Content

Add practical Markdown guides beside generated API documentation.

Generated API docs are the main event.

Sometimes we also need the stuff that lives around the API contract, things like:

onboarding
authentication, tokens and security
security guidance
error handling
SDK notes
webhooks
guidance
FAQs, and changelogs

printing press can render those pages from Markdown files that live next to your OpenAPI document.

No page config, No docs manifest.

Just conventional Markdown files.

How discovery works

Put known Markdown files beside the source OpenAPI file:

service/
  openapi.yaml
  about.md
  quickstart.md
  auth.md

Or place them in a sibling docs/ directory:

service/
  openapi.yaml
  docs/
    guide.md
    security.md
    faq.md

printing press checks both locations and renders the files that exist.

If the same page exists in both places, the file beside the OpenAPI document wins. The docs/ copy is ignored.

Missing conventional pages are ignored silently.

Conventional pages

These are the page names printing press understands:

File	Default output
`about.md`	`about.html`
`quickstart.md`	`quickstart.html`
`guide.md`	`guide.html`
`auth.md`	`auth.html`
`security.md`	`security.html`
`errors.md`	`errors.html`
`webhooks.md`	`webhooks-guide.html`
`sdks.md`	`sdks.html`
`faq.md`	`faq.html`
`changelog.md`	`changelog.html`

webhooks.md is a guide page. It does not replace the generated OpenAPI webhooks section.

That is why its default title is Webhooks Guide, and its default output is webhooks-guide.html.

Front matter

Front matter is optional, but it is the clean way to control labels, slugs, and ordering.

---
title: API Development Guide
label: Development
slug: guides/api-development
order: 30
description: How to work on the API contract and service code in parallel.
hidden: false
---

# API Development Guide

Useful guidance goes here.

Supported fields:

Field	What it controls
`title`	Page heading and browser title.
`label`	Sidebar and guides index label.
`slug`	Output path without `.html`. Nested slugs are supported.
`order`	Sort position in the Guides nav.
`description`	Short page summary.
`hidden`	Render the page, but remove it from navigation.

When front matter is missing, printing press uses filename defaults.

The default sort order is:

about
quickstart
guide
auth
security
errors
webhooks
sdks
faq
changelog

order can override that without adding any config.

Visible custom pages appear in the main sidebar under Guides.

They sit near the top of the docs:

API Overview
Diagnostics, when enabled
Operations
Models
Webhooks

about.md is an additional guide page. It does not replace the generated API overview.

hidden: true pages are still rendered and reachable by direct URL, but they do not appear in the sidebar or guides index.

Links and assets

Links between discovered pages are rewritten from Markdown files to generated HTML.

[Auth](auth.md)
[Setup](docs/guide.md#install)

becomes:

auth.html
guide.html#install

If a page uses a nested slug, links point to the final nested output.

Local images are copied into the generated site:

![Auth flow](images/auth-flow.svg)

becomes a published asset under:

assets/docs/<page-slug>/<asset-name>

Supported image types are:

.png
.jpg
.jpeg
.gif
.webp
.svg

Images are capped at 5 MB each.

Partials

Reusable Markdown fragments can live in _partials/.

service/
  openapi.yaml
  about.md
  _partials/
    support.md

Include them from a custom page:

{{< partial "support.md" >}}

Partials can also live under docs/_partials/. If the same partial exists in both places, the root _partials/ copy wins.

Partials are only expanded inside custom Markdown pages.

Generated output

Custom content is rendered as HTML pages in the same generated site.

When visible pages exist, printing press also writes:

guides.html

That page is the generated index for the Guides section.

Custom content does not change the generated OpenAPI operation, model, webhook, or agent output. The LLM files remain focused on the API contract.