What you need
- A GitHub repository with Markdown or MDX pages. The pages can be in the root or in one folder, for example
docs/. - If you have them: a
docs.jsonfile for the navigation, and an OpenAPI file for the API reference. - Permission to install a GitHub App for the repository. For an organization, an admin of the organization connects it.
Connect the repository
- Sign up with GitHub, Google or your email address.
- When the setup asks where your docs come from, click Connect a GitHub repository.
- Install the Revdoku GitHub App and select the repository.
- Choose the branch. If the docs are in a folder, choose the folder too.
- Click Continue, then Publish. Choose the name of the site, its address and a docs layout.
The site is at https://<name>.revdoku.site. To use your own domain, open the Domain page of the site.
If your docs are not on GitHub, click Upload files, or Start from the docs template for a sample site with an OpenAPI file and an API console.
What Revdoku publishes
| In the repository | On the docs site |
|---|---|
| Markdown and MDX pages | One page each, with the title and the description from the front matter |
docs.json or mint.json |
The navigation: tabs, groups and pages. Without these files, the folders make the navigation. |
| An OpenAPI file | One reference page for each tag, and an API console where people try real requests |
| All pages | Full-text search, Ask AI, llms.txt, llms-full.txt, a Markdown copy of each page and an MCP server at /mcp |
Revdoku skips a file that is larger than 100 MiB or that Git LFS stores. The GitHub page of the site lists each skipped file. The other files publish.
What happens on each push
- A push to the connected branch publishes the site again. GitHub shows a “Revdoku” status on the commit, with the link to the site.
- After the site is live, a push to another branch of the repository makes a preview site for 24 hours. A pull request from that branch shows the same preview in its status.
- If a publish fails, the status on the commit links to the site page in Revdoku.
Edits in Revdoku go back to GitHub
The Edits in Revdoku setting on the GitHub page of the site has three choices:
| Choice | What happens to an edit |
|---|---|
| Publish manually | The edit waits as a pending change. Click Publish to main to send all pending changes as one commit, or Open pull request. |
| Commit at once | Each sync sends the edits as a commit. |
| Read-only | Nobody can change the docs files in Revdoku. Edit them in the repository. |
If GitHub refuses a direct commit, for example because of branch protection, Revdoku opens a pull request with the same commit. If a file changed on both sides, the GitHub version wins, and the Revdoku version stays as an earlier version of the file.
What the GitHub App can do
The app can read and write the repository contents, commit statuses and pull requests. It reads the repository metadata and, for an organization, its members. It has no Administration permission, so Revdoku never creates, deletes or configures repositories. Revdoku uses the GitHub API and keeps no clone of the repository. See Security.
Start
Start free. You do not need a card. Already on Mintlify? See Move Mintlify docs to Revdoku.