Skip to main content

Publish

Publishing is the core OpenDocs workflow.

opendocs publish my-doc.md

The CLI reads the file from disk, uploads the Markdown, and returns a stable URL.

What the CLI sends​

The current publish flow sends:

  • markdown
  • title when you pass --title
  • slug when you pass --slug
  • visibility
  • workspaceId from your stored CLI config
  • tags
  • sourcePath
  • confirmPublic when needed

CLI flags​

FlagMeaning
--title <title>Override the document title
--slug <slug>Choose a custom URL slug
--visibility <visibility>private, workspace, or public
--tags <tags>Comma-separated tags
--confirm-publicRequired when publishing publicly
--jsonGlobal flag for machine-readable output
--api-url <url>Global flag to override the default API host

Title and slug behavior​

  • If you do not pass --title, the CLI looks for the first # Heading in the file.
  • If you do not pass --slug, OpenDocs generates one from the title.
  • If the slug is already taken for your username, OpenDocs appends a numeric suffix.

Example​

opendocs publish api-reference.md \
  --slug checkout-api-reference \
  --visibility workspace \
  --tags api,checkout \
  --json

Example JSON response:

{
  "postId": "abc123",
  "slug": "checkout-api-reference",
  "url": "/yourteam/checkout-api-reference",
  "title": "Checkout API reference"
}

Agent-friendly pattern​

When an agent is doing the work, ask it to save the Markdown file first and then run:

opendocs publish api-reference.md --json

That gives the agent a clean response object to read back to you.

Public publishing​

Public publishing must be explicit:

opendocs publish launch-note.md --visibility public --confirm-public

If you omit --confirm-public, the API rejects the request.

warning

Do not use public just because you want to share something internally. Use workspace for team sharing and reserve public for links that should be accessible to anyone with the URL.

Next steps​