Manage the lifecycle of your documentation to ensure your users always see accurate, up-to-date information. With GitDocAI, you can control exactly when content goes live, collaborate on drafts, and maintain multiple versions of your documentation simultaneously.
stateDiagram-v2
[*] --> Draft
Draft --> In_Review : "Submit"
In_Review --> Published : "Approve & Publish"
Published --> Draft : "Edit / Unpublish"
Published --> Archived : "Deprecate"Content Statuses
Every page in your GitDocAI project goes through a specific lifecycle. Understanding these statuses helps you manage what your users can see.
| Status | Description | Visibility |
|---|---|---|
| Draft | Work in progress. The content is saved but not yet live. | Visible only to workspace members (Editors, Admins). |
| In Review | Content is finished and waiting for peer or admin approval. | Visible to workspace members. |
| Published | Live, official documentation. | Visible to your end-users. |
| Archived | Outdated or deprecated content. | Hidden from navigation, but accessible via direct URL if needed. |
You can share a secure preview link for pages in the Draft or In Review state. This is perfect for getting feedback from stakeholders who don't have a GitDocAI account.
Publishing Content
When you are ready to share your updates with the world, follow these steps to publish your draft.
- 1
Preview your changes
Before publishing, click the Preview button in the top right corner of the editor. This opens a staging view where you can verify formatting, test links, and ensure your Markdown renders correctly.
- 2
Submit for review (Optional)
If your workspace requires approvals, click Submit for Review. This notifies your team administrators that the page is ready for a final check.
- 3
Publish the page
Click the Publish button. You can choose to publish immediately or schedule the publication for a future date and time (ideal for coordinating with product releases).
Publishing a page immediately overwrites the live version. If you make a mistake, you can always revert to a previous commit in your connected Git repository.
Managing Documentation Versions
If your product has multiple major releases (e.g., v1.0, v2.0), you likely need to maintain separate documentation for each version. GitDocAI handles this seamlessly by tying versions directly to your Git repository branches or tags.
Creating a new version
In your connected Git repository, create a new branch or tag (for example,
release/v2.0).Navigate to your GitDocAI dashboard and go to Settings > Versions.
Click Add Version.
Select the Git branch or tag you just created from the dropdown menu.
Give the version a user-friendly name (e.g., "Version 2.0") and click Save.
By default, the newest version is not automatically set as the default version for your site. You must manually update the default version in your settings when you are ready to switch your users over.
Automating Publishing via API
If you prefer to trigger documentation updates programmatically (such as from a CI/CD pipeline), you can use the GitDocAI publishing API endpoints to manage your publishing jobs:
| Action | Method | Endpoint |
|---|---|---|
| Start a publish job | POST | /documentations/{documentation_id}/publish |
| Get publish job status | GET | /documentations/{documentation_id}/publish/status |
| Get latest publish | GET | /documentations/{documentation_id}/publish/latest |
| Get publish history | GET | /documentations/{documentation_id}/publish/history |
You can also manage your documentation structure programmatically. The API provides full support for creating, updating, reordering, and deleting sections within specific versions using the /v1/documentation/{organization_id}/{documentation_id}/version/{version_id}/section endpoints.
Frequently Asked Questions
How do I unpublish a page?
To remove a page from your live site, open the page in the editor, click the settings cog, and select Change Status to Draft. The page will instantly disappear from your live navigation but remain safe in your workspace.
Can I publish multiple pages at once?
Yes! Navigate to the Content Structure view, select the checkboxes next to the pages you want to update, and use the bulk action menu to click Publish Selected.
What happens to links when I archive a version?
When you archive a version, it is hidden from the version dropdown menu. However, existing direct links will still work to prevent breaking external bookmarks. A banner will automatically appear at the top of archived pages warning users that the content is outdated.
Next Steps
Now that your content is published and versioned, you might want to customize how it looks or ensure it ranks well on search engines.