72 lines
2.6 KiB
Markdown
72 lines
2.6 KiB
Markdown
# bludit-github
|
|
|
|
A [Bludit](https://www.bludit.com) plugin that automatically exports your blog articles to a GitHub repository as Markdown files.
|
|
|
|
## What it does
|
|
|
|
Whenever you create, update, or delete an article in Bludit, the plugin pushes the change to a GitHub repository via the GitHub API. Each article is exported as its own folder, with the markdown file inside `article/` and images inside `img/`:
|
|
|
|
```
|
|
my-article/
|
|
article/
|
|
index.md
|
|
img/
|
|
photo.png
|
|
screenshot.jpg
|
|
another-post/
|
|
article/
|
|
index.md
|
|
```
|
|
|
|
Each `index.md` contains a YAML frontmatter block followed by the article content. Image references are written as relative paths from the `article/` subfolder:
|
|
|
|
```markdown
|
|
---
|
|
title: "My Article"
|
|
date: 2026-05-01
|
|
slug: my-article
|
|
status: published
|
|
tags:
|
|
- php
|
|
- bludit
|
|
description: "Optional meta description"
|
|
category: tech
|
|
---
|
|
|
|
Article content with images like 
|
|
```
|
|
|
|
## Installation
|
|
|
|
1. Copy the `bludit-github` folder into your Bludit `bl-plugins/` directory.
|
|
2. Go to **Admin → Plugins** and enable **GitHub Export**.
|
|
3. Open the plugin settings and fill in your GitHub credentials.
|
|
|
|
## Settings
|
|
|
|
| Field | Description |
|
|
|---|---|
|
|
| Personal Access Token | A GitHub token with `public_repo` scope (or `repo` if the repository is private). [Generate one here](https://github.com/settings/tokens/new). |
|
|
| Repository Owner | Your GitHub username or organization name. |
|
|
| Repository Name | The target repository (e.g. `my-blog`). |
|
|
| Branch | Branch to push to (default: `main`). |
|
|
| Path Prefix | Optional subfolder prefix. Leave empty to export at the repo root. |
|
|
| Export drafts | When checked, draft articles are also exported. |
|
|
| Auto-export on save | When checked, articles are automatically pushed to GitHub whenever you save or modify them. Uncheck to only use manual bulk export. |
|
|
|
|
## Bulk export
|
|
|
|
The settings page includes an **Export all articles now** button that pushes all your existing articles to GitHub in one go. Useful on first install or after changing the target repository.
|
|
|
|
## Behavior
|
|
|
|
- **On article save** (if auto-export is enabled): `article/index.md` is created or updated, and all images referenced in the content are uploaded to `img/`.
|
|
- **On article delete** (if auto-export is enabled): both `article/index.md` and all files in `img/` are deleted (GitHub removes the empty folders automatically).
|
|
- **Manual bulk export:** Use the "Export all articles now" button to push articles regardless of auto-export setting.
|
|
- **Errors** are displayed in the plugin settings panel and never interfere with Bludit's own save process.
|
|
|
|
## Requirements
|
|
|
|
- Bludit 3.20+
|
|
- PHP with `curl` extension enabled
|