Skip to main content

Publish Generated Docs Anywhere With docs generate Hooks

· 4 min read
Erik Osterman
Founder @ Cloud Posse

Generating a README is the easy half. The harder half is getting it where people actually read it. A common request is to keep the README and docs in the repository as the source of truth, and publish a copy to Confluence for the people who live there. Others want a documentation portal or a bucket behind a static site. Most teams end up with a shell script or a CI job that runs after the generator, has to know where the output landed, and quietly drifts out of sync with the generator it follows.

Documentation generation in Atmos now has lifecycle hooks, so the publishing step lives right next to the generator it belongs to.

The Problem​

Once a document is generated, something has to move it. In practice that something is glue:

  • A wrapper script that calls the generator and then calls curl, and has to be kept in sync with the generator's output path.
  • A CI step that assumes the generator already ran, so running the same thing locally means remembering two commands.
  • No clean way to say "never publish if generation failed" or "post a note even when it did."
  • No way for a platform team to require a publishing or review step for every generated document without editing every repository's scripts.

The Fix​

Hooks can now run before and after atmos docs generate. You declare them under the generator in atmos.yaml, using the same hook kinds you already use around Terraform and other component operations, so a step you run in a workflow works here unchanged.

Two new events, before.docs.generate and after.docs.generate, mark the edges. A before-hook that fails stops the command before any file is written. An after-hook runs once the file exists, and its when: setting decides whether it runs on success, on failure, or both. Steps receive the document type, the output path, and the base directory, so a hook never has to parse configuration to find the file it is supposed to publish.

Governing policies reach documentation generation too. A rule with on: operation and action: hooks can require a hook for a specific generator, or block generation on the before-event, exactly as it does for component operations.

How to Use It​

Publishing to Confluence, or any wiki with a REST API, is a generic HTTP request. This example updates a Confluence page after the README is generated:

docs:
generate:
readme:
input:
- "./README.yaml"
template: "./README.md.gotmpl"
output: "./README.md"
hooks:
publish-wiki:
kind: step
type: http
events: [after.docs.generate]
when: success
with:
url: "https://example.atlassian.net/wiki/rest/api/content/123456"
method: PUT
headers:
Authorization: "Bearer {{ .env.WIKI_TOKEN }}"
Content-Type: application/json
body: '{"id": "123456", "type": "page", "title": "README", "version": {"number": 2}, "body": {"storage": {"value": "<p>Generated by Atmos</p>", "representation": "storage"}}}'

Run it the way you always have:

atmos docs generate readme

Confluence expects the next version number of the page and content in its storage format, so a real publish usually converts the generated file first. A command hook that runs a small script reading the output path does that cleanly. Use --skip-hooks to generate without publishing, for example while iterating on a template. Atmos has nothing Confluence-specific built in: any service with an HTTP API, or any command you can run, can be a destination.

See atmos docs generate for ordering, failure handling, and the full list of values hooks receive, and the hooks reference for the hook kinds you can use.

Get Involved​

If you publish generated documentation somewhere and a hook doesn't cover your case, open an issue on GitHub and tell us what the hook needed to know.