GitHub Integration

Push your articles directly to a GitHub repository as MDX files. This integration is perfect for static site generators like Next.js, Astro, Gatsby, or any framework that supports MDX content.

Prerequisites

• A GitHub account
• A repository where you want to publish articles
• Repository write access

Setup

1. Install the PixelPost GitHub App

1. Go to Project Settings in your PixelPost dashboard
2. Click Connect on the GitHub integration
3. You’ll be redirected to GitHub to install the PixelPost app
4. Select the repositories you want to grant access to
5. Click Install to complete the setup

2. Configure Your Repository

After connecting, click Configure to set up your publishing paths:

• Repository - Select which repository to publish to
• Branch - The branch to commit to (usually main)
• Content Path - Where MDX files will be saved (e.g., content/blog)
• Images Path - Where images will be saved (e.g., public/images/blog)

3. Enable the Integration

Toggle the integration switch to enable automatic publishing.

File Structure

When PixelPost publishes an article, it creates:

your-repo/
├── content/blog/
│   └── your-article-slug.mdx
└── public/images/blog/
    └── your-article-slug/
        ├── featured.png
        └── image-1.png

Image extensions match the original format (png, jpg, or webp).

Frontmatter Configuration

PixelPost supports customizable frontmatter to work with any static site generator. When you configure the GitHub integration, you can choose from framework presets or define custom field mappings.

Supported Frameworks

PixelPost works with any static site generator or framework that uses Markdown/MDX files for content. Select your framework to automatically configure paths and frontmatter fields:

Each preset also configures the correct frontmatter field names for that framework (e.g., Astro uses pubDate instead of date, Hugo uses featured_image instead of image).

Auto-Detection

When you select a repository, PixelPost automatically scans your existing content to detect the frontmatter pattern you’re using. If we find existing MDX or Markdown files, we’ll pre-fill the configuration to match your blog’s structure.

You’ll see a notification: “Frontmatter detected! We found existing content and configured the fields to match your blog.”

Custom Fields

If your site uses non-standard field names, expand the Frontmatter Fields section in the configuration dialog to customize each field:

• Title field - The key for your article title (e.g., title, name)
• Description field - The key for SEO description (e.g., description, excerpt, summary)
• Date field - The key for publish date (e.g., date, pubDate, publishedAt)
• Image field - The key for featured image (e.g., image, coverImage, heroImage, featured_image)
• Keywords field - The key for tags/categories (e.g., tags, keywords, categories)

Example Output

Based on your configuration, PixelPost generates frontmatter like this:

---
title: "Your Article Title"
description: "Meta description for SEO"
date: "2024-01-15"
slug: "your-article-slug"
image: "/images/blog/your-article-slug/featured.png"
tags: ["target keyword"]
---

The field names will match your configuration, ensuring seamless integration with your existing content pipeline.

Permissions

The PixelPost GitHub App only requests the minimum permissions needed:

• Contents - Read and write access to commit files
• Metadata - Read-only (required by GitHub)

We never access your code, issues, pull requests, or any other repository data.

Troubleshooting

”Repository not found” error

Make sure the PixelPost GitHub App is installed on the repository. Go to your GitHub Settings → Applications → PixelPost to verify.

”Branch not found” error

Verify the branch name in your configuration matches an existing branch in your repository.

Images not displaying

Check that your site’s image configuration includes the images path you specified. For Next.js, you may need to update next.config.js.

Images not showing in GitHub preview

Depending on your file structure and framework, images may not display in GitHub’s markdown preview but will work correctly on your live website. This is because GitHub’s preview doesn’t understand framework-specific image paths like /images/blog/... that resolve to public/images/blog/... at build time.