Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Publish to a docs site someone else operates

When another team or a provider runs the OpenD server, connecting your docs repository takes a few details and one webhook.

About this task

On a managed site you are usually a staff reader yourself, and do all of this in the admin console at /admin (Run your site from the admin console):

  • GitHub says Managed by your hosting provider. Its Connect GitHub button installs the provider's GitHub App on the repositories you choose; there is no app to create and no key to handle.
  • Installed on one repository, that is all: the site finds opend.config.yaml, connects the repository and builds it, and the site block of the file sets up access, the version picker and release lines (Set the site up from opend.config.yaml). With several, Docs source lists them: pick yours and the first build starts. Pushes reach the site through the provider, already verified.
  • Custom domain serves the site at your own domain: add the DNS records it lists, and it switches over once they have propagated (Serve your site at your own domain).
  • Readers and staff sign in with Sign in with GitHub, which goes through the provider's sign-in service; the web editor signs authors in the same way.

Otherwise, ask the operator to do these steps for you.

  1. Send the operator your repository details.
    • The repository's full name and clone URL, such as acme/docs and https://github.com/acme/docs.git.
    • The branches and tags that publish, such as main and v*.
    • The folder inside the repository that holds opend.config.yaml, if it is not the root.
    • Whether the repository is private. Private repositories need the operator's GitHub App installed on them.
  2. Add the webhook the operator gives you, or install their GitHub App.

    The webhook sends push events, as JSON, to the site's /webhooks/github with a secret the operator shares with you.

  3. Tell the operator which organizations should read the docs, with their products, features and release, and who their readers are.
  4. Push.

    With the GitHub App installed, the commit shows an opend/build status: pending, then Published 0.1, or a failure naming the first errors.

Results

A push that fails validation never goes live; the previous version stays up. Run opend validate locally or in CI to catch problems first, and ask the operator of your docs site for the full list of a failed build's diagnostics.

If the operator also runs the web editor, ask them to add the authors who do not use Git. See Edit docs in the browser.