# 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](#what-rivelant-writes)).
3. **The revision tag in each post's page.** Your post template must output this in the page's `<head>`:

```html
<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:

| 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}`  |

4. 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 `h1`s 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](#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.                                                                                                                                                                                       |
