How to generate a draft docs site

How-to guide

Add a DocsGen or OpenAPI source and generate a draft. Approve is a separate step.

Goal

Generate a draft documentation package from a GitHub repository or an API description, then leave it in Draft reviews until you Approve.

Conditions

  • You are a workspace owner or admin.
  • Public owner/name needs no GitHub login. Private code needs Connect GitHub.

Procedure

  1. Open Generate.
  2. If you want any public repo, type owner/name.
  3. If you want OpenAPI, add an OpenAPI source with a title and API description.
  4. Set the target site (existing or new, within plan quota).
  5. Click Generate draft package.
  6. Open Review. Preview the draft. Click Approve only when you intend the live host to serve it.

Verification

  • Draft reviews shows a pending row.
  • The live host has not changed until Approve succeeds.
  • Generated pages are one Diátaxis type each: tutorial, how-to, reference, or explanation. There is no mixed Overview page.

Failures

  • Generate disabled: no site or no origin.
  • Approve rejected (`draft_not_reader_servable`): the draft is incomplete. Do not force live.
  • 401/403 on a public remote: the platform retries without a token. If it still fails, the slug is wrong or the repo is not public.
Warning
Approve is the only promote. Generate never flips the public pointer. *(see Explanation: About Generate then Approve)*

How to connect a source is the index path, not go-live.