brendan/obsidian-jekyll-publish
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Update README

Browse Source
This commit is contained in:
Brendan Chen
2026-08-09 14:11:36 -04:00
parent ac37b6a6f5
commit 06350d6c62
1 changed files with 55 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

81
README.md
View File

@@ -1,13 +1,17 @@
# Obsidian Jekyll Publish
An Obsidian plugin that publishes the active note as a Jekyll blog post via git. Images are copied alongside the post using one of two configurable strategies, and credentials are handled by your system git — nothing is stored inside Obsidian.
An Obsidian plugin that publishes the active note as a Jekyll page via git.
Images are copied alongside the post using one of two configurable strategies,
and credentials are handled by your system git. Nothing is stored inside
Obsidian.
## What it does
1. Opens a "Publish to Jekyll" modal for the currently active markdown file.
2. Lets you confirm or adjust the slug, date, frontmatter, image strategy, and commit message.
1. Opens a "Publish to Jekyll" modal for the currently active Markdown file.
2. Lets you confirm or adjust the slug, date, frontmatter, image strategy, and
commit message.
3. Clones (or updates) your Jekyll site repository into a temporary directory.
4. Writes the post as `_posts/<date>-<slug>.md` (or your configured path).
4. Writes the note to your configured directory.
5. Copies any embedded images according to the selected strategy.
6. Commits and pushes to your configured remote and branch.
@@ -18,36 +22,54 @@ An Obsidian plugin that publishes the active note as a Jekyll blog post via git.
```
<your-vault>/.obsidian/plugins/jekyll-publish/
```
3. Reload Obsidian and enable **Jekyll Publish** under Settings → Community plugins.
3. Reload Obsidian and enable **Jekyll Publish** under Settings → Community
plugins.
## Settings
| Setting | Description | Default |
|---|---|---|
| Remote URL | Git remote URL for your Jekyll site (HTTPS or SSH) | _(empty)_ |
| Branch | Branch to push to | `main` |
| Posts directory | Destination directory inside the repo | `_posts` |
| Images directory | Where images are copied inside the repo | `assets/img` |
| Default image strategy | `flat-slug` or `per-post-folder` (see below) | `flat-slug` |
| Preset frontmatter | Key/value pairs always injected into every post | _(empty)_ |
| Setting | Description | Default |
|-------------------------|-----------------------------------------------------|----------------------|
| Remote URL | Git remote URL for your Jekyll site (HTTPS or SSH) | _(empty)_ |
| Branch | Branch to push to | `main` |
| Posts directory | Destination directory inside the repo | `_posts` |
| Images directory | Where images are copied inside the repo | `assets/img` |
| Default image strategy | `flat-slug` or `per-post-folder` (see below) | `flat-slug` |
| Preset frontmatter | Key/value pairs always injected into every post | _(empty)_ |
| Commit message template | Template; `{{title}}` is replaced by the note title | `Publish: {{title}}` |
| Author name | Git author name for commits | _(empty)_ |
| Author email | Git author email for commits | _(empty)_ |
| Author name | Git author name for commits | _(empty)_ |
| Author email | Git author email for commits | _(empty)_ |
## Image strategies
**flat-slug** — all images for the post are copied flat into `<images-dir>/`. A single image is renamed to `<slug>.<ext>`; multiple images are renamed to `<slug>-1.<ext>`, `<slug>-2.<ext>`, … (the original Obsidian filename is discarded). Keeps the images directory shallow; suitable for sites with few images per post.
**flat-slug** — all images for the post are copied flat into `<images-dir>/`. A
single image is renamed to `<slug>.<ext>`; multiple images are renamed to
`<slug>-1.<ext>`, `<slug>-2.<ext>`, etc.
**per-post-folder** — images are copied into `<images-dir>/<slug>/` preserving their original filenames. Keeps each post's images grouped together; suitable for posts with many images.
**per-post-folder** — images are copied into `<images-dir>/<slug>/` preserving
their original filenames.
## Credentials model
The plugin uses your **system git** binary for all remote operations and stores **no** passwords or tokens inside Obsidian or the plugin's data files. Authentication is delegated entirely to git's own credential handling, which works across platforms:
The plugin uses your **system git** binary for all remote operations and stores
**no** passwords or tokens inside Obsidian or the plugin's data files.
Authentication is delegated entirely to git's own credential handling, which
works across platforms:
- **HTTPS remotes** — git uses your configured credential helper: **Git Credential Manager** (bundled with Git for Windows), **osxkeychain** (macOS), or libsecret (Linux). The first push prompts you through that helper's own dialog and caches the result in your OS keychain. If no helper is configured, the publish fails fast with a clear message (the plugin sets `GIT_TERMINAL_PROMPT=0` so git never hangs waiting on a non-existent terminal).
- **SSH remotes** — git uses your existing SSH agent / `~/.ssh` key configuration. Use an `ssh://` URL and make sure your key (or agent) is set up; no extra steps in the plugin.
- **HTTPS remotes** — git uses your configured credential helper: **Git
Credential Manager** (bundled with Git for Windows), **osxkeychain** (macOS),
or libsecret (Linux). The first push prompts you through that helper's own
dialog and caches the result in your OS keychain. If no helper is configured,
the publish fails fast with a clear message (the plugin sets
`GIT_TERMINAL_PROMPT=0` so git never hangs waiting on a non-existent
terminal).
- **SSH remotes** — git uses your existing SSH agent / `~/.ssh` key
configuration. Use an `ssh://` URL and make sure your key (or agent) is set
up; no extra steps in the plugin.
Commits are authored with the **Author name/email** from the plugin settings if set; otherwise git uses your machine's git identity (`user.name` / `user.email`). If neither is configured, git will refuse to commit — set an author in settings or configure a global git identity.
Commits are authored with the **Author name/email** from the plugin settings if
set; otherwise git uses your machine's git identity (`user.name` /
`user.email`). If neither is configured, git will refuse to commit — set an
author in settings or configure a global git identity.
## Development
@@ -70,11 +92,13 @@ npm run build
npm test
```
Runs the Vitest suite (frontmatter parsing, slug derivation, image path logic, git helpers, publish pipeline).
Runs the Vitest suite (frontmatter parsing, slug derivation, image path logic,
git helpers, publish pipeline).
### E2E tests
The E2E suite boots the real Obsidian binary in a headless X display and drives it via the Chrome DevTools Protocol.
The E2E suite boots the real Obsidian binary in a headless X display and drives
it via the Chrome DevTools Protocol.
**Prerequisites:**
@@ -87,9 +111,14 @@ npm run e2e
```
The script:
1. Extracts the AppImage (once, cached).
2. Provisions a throwaway vault at `.obsidian-e2e/` with the plugin installed.
3. Launches Obsidian with `--remote-debugging-port` and connects Playwright over CDP.
4. Runs the smoke spec: plugin loads, command `jekyll-publish:publish-current-note` is registered, opening a note and executing the command shows a modal with heading "Publish to Jekyll".
3. Launches Obsidian with `--remote-debugging-port` and connects Playwright over
CDP.
4. Runs the smoke spec: plugin loads, command
`jekyll-publish:publish-current-note` is registered, opening a note and
executing the command shows a modal with heading "Publish to Jekyll".
The `.obsidian-e2e/` directory and Playwright `test-results/` are excluded from git.
The `.obsidian-e2e/` directory and Playwright `test-results/` are excluded from
git.