bludit-github-sync/README.md

bludit-github-sync

Export Bludit articles to GitHub, and import an individual article back through an explicit preview and confirmation step.

Saving an article in Bludit can automatically export it. Changes committed to GitHub do not automatically publish to Bludit: use the import controls when you are ready to apply them.

Repository layout

my-article/
  content/
    index.md
  img/
    screenshot.png
  files/
    deployment-log.txt

index.md contains metadata followed by the HTML or Markdown body:

---
title: "My Article"
date: 2026-11-01
slug: my-article
status: published
tags:
  - homelab
  - network
description: "An optional meta description."
category: network
---

Article content with ![Screenshot](../img/screenshot.png)
and a [deployment log](../files/deployment-log.txt).

HTML src and href references use the same relative paths. External HTTP(S) links remain unchanged; imports never download them. Literal fenced code blocks and inline/HTML code examples are not treated as asset links.

Install or upgrade

1. Copy both plugin.php and importer.php, plus metadata.json and languages/, into the existing plugin directory under bl-plugins/. Keep the installed directory name unchanged when upgrading, so Bludit keeps the plugin's settings and workspace.
2. Enable GitHub Sync under Admin → Plugins and open its settings. The old display name was GitHub Export.
3. Configure the repository owner, name, branch, optional path prefix and token. Existing settings are retained on upgrade.

The plugin configuration screen uses Bludit's normal administrator authorization and POST/CSRF protection. There is no public import endpoint or webhook.

Settings

Field	Description
Personal Access Token	A classic token with public_repo for public repositories or repo for private repositories; alternatively a fine-grained token scoped to this repository with Contents read/write for exports. Import also needs read access to repository commits, trees and blobs.
Repository Owner	GitHub user or organization.
Repository Name	Target repository, such as blog.
Branch	Branch used for both exports and import previews; default main. Branch names containing slashes are supported.
Path Prefix	Optional subfolder above the article folders. Leave empty for the repository root.
Auto-export draft articles on save	Default off.
Auto-export published articles on save	Default on.

Use Save after configuring the repository. Import preview also saves the displayed settings before reading GitHub. Changing repository settings after preview requires a fresh preview.

Import one article

For example, to import the article stored as load-balancing-my-homelab/content/index.md:

1. Push the article and its referenced assets to the configured GitHub branch.
2. Open the plugin settings and enter load-balancing-my-homelab under Import one article from GitHub. With a path prefix, still enter only the article folder name.
3. Choose the status behavior before previewing:
   • Import as draft is checked by default, including for an existing published article. Confirming with this option changes the page to a draft.
   • Uncheck it to use a nonempty repository status. A blank or omitted status preserves an existing page's type; a new page remains a draft. Future published dates are scheduled by Bludit.
4. Click Preview import. Review create versus replace, commit, metadata, resulting status, incoming source text and the assets to download. Existing content can be expanded for comparison. The incoming HTML is escaped in the preview, not executed.
5. Click Confirm this import. The plugin downloads and verifies the assets, saves a protected backup when replacing a page, then uses Bludit's createPage() or editPage() functions to save the article and rebuild category/tag indexes.
6. Check the imported draft or live page in Bludit, including its images and attachment links.

The preview is pinned to the Git commit it displayed; newer GitHub commits require another preview. It belongs to the current administrator session, expires after 30 minutes and can only be confirmed once. Cancel preview discards it without editing an article.

Confirmation checks the persisted local page metadata and body again, including after downloads. An intervening local edit requires a new preview. Imports are serialized with each other, but do not lock out Bludit's normal editor: avoid editing the same page during confirmation. Bludit's page storage is not a transactional database.

Metadata and content

• Supported fields: title, date, slug, status, tags, description, category, cover.
• A title and nonempty body are required. If present, slug must match the selected folder. Only a single top-level page key is supported, not nested pages or renames; Bludit slug normalization/collisions are refused.
• Dates use YYYY-MM-DD. An unchanged date preserves the existing time; a changed date uses midnight in the site's timezone.
• Supported statuses: draft, published, static, sticky, scheduled, or blank for legacy exports. Normal Bludit scheduling applies.
• Tags use tags: [] or an indented - tag list. Omitted metadata is preserved on update, apart from the explicit draft option and required title. Blank fields clear their corresponding values.
• A nonempty category key must already exist in Bludit; create it in the administration interface first. Tags are rebuilt through Bludit after save.
• Existing author, UUID and unrelated metadata are retained. New articles belong to the logged-in administrator.
• Front matter supports the small scalar/list format emitted by this plugin, not general YAML. Nested objects, aliases, tags, multiline scalars, unknown fields and duplicate fields are rejected. Quote strings containing YAML punctuation with JSON-style double quotes.
• A cover may be a repository ../img/… reference or an HTTP(S) URL. A repository cover image is imported with the other assets.
• The body is stored as supplied, with asset destinations rewritten to Bludit uploads. The site's usual Markdown configuration controls Markdown rendering. Confirmed HTML is trusted author content, just like content saved in Bludit's editor; previewing it does not sanitize the eventual article.

Assets

Referenced files under the selected article's img/ and files/ directories are fetched through GitHub's blob API and checked against their Git SHA-1 object IDs. Unreferenced files are ignored. This also allows an unused SVG source diagram to remain in Git while its PNG rendition is imported.

Supported extensions: PNG, JPEG, GIF, WebP, AVIF, ICO, TXT, PDF, CSV, JSON and ZIP. Images must pass PHP's image-type validation; support for some formats depends on the PHP runtime. Executable files, HTML and SVG are refused. Absolute external URLs, symlinks, traversal, percent-encoded paths and paths containing whitespace are not fetched. Use simple filenames and inline Markdown links or quoted HTML attributes; reference-style Markdown links and srcset are not imported.

Limits: 1 MiB for the article document; at most 100 referenced assets, 10 MiB per asset and 32 MiB total. The GitHub recursive tree must be complete; truncated trees are rejected. Server memory and request timeouts must also accommodate the import. Git LFS pointer files are not hydrated.

Assets receive generated filenames under the page's UUID uploads directory, preserving existing uploads. A protected per-page mapping makes later exports restore the original repository img/ and files/ paths. Old uploads are not pruned automatically.

Backups and failures

Before updating an existing article, the plugin writes backup-*.php in its Bludit workspace, containing the prior page database row, raw content and imported asset mapping. The file begins with a PHP access-denial guard and is created with restrictive permissions. Keep the site's normal full backups too; these per-page snapshots are not a backup of the entire site or all uploads.

Failed downloads leave page content unchanged. If saving or a later page hook fails, the plugin attempts to restore the previous metadata and content, or remove a partially created page. External side effects from other plugins cannot be rolled back. An unsuccessful automatic restoration is reported explicitly with the backup filename.

Backups and asset mapping files remain in the workspace across plugin upgrades. Do not delete mappings while using import/export round trips. Backups are retained until an administrator removes them. To recover manually, an administrator can read the JSON after the guard line on the server and restore the recorded body and metadata through Bludit; this release does not have a restore button.

Export

• Saving a page exports it when its auto-export setting is enabled.
• Export everything exports drafts and published articles; Export published only exports the published selection.
• Bludit upload URLs become relative ../img/ or ../files/ references. Imported asset mappings retain their original paths.
• Exported status comes from Bludit's actual page type. Earlier plugin versions exported an empty status field; imports accept that legacy format.
• Contents API reads use the configured branch, so export SHA lookups do not accidentally use the repository's default branch.
• Deleting a Bludit page retains the existing automatic GitHub deletion behavior: its document and direct files in img/ and files/ are removed. This is unrelated to importing: missing repository pages never trigger local deletion. Nested repository asset directories are not recursively deleted.
• The plugin's own export hooks are suppressed during import. Other Bludit plugins still receive normal page hooks.

Do not save an older local copy over a newer GitHub article before importing: ordinary exports still replace the repository's current file. This is a manual two-way workflow, not automatic conflict merging or continuous deployment.

Requirements and checks

• Bludit 3.20+; integration tests run against Bludit 3.22.0.
• PHP 7.4+ with cURL; the site's usual Bludit PHP extensions, including mbstring.
• Writable page storage, uploads and plugin workspace, plus access to api.github.com over HTTPS.

No Composer dependencies or YAML extension are required. To run the tests against a separate, unmodified Bludit checkout:

php -l plugin.php
php -l importer.php
BLUDIT_ROOT=/path/to/bludit-3.22.0 php tests/discovery.php
BLUDIT_ROOT=/path/to/bludit-3.22.0 php tests/import.php

The discovery regression test runs Bludit's real buildPlugins() with its real Plugin base class. Helper classes are loaded from init(), after class discovery, so Bludit does not mistake them for plugins.

Tests use temporary local storage and a fake GitHub transport. They exercise real Bludit page creation/editing, asset rewriting and export round trips, rejected paths, escaped previews, stale metadata/configuration, failed downloads and rollback after a failing page hook. They do not modify a live site or contact GitHub.

Optionally exercise a real exported article as a fixture too:

BLUDIT_ROOT=/path/to/bludit-3.22.0 \
BLOG_ARTICLE_DIR=/path/to/blog/load-balancing-my-homelab \
php tests/import.php