GitHub Sync

With DeveloperHub you can have two-way sync set up with GitHub. This enables you to:-

• Write your docs in DeveloperHub and have a permanent export in GitHub.
• Update your docs in GitHub if your team prefers using their local text editors to write docs, which would reflect to DeveloperHub on push.
• Enable readers to edit the docs from GitHub and even use GitHub's comment system.
• Do some fancy GitHub stuff:
  • Set up a pull request review system.
  • Keep drafted docs in a branch.
  • Use GitHub actions to modify or lint docs before pushing.

Setting up GitHub Sync

The set up is needed from both GitHub side and DeveloperHub side. Follow the steps:

• First of all, ensure that you have created the repository for syncing and that it has at least one commit (so a branch would be created). Your initial commit could be adding a README file.
• From the left sidebar, open Project Settings
• Under Integrations, click Connect next to GitHub.
• Complete the authorisation on GitHub and give access to the repositories with which you wish to sync.

• You would be taken back to DeveloperHub to set up the integration.
• For the current project you are on, select the repository to sync with.
• Select the branch to sync with.
• If you wish for the docs to be synced under a different path (not root), enter it under base path.
• If you wish for the readers to see "Edit on GitHub" on every page, check "Allow readers to suggest edits on GitHub".
• Click Save.

On clicking Save, the initial sync process would start where all the files would be synced from DeveloperHub to GitHub. This could take minutes.

What Gets Synced?

All pages are synced excluding pages that are still in draft mode and have not been published before.

Exactly, files would be synced to GitHub whenever a:

• Published page content is updated (regardless if page is listed or not),
• Page's settings are changed,
• Page is deleted,
• Documentation is created,
• Documentation's settings are changed,
• Documentation is deleted,
• Version is created,
• Version's settings are changed,
• Version is deleted,
• Version is imported (using Project Import),

Whenever a file is created or updated on GitHub, the corresponding contents or settings would be updated on DeveloperHub.

File Formats

The files synced on GitHub are of two types:

• Contents: Such as page contents, formatted in Markdoc.
• Settings: Such as documentation settings, formatted in YAML.

File Structure

In the repository the files would be structured (from the basepath) as such:

• Folder for each version having the version slug as its name.
  • settings.yaml file containing the version settings.
  • Folder for each documentation section having the documentation slug as its name.
    • settings.yaml file containing the documentation settings.
    • File for each parent page having the page slug as its name with a md extension.
    • Folder for each parent page that has child pages, having the page slug as its name.
      • File for each child page having the page slug as its name with a md extension.

For example:

.

├── README.md

├── v1.0

│   ├── docs

│   │   ├── getting-started.md

│   │   ├── check-api.md

│   │   └── settings.yaml

│   └── settings.yaml

└── v1.02

    ├── settings.yaml

    └── support-center

        ├── activity-log.md

        ├── ai-features.md

        ├── ai-summarisation.md

        ├── api-references

        │   ├── api-reference-faq.md

        │   ├── api-reference-settings.md

        │   ├── code-generation.md

        │   └── openapi-extensions.md

        ├── api-references.md

        ├── hosting

        │   ├── configure-dns.md

        │   ├── server-headers.md

        │   ├── url-redirects.md

        │   └── using-custom-domain.md

        ├── hosting.md

        └── writing-documentation.md

GitHub Sync in Beta

GitHub sync is a work-in-progress. At the moment, the following is not possible:

• Creating new documentation sections or versions from GitHub.
• Ordering pages, documentation sections or version from GitHub.
• API references are not synced yet.
• Synced blocks are not synced yet.
• Project settings are not synced yet.

For any requirements, please contact us.

Uninstalling GitHub Sync

To uninstall GitHub sync, you should remove the application DeveloperHub - Sync from your GitHub application settings. Depending on the installation, it could be under your personal GitHub application settings or under the organisation GitHub application settings. Once the application is removed, the GitHub connection would be freed from DeveloperHub's side automatically.