GitHub
Connect Knowatoa to a GitHub repository to publish articles as markdown files. This works with static site generators like Hugo, Jekyll, Astro, and any system that builds from markdown in a Git repository.
Requirements
- A GitHub repository for your site’s content
- A GitHub personal access token with
reposcope
Setup
- Go to your site in Knowatoa and click Integrations > CMS Connections > New Connection.
- Select GitHub.
- Fill in the required fields:
| Field | Description |
|---|---|
| Repository | The repo where articles should be committed (e.g., your-org/your-blog) |
| Branch | The branch to commit to (e.g., main) |
| Path Prefix | The directory for content files (e.g., content/blog/) |
| Personal Access Token | A GitHub token with repo scope |
| Front Matter Template | Custom YAML front matter for your static site generator |
- Click Verify Credentials to confirm the connection works.
- Click Save.
Front matter template
Customize the YAML front matter prepended to each article using these template variables:
| Variable | Description |
|---|---|
{{title}} |
The article title |
{{date}} |
The publication date (YYYY-MM-DD) |
{{datetime}} |
Full timestamp |
{{slug}} |
URL-friendly slug |
{{excerpt}} |
Article excerpt/description |
{{content}} |
The full article body (used in the main content, not typically in front matter) |
Example templates
Hugo:
yaml
---
title: "{{title}}"
date: {{datetime}}
slug: "{{slug}}"
description: "{{excerpt}}"
---
Jekyll:
yaml
---
layout: post
title: "{{title}}"
date: {{datetime}}
excerpt: "{{excerpt}}"
---
Astro:
yaml
---
title: "{{title}}"
pubDate: {{datetime}}
slug: "{{slug}}"
description: "{{excerpt}}"
---
How articles are published
- Articles are committed as markdown files to the specified branch and path.
- Filenames follow your static site generator’s convention (e.g.,
2026-04-23-article-slug.mdfor Jekyll, orarticle-slug.mdfor others). - If your site has CI/CD set up (Netlify, Vercel, GitHub Pages), the commit will automatically trigger a rebuild.
Generating a personal access token
- Go to GitHub Settings > Developer settings > Personal access tokens.
- Click Generate new token (classic).
- Give it a name (e.g., “Knowatoa Publishing”).
- Select the repo scope.
- Click Generate token and copy it.
Troubleshooting
Verify Credentials fails
- Check that the token has repo scope and hasn’t expired.
- Verify the repository name is correct (format: owner/repo).
Articles committed to wrong location
- Check the Path Prefix setting – it should match your content directory (e.g., content/posts/ for Hugo, _posts/ for Jekyll).
See Connect Your CMS for general CMS setup instructions.