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:

  1. A folder for posts and a folder for images, both on the branch you publish to. If a folder is empty, add a .gitkeep file so it exists in Git. The images folder must be inside your site's public folder.
  2. Pages that read the frontmatter Rivelant writes (see What Rivelant writes).
  3. 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

  1. 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.)
  2. Click Install on GitHub. On GitHub, choose the repository Rivelant may use (you can pick just one) and approve.
  3. You're back in Rivelant. Pick the repository and fill in:
FieldWhat to enter
BranchLeave empty for the repo's default branch
Posts folderFor example src/content/blog
Images folderFor example public/blog, inside your public folder
File type.mdx or .md
Publish byCommit (straight to the branch) or Pull request
Site addressYour site's address, like https://example.com
URL patternWhere a post lives, with {slug}, like /blog/{slug}
  1. 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:

KeyWhat it holds
title, descriptionThe post's title and meta description
dateYYYY-MM-DD, set on first publish and never changed
updatedSet when a later publish happens on another day
tagsThe post's categories
draftfalse when published, true when taken down
imageThe first image in the post, only if the file has no image yet
rivelant.document, rivelant.revisionRivelant'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 (&#105;mport), 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 seeWhat it means
Repository or folder not foundThe 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 GitHubThe app installation wasn't finished within an hour, or was started by another GitHub user. Click it and install again.
Token not acceptedThe 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 updateThe 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 websiteSomeone edited the post's text on GitHub (or a formatter did). Review the change before publishing again.
Branch is protectedYour 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 nowGitHub's limit of 5,000 requests an hour for the token was reached. Try again later.