GitHub Integration

Overview

The GitHub integration lets you publish content to any GitHub repository, making it ideal for static site generators like Hugo, Jekyll, Eleventy, Gatsby, Astro, and Next.js. Publish Owl commits Markdown, MDX, or JSON files directly to your repo, triggering your site's auto-deploy pipeline.

Requirements

• A GitHub repository for your static site
• A fine-grained personal access token with repository access
• A static site generator set up with auto-deploy (GitHub Pages, Vercel, Netlify, etc.)

Step 1: Create a Personal Access Token

1. Go to GitHub → Settings → Developer settings → Fine-grained tokens
2. Click Generate new token
3. Name it "Publish Owl" and set an expiration
4. Under Repository access, select "Only select repositories" and choose your site repo
5. Under Repository permissions, set:
   • Contents — Read and write (for committing files)
   • Metadata — Read (auto-enabled with Contents)
6. Click Generate token and copy it

Step 2: Add Your GitHub Site

1. In Publish Owl, go to Sites
2. Click + Add Site
3. Enter a name for your site
4. Select GitHub Pages as the CMS type
5. Fill in:
   • Owner: Your GitHub username or organization (you can also paste a full repo URL and it will auto-fill)
   • Repository: The repo name
   • Branch: The branch to commit to (e.g., main)
   • File Format: Markdown (.md), MDX (.mdx), or JSON (.json)
   • Personal Access Token: The token from Step 1
   • Content Path: Where to save files (e.g., content/posts)
6. Click Save Site

File Formats

Frontmatter

For Markdown and MDX formats, Publish Owl generates frontmatter with article metadata. You can customize this with a frontmatter template using placeholders:

title: "{{title}}"
date: {{date}}
draft: {{draft}}
description: "{{description}}"
tags: {{tags}}
categories: {{categories}}
featured_image: "{{featured_image}}"
author: "{{author}}"
keyword: "{{keyword}}"

Leave the template blank to use sensible defaults. YAML is the default frontmatter format, but TOML (+++) and JSON (---json) are also supported.

Hugo Page Bundles

Enable "Use page bundles (Hugo)" to create each article in its own folder with images as page resources. This creates:

content/posts/my-article/
  index.md          # Article content
  featured.jpg      # Featured image (downloaded)
  image-1.png       # Inline images (downloaded)
  image-2.jpg

Images are downloaded from their source URLs, committed to the bundle directory, and image references in the content are rewritten to use local paths. All files are committed atomically using GitHub's Git Trees API.

Deploy Hooks

If your site doesn't auto-deploy on git push, you can configure a deploy hook URL. Enable "Trigger deploy hook after publishing" and enter your Vercel or Netlify deploy hook URL. This triggers a rebuild after each article is committed.

Limitations

• No scheduled publishing: Files are committed immediately. Use your static site generator's draft/publish system for scheduling.
• No content fetching: Publish Owl cannot fetch content back from GitHub for editing. Content is stored locally in the Publish Owl database.

Troubleshooting