GitHub Publishing

Floyi’s GitHub Publishing integration lets you push finished content from the Content Creation workspace straight to any Git-based static site. Your articles arrive as Markdown or MDX files with frontmatter, images, and schema markup, committed atomically to your repository. If your repo has CI/CD configured (Cloudflare Pages, Vercel, Netlify), your site deploys automatically.

• How to install the Floyi GitHub App on your GitHub account or organization
• How to connect a repository and configure it for your static site framework
• How to publish, update, and manage articles
• How to customize frontmatter templates for any framework
• How to use framework presets for Astro, Next.js, Hugo, Jekyll, and Docusaurus
• How to manage connected repos and troubleshoot issues

Before you can connect a repository, you need to install the Floyi GitHub App on your GitHub account or organization.

[!NOTE] CI/CD is not required. Floyi commits files to your repo regardless. However, without CI/CD, you’ll need to manually build and deploy your site after publishing.

The Floyi GitHub App requests minimal permissions:

Floyi does not request access to issues, pull requests, actions, or any other GitHub features.

1. In Floyi, go to Settings > Integrations.
2. Scroll to the GitHub section.
3. Click Connect.
4. You are redirected to GitHub to install the Floyi app.
5. Choose which account or organization to install on.
6. Select All repositories or choose specific repos you want Floyi to access.
7. Click Install.
8. GitHub redirects you back to Floyi with a confirmation.

After installation, Floyi stores your installation ID. You can now connect individual repositories.

[!TIP] If you’re installing on an organization, an organization admin may need to approve the installation first. Check your org’s GitHub App policy if the install is blocked.

After installing the GitHub App, you connect individual repositories and configure how Floyi publishes to each one.

1. In Settings > Integrations, under the GitHub section, click + Connect.
2. The connection modal opens with two steps.

Step 1: Select Repository

• If you’ve already installed the Floyi app, your accessible repos appear in a dropdown.
• If you haven’t installed the app yet, click Install Floyi on GitHub to start the installation flow.
• Select the repository you want to publish to.
• Select the target branch (e.g., main, develop).

Step 2: Configure Publishing Settings

Choose a framework preset (optional) to pre-fill settings, or configure manually:

• File Extension — .md or .mdx
• File Naming Pattern — How article files are named (e.g., {slug}.mdx, {date}-{slug}.md, {slug}/index.md)
• Content Path — Where Markdown/MDX files are committed (e.g., src/content/blog/)
• Image Path — Where images are committed (e.g., src/assets/blog/)
• Frontmatter Template — The YAML frontmatter template with {{ variable }} placeholders
• Schema Embed Mode — How JSON-LD schema markup is included: as a script tag after frontmatter, inside frontmatter, or not at all

Click Connect to save the configuration. A success screen confirms the connection with a summary of your settings.

Presets pre-fill all settings with sensible defaults for popular frameworks. You can edit everything after selecting a preset.

If your framework isn’t listed, skip the preset and configure settings manually. The integration is framework-agnostic — it works with any static site that reads Markdown or MDX files.

[!TIP] You can change all connection settings later from Settings > Integrations by clicking the settings icon on the connected repo card.

After connecting, your repositories appear in Settings > Integrations under the GitHub section.

Each connected repo shows:

• Repository name in owner/repo format
• Branch being published to
• Content path where files are committed
• File extension (.md or .mdx)
• Framework preset badge (if one was used)
• Last publish date and article count
• Settings button to modify connection configuration
• Disconnect button to remove the connection

Click the health check icon on any connected repo to verify the connection is working. A successful check confirms that:

• The Floyi GitHub App still has access to the repository
• The configured branch exists
• Floyi can write to the repository

If the check fails, review the error message. Common causes include:

• The Floyi app was uninstalled from GitHub
• The repository was deleted or renamed
• Repository access was revoked from the app’s installation settings

WordPress and GitHub connections share a single publishing sites limit based on your Floyi plan. The connection count appears as a badge (e.g., “2/3”) next to the Publishing section header.

Disconnecting a site frees up a slot immediately.

1. Click the Disconnect button (trash icon) on the repo card.
2. Confirm the disconnection in the dialog.

Disconnecting removes the active link between Floyi and your repository. Files already committed to the repo remain untouched. You can reconnect the same repo later.

You can publish any article from the Content Creation workspace to a connected GitHub repository.

1. Open an article in the Content Editor.
2. Click the Publish dropdown in the toolbar.
3. Select Publish to GitHub.
4. The GitHub publish modal opens.

If you have multiple connected repos, choose the target repo from the Repository dropdown. The dropdown shows each repo’s name, branch, and framework preset.

If only one repo is connected, it is selected automatically.

When you select a repository, the publish settings are pre-filled from your connection configuration. You can override any setting for this specific publish without changing the connection defaults:

• Branch — The branch to commit to
• File extension — .md or .mdx
• Content path — Where the article file goes
• File naming pattern — How the file is named
• Image path — Where images are committed
• Schema markup — Script tag, frontmatter, or none
• Include images — Toggle to include or exclude images from the commit

Below the settings, a file path preview shows exactly where the article will be committed:

src/content/blog/seo-topical-map-mistakes.mdx

This updates live as you change the content path, file naming pattern, or file extension.

If a frontmatter template is configured, it appears in an editable text area. You can review and modify the template before publishing. Variables like {{ title }}, {{ slug }}, and {{ tags_array }} are replaced with actual article data at publish time.

Click Publish to GitHub. A loading state appears while Floyi:

1. Compiles your article to Markdown
2. Renders the frontmatter template with article data
3. Downloads images from Floyi’s CDN
4. Creates Git blobs for all files
5. Commits everything atomically to your repo

Once complete, a success screen shows:

• Repository name and branch
• File path of the committed article
• Commit SHA with a link to view the commit on GitHub
• A note that your site will deploy automatically if CI/CD is configured

Floyi uses the Git Trees API to create a single atomic commit containing the article file and all images. This means either all files are committed together or none are — there are no partial commits.

The commit is authored by Floyi with a message like:

Publish: 10 Common SEO Topical Map Mistakes

Published via Floyi

When you edit an article in Floyi after it has been published to GitHub, the publish modal shows that the article was previously published.

1. Open the previously published article in the Content Editor.
2. Click the Publish dropdown and select Publish to GitHub.
3. The modal shows:
   • A Previously published indicator with a green checkmark
   • The commit SHA of the last publish (clickable link to GitHub)
   • An Update badge if the article content has changed since the last publish
4. Modify any publish settings if needed.
5. Click Update on GitHub to push the latest version.

The updated content replaces the existing file in your repo. A new commit is created — the file path remains the same.

Floyi tracks a content hash for each published article. When you edit the article in Floyi, the publish modal shows whether the content has changed since the last publish. This helps you know at a glance which articles need updating.

The frontmatter template is the core of Floyi’s framework-agnostic approach. You write a YAML template with {{ variable }} placeholders, and Floyi fills them in with article data at publish time.

1. When you connect a repo (or select a framework preset), a frontmatter template is saved.
2. At publish time, Floyi replaces each {{ variable }} with the corresponding article data.
3. The rendered frontmatter is prepended to the Markdown body.
4. The assembled file is committed to your repo.

Template (what you configure):

---
title: '{{ title }}'
description: '{{ meta_description }}'
pubDate: { { publish_date } }
slug: '{{ slug }}'
heroImage: '{{ hero_image_path }}'
heroAlt: '{{ hero_image_alt }}'
author: '{{ brand_name }}'
tags: { { tags_array } }
---

Rendered output (what gets committed):

---
title: '10 Common SEO Topical Map Mistakes to Avoid'
description: 'Validate seed topics, align search intent, and avoid common pitfalls when building your topical map.'
pubDate: 2026-04-17
slug: 'seo-topical-map-mistakes'
heroImage: './images/seo-topical-map-mistakes-hero.jpg'
heroAlt: 'Topical map structure diagram'
author: 'Floyi'
tags: ['seo', 'topical-maps', 'content-strategy']
---

You can edit the frontmatter template in two places:

1. Connection settings — Go to Settings > Integrations, click settings on a connected repo. Changes here apply to all future publishes from that repo.
2. Publish modal — Edit the frontmatter directly before publishing. Changes here apply only to the current publish and do not modify the saved template.

When you publish with images included, Floyi downloads each image from its CDN and commits it to your repository alongside the article file.

1. Floyi downloads images from the Cloudflare R2 CDN where they are stored.
2. Each image is encoded as a Git blob (base64).
3. Images are placed in the configured image path, organized in a subdirectory named after the article slug.
4. Image references in the Markdown body and frontmatter are rewritten to use relative paths.

For an article with slug seo-topical-map-mistakes, images are committed as:

src/assets/blog/
  └── seo-topical-map-mistakes/
      ├── hero.jpg
      ├── image-1.jpg
      └── image-2.jpg

This prevents filename collisions between articles.

Floyi selects the hero/featured image in this order:

1. User-selected featured image set explicitly in Floyi
2. First image in the article body auto-detected from the editor content
3. AI-generated image if image generation was used
4. No featured image if none of the above exist

If you prefer to manage images separately (e.g., through a CMS or image CDN), uncheck Include images in commit in the publish modal. The article file will still be committed, but image paths in the Markdown will reference their Floyi CDN URLs instead of local paths.

Floyi can embed structured data (JSON-LD schema markup) in your published files. This is the same schema data generated by Floyi’s Schema Generator.

You can change the schema embed mode per connection in your repo settings, or override it per publish in the publish modal.

When you publish an article that is linked to a topic in your Topical Map, Floyi automatically updates your Topical Authority data:

• The topic node is marked as Published in the Topical Authority Planner
• Your coverage metrics update to reflect the newly published content
• The Topical Authority Scorecard reflects the change in your next refresh

This creates a closed loop: plan topics in your Topical Map, create briefs and drafts, publish to GitHub, and track authority growth — all within Floyi.

Floyi articles can contain internal links to other articles. When publishing to GitHub, these links are automatically resolved.

• Published articles — Internal links pointing to other published articles are resolved to your site’s URL using your brand website URL + the article slug.
• Cross-repo links — If the linked article is published to the same repo, relative paths are used.
• Unpublished articles — If a linked article hasn’t been published yet, Floyi warns you during the pre-publish step. The link is still included but may not resolve until the target article is published.

When a publish fails, the error screen shows a Retry button. Click it to attempt the publish again with the same settings. Floyi also retries automatically up to 3 times with increasing delays for transient errors.

If publishing takes longer than 2 minutes (e.g., an article with many large images), the modal shows a timeout message. The task may still be running in the background — check your GitHub repo to see if the commit appeared.

GitHub publishing is available to team members based on their role:

Floyi uses a GitHub App (not OAuth tokens or personal access tokens) for maximum security:

The number of connections depends on your Floyi plan. WordPress and GitHub connections share the same limit. Your current usage is shown in the Publishing section header (e.g., “2/3”). Free plans do not include publishing integrations.

Yes. Open the publish modal and select a different repo from the dropdown. Each repo maintains its own publish record, so you can publish the same Floyi article to multiple repos with different settings and frontmatter templates.

Yes. WordPress and GitHub are independent publishing integrations. You can publish the same article to a WordPress site and a GitHub repo. Each uses its own publish flow and tracks its own publish status.

Any framework that reads Markdown or MDX files with YAML frontmatter. Floyi provides quick-start presets for Astro, Next.js, Hugo, Jekyll, and Docusaurus, but the integration is framework-agnostic. You can configure the frontmatter template, file naming, and paths to match any framework.

Floyi commits directly to the configured branch (e.g., main). Pull request-based workflows are planned for a future update.

Files already committed to the repo remain untouched. After reconnecting, Floyi creates a new connection record. Existing publish records from the previous connection are preserved in Floyi’s history.

Floyi commits files to your repo but does not manage deployments. Verify that:

• Your CI/CD platform (Cloudflare Pages, Vercel, Netlify) is configured to deploy on pushes to the branch Floyi commits to
• Your build is not failing due to content errors (check your platform’s build logs)
• The committed files are in the correct directory for your framework

Yes. Presets are a convenience that pre-fills settings. After selecting a preset, you can edit every field — the content path, image path, file naming pattern, and the entire frontmatter template. You can also start from scratch without a preset.

The publish modal shows a Previously published indicator with the commit SHA. If the article has changed since the last publish, an orange Update badge appears. You can also see this in the file path preview area of the publish modal.

Commits use the format: Publish: {Article Title} with a body of Published via Floyi. For updates, the message is Update: {Article Title}.

Yes. Go to your GitHub account settings > Applications > Floyi, and modify the repository access. You can add or remove repos at any time. Changes take effect immediately in Floyi.

All files previously committed to your repo remain unchanged. Uninstalling the app only removes Floyi’s ability to make new commits. In Floyi, the connection is marked as disconnected.

Floyi only creates or updates files that it published. It never modifies, deletes, or reads files that were not created through Floyi’s publishing flow.