All docs
Connect your site
Publish to GitHub (MDX and Markdown sites)
Install the Rivelant GitHub App on your repository so Rivelant publishes posts as .mdx or .md files, for sites built with Next.js, Astro, Hugo and similar.
If your site's posts are Markdown or MDX files in a GitHub repository, Rivelant can publish to it directly. Each post becomes a file in your repo, committed the way a developer would add a page. Nothing is installed on your site.
It works with any framework that builds pages from .mdx or .md files with YAML frontmatter: Next.js, Astro, Hugo, Eleventy and others. Only GitHub is supported, not GitLab or Bitbucket.
Before you start
Your site needs three things:
- A folder for posts and a folder for images, both on the branch you publish to. If a folder is empty, add a
.gitkeepfile so it exists in Git. The images folder must be inside your site's public folder. - Pages that read the frontmatter Rivelant writes (see What Rivelant writes).
- The revision tag in each post's page. Your post template must output this in the page's
<head>:
<meta
name="rivelant:revision"
content="{rivelant.revision from the post's frontmatter}"
/>
Rivelant only marks a post as live when it finds this tag, with the right value, on the published page. Leave it out when a post has no rivelant key.
Connect your repository
- In your project, open Settings › General › Data sources, and click Connect GitHub in the CMS row. (In a new project's setup, Detect recognizes a GitHub repository and offers Connect GitHub too.)
- Click Install on GitHub. On GitHub, choose the repository Rivelant may use (you can pick just one) and approve.
- You're back in Rivelant. Pick the repository and fill in:
| Field | What to enter |
|---|---|
| Branch | Leave empty for the repo's default branch |
| Posts folder | For example src/content/blog |
| Images folder | For example public/blog, inside your public folder |
| File type | .mdx or .md |
| Publish by | Commit (straight to the branch) or Pull request |
| Site address | Your site's address, like https://example.com |
| URL pattern | Where a post lives, with {slug}, like /blog/{slug} |
- Click Connect. Rivelant reads the repository and the posts folder first, and only saves the connection if that works.
Finish within an hour of installing. If it takes longer, you'll see Install again on GitHub; click it and repeat.
After that:
- Click Check connection any time to test it. You should see Connection works.
- To bring in posts you already have, click Import existing posts. Up to 50 come in per click; Import more continues. Importing is free.
What the app can do. The Rivelant GitHub App asks for Contents read and write, Pull requests read and write, and Metadata read, on the repositories you choose. It doesn't use webhooks and can't see repositories you didn't pick.
Anyone with permission to publish in the project can connect GitHub. Only one GitHub connection per project is active at a time; connecting another one switches the old one off.
Can't install the app? Use a token
If you can't install GitHub Apps on the repository, connect with a fine-grained personal access token instead. On GitHub, go to Settings › Developer settings › Fine-grained tokens › Generate new token:
- Repository access: Only select repositories, and pick the one repository.
- Permissions: Contents read and write, and Pull requests read and write. GitHub adds Metadata read-only on its own.
Paste it into the Access token field instead of installing the app. It's stored encrypted and never shown again; if you change the connection's settings later, paste it again.
Tokens expire. When yours does, Check connection shows Token not accepted and publishing stops until you connect again with a new token. The app doesn't have this problem, so prefer it when you can.
What Rivelant writes
Each post is one file, {posts folder}/{slug}.mdx (or .md), and its images go in {images folder}/{slug}/. Images are PNG, JPEG, GIF, WebP or AVIF up to 10 MB each; SVG is not supported. File names are lowercased.
Rivelant writes these frontmatter keys:
| Key | What it holds |
|---|---|
title, description | The post's title and meta description |
date | YYYY-MM-DD, set on first publish and never changed |
updated | Set when a later publish happens on another day |
tags | The post's categories |
draft | false when published, true when taken down |
image | The first image in the post, only if the file has no image yet |
rivelant.document, rivelant.revision | Rivelant's ids for the post and this version |
Any other keys you add, like author, canonical or featured, are kept as they are, comments included.
The body is CommonMark with GitHub tables. Rivelant drops an h1 that repeats the title and turns other h1s into h2, because your page template shows the title. In .mdx files, {, } and < outside code are written as \{, \} and \<, and a line that starts with import or export gets an HTML entity as its first letter (import), so MDX reads them as text. Code is never changed.
Don't auto-format the posts folder. If a formatter like Prettier rewrites those files, Rivelant sees it as an edit on GitHub (below). Add the folder to .prettierignore.
Publishing and going live
Every publish is one commit with the post and its images:
- Commit mode commits straight to your branch, with a message like
Publish "Your title" (Rivelant). - Pull request mode opens a pull request from a
rivelant/...branch, titled the same way. The post goes live when you merge it.
Commits come from the Rivelant app's bot account, or from your GitHub user if you connected with a token.
Protected branches. If your branch is protected, GitHub refuses direct commits and Rivelant shows Branch is protected. Nothing is committed. Switch Publish by to Pull request (the message links to the setting), or allow Rivelant to push to the branch.
While Rivelant waits for your site to deploy, the article shows Publishing · waiting for the site to deploy. Every 5 minutes it fetches the post's address and looks for the revision tag. You can also click Check on the article. Once the tag matches, the post is live and Rivelant starts measuring its rankings.
If the tag doesn't show up within 2 hours of the commit, or the pull request is closed without merging, you'll see The site didn't update. The usual causes are covered in Troubleshooting.
Edits on GitHub
You can edit published files on GitHub. If you change a post's title, description or body there, Rivelant notices before its next publish of that post, refuses to overwrite your change, and shows Changed on the website. Changes to other frontmatter keys don't count.
Taking a post down
Taking a post down, with Undo in a campaign or Take down… under More pages › Articles, sets draft: true in its file, so your site should stop showing it (a 404). The file stays in the repository. Reinstate under Taken down pages removes the draft key again. Rivelant never deletes files; to delete one, do it on GitHub.
Take-downs always commit straight to the branch, even in pull request mode, so on a protected branch they're refused too; set draft: true on GitHub yourself instead.
Rivelant can't create redirects on GitHub sites, so merging two articles into one isn't available for them.
Disconnecting
In Settings › General › Data sources, click Disconnect on the CMS row and confirm. Rivelant switches the connection off and forgets the app installation (or deletes the stored token). The row then shows Not connected; to use it again, connect again.
Your files and commits stay in the repository, and your articles stay in Rivelant. A post that was already committed and waiting for your site to deploy is still confirmed live from the page.
To remove Rivelant from GitHub too, uninstall the app on GitHub under Settings › Applications, or delete the token if you used one.
Troubleshooting
| You see | What it means |
|---|---|
| Repository or folder not found | The repository, branch or a folder doesn't exist, or Rivelant wasn't given access to it. Check the names, that both folders exist on the branch, and that the app (or token) includes this repository. |
| Install again on GitHub | The app installation wasn't finished within an hour, or was started by another GitHub user. Click it and install again. |
| Token not accepted | The token is wrong, expired, or missing a permission. Create a new one with the permissions above, or switch to the app. |
| The site didn't update | The revision tag wasn't found within 2 hours. Check that your site redeploys after a commit, that the page is public, that the template outputs the tag, and that the URL pattern matches your site. Long CDN caching can also delay it. A revoked token can cause it too. |
| Changed on the website | Someone edited the post's text on GitHub (or a formatter did). Review the change before publishing again. |
| Branch is protected | Your branch doesn't accept direct commits. Switch Publish by to Pull request, or allow the token to push to the branch. |
| Can't reach the CMS (on an article) or CMS unreachable (in Settings) | GitHub refused the request or was unavailable, or the token no longer works. Click Check connection. |
| Unavailable for now | GitHub's limit of 5,000 requests an hour for the token was reached. Try again later. |
Updated November 13, 2026. Still stuck? support@rivelant.comView as Markdown