Publishing your documentation ensures that your latest updates, structural changes, and new versions are live and accessible to your users. Whether you prefer to manually trigger updates or fully automate your releases through a CI/CD pipeline, GitDocAI provides a robust set of tools and APIs to support your ideal publishing workflow.

This guide walks you through the publishing lifecycle, managing versions, and setting up automated workflows.

The Publishing Lifecycle

Before diving into the setup, it is helpful to understand how content moves from draft to live. A typical publishing workflow involves managing your versions, structuring your sections, and finally triggering a publish job.

flowchart TD
    A[Manage Versions] --> B[Organize Sections]
    B --> C[Trigger Publish Job]
    C --> D{Check Status}
    D -->|In Progress| D
    D -->|Success| E[Live Documentation]
    D -->|Failed| F[Review Publish History]

Setting up a Manual Workflow

If you prefer to control exactly when your documentation goes live, you can manually manage your workflow using the GitDocAI API.

1. 1

   Prepare your version

   Ensure the version you want to publish is up to date. You can create a new version or update an existing one using the Version management endpoints.

2. 2

   Organize your sections

   Structure your content by creating, updating, or reordering sections. A well-organized table of contents is crucial for readability.

3. 3

   Start the publish job

   Trigger the publishing process by calling the publish endpoint for your specific documentation ID.

   curl -X POST https://api.gitdocai.com/documentations/{documentation_id}/publish 
     -H "Authorization: Bearer YOUR_API_TOKEN"

4. 4

   Monitor the status

   Publishing may take a few moments depending on the size of your documentation. You can poll the status endpoint to check if the job is complete.

Automating with CI/CD

For teams that want documentation to stay in sync with their codebase, automating the publish workflow is the best approach. You can add a simple script to your GitHub Actions, GitLab CI, or other deployment pipelines to trigger a publish job automatically when changes are merged.

# Example GitHub Action snippet
name: Publish Documentation
on:
  push:
    branches:
      - main
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger GitDocAI Publish
        run: |
          curl -X POST https://api.gitdocai.com/documentations/${{ secrets.DOC_ID }}/publish 
          -H "Authorization: Bearer ${{ secrets.GITDOCAI_TOKEN }}"

Managing Versions in Your Workflow

A robust publishing workflow often involves maintaining multiple versions of your documentation (e.g., v1.0, v2.0, beta). GitDocAI allows you to control the lifecycle and visibility of these versions.

Monitoring and Troubleshooting

Sometimes publish jobs fail due to formatting errors, missing source files, or network issues. GitDocAI keeps a detailed log of your publishing activity.

Next Steps

Ready to dive deeper into the APIs that power these workflows? Check out the detailed endpoint references: