Skip to content

Push to GitHub

Sync your published documentation to a GitHub repository as Markdown files. This is useful for maintaining docs alongside code, enabling pull request workflows, or publishing through GitHub Pages or other static site generators.

Before you begin

  • You need a GitHub repository where the documentation will be pushed.

  • You need a GitHub personal access token with repo scope.

  • You need at least one publication target configured in your map.

Configure GitHub sync

  1. Go to Settings in the sidebar.

  2. Open the GitHub Sync tab.

  3. Enter the repository in owner/repo format — e.g., acme/docs.

  4. Enter the branch name — e.g., main or docs.

  5. Enter a path prefix — e.g., docs/ to place files in a subdirectory.

  6. Add a GitHub personal access token with repo scope.

  7. Select the publication target whose content should be synced.

Store your GitHub personal access token securely. Anyone with access to your Topicary project settings can see the configured repository and branch, though the token itself is masked after entry. Use a fine-grained personal access token scoped to only the target repository when possible.

Test the connection

Click Test Connection to verify that Topicary can access the repository with the provided token.

Push content

  1. Click Push to GitHub.

  2. Topicary resolves the content through the publishing pipeline, converts topics to Markdown, and commits them to the repository.

  3. The last sync status shows the timestamp, commit SHA, and number of files written.

Example repository structure

After pushing a map with a docs/ path prefix, your repository might look like this:

acme/docs
├── docs/
│   ├── getting-started.md
│   ├── configuration/
│   │   ├── basic-setup.md
│   │   └── advanced-options.md
│   ├── guides/
│   │   ├── user-guide.md
│   │   └── admin-guide.md
│   └── reference/
│       └── api-reference.md
├── src/
│   └── ...
└── README.md

What gets pushed

  • One Markdown file per topic in the map

  • Files placed under the configured path prefix

  • Folder hierarchy matching the map structure

  • Content resolved through the full publishing pipeline (components expanded, conditions filtered, variables substituted)

Updating

Each push creates a new commit. Changed files are updated, new topics are added, and removed topics are deleted from the repository.

Each push replaces all files under the configured path prefix. Any manual edits made directly in the GitHub repository under that path will be overwritten on the next push. Treat the Topicary-managed path as a one-way sync destination.

See also

Was this page helpful?