Connect GitHub or GitLab
Git Sync keeps a knowledge base and a folder of Markdown files in GitHub or GitLab in step. Write in your editor and push, and the docs publish in WordPress. Edit a doc in WordPress and click Update, and the change goes back to the repository.
This guide connects your first repository. It takes about five minutes.
What you need
- A GitHub or GitLab repository (gitlab.com or your own self-managed GitLab)
- An access token that can read and write the repository's contents
- A folder for your docs, such as
docs. It can be empty: docs you publish in WordPress are written there.
Create an access token
Create a fine-grained token for the repository with Contents: Read and write.
Add Pull requests: Read and write if you want changes sent as pull requests.
Create a project or personal access token with the api scope.
The account needs the Developer role or higher on the project.
Connect the repository
Open Git Sync
In WordPress, go to PinkDocs → Git Sync. Settings apply to the knowledge base selected in the PinkDocs header.
Enter the repository
Choose GitHub or GitLab, and enter your GitLab address if it's self-managed. Paste the repository as owner/name or its full URL, then set the Branch (leave it empty for the default branch) and the Docs folder.
Paste the token
Paste the token and click Save and connect. PinkDocs checks the connection and tells you how many Markdown files it found. The token is stored encrypted.
Preview the first sync
Click Preview changes to see exactly what the first sync would create, update or push. Nothing changes yet.
Sync
When the preview looks right, turn on Sync this knowledge base and click Sync now.
Choose which way changes flow
| Direction | Best for |
|---|---|
| Both ways (recommended) | Writers in WordPress and developers in Git working on the same docs |
| Repository → WordPress | Docs-as-code teams: the repository is the source and WordPress publishes it |
| WordPress → Repository | A Markdown backup or mirror of docs written in WordPress |
You can also choose:
- New files in the repository: publish them straight away, or save them as drafts.
- Send changes to the repository as: a direct commit, or a pull request (a merge request on GitLab) that your team reviews first. The pull request updates itself while it's open.
- When a file is deleted: move the doc to drafts, or keep it published. A sync never deletes a doc.
- Schedule: every hour, twice a day, once a day, or only when you click Sync now.
Show an "Edit this page" link
Turn on Show "Edit this page on GitHub" (or GitLab) and every synced doc gets a link that opens its file in the repository's editor, so teammates can propose fixes straight from the doc.
Common questions
No. When a file is deleted from the repository, its doc moves to drafts or stays published, as you chose. Trashing a doc in WordPress deletes its file from the repository.
Yes. The Activity section shows each sync, what triggered it (schedule, webhook, a saved doc or Sync now) and what changed.
It removes the connection and the link between docs and files. Your docs stay exactly as they are.
