Update README
This commit is contained in:
81
README.md
81
README.md
@@ -1,13 +1,17 @@
|
|||||||
# Obsidian Jekyll Publish
|
# 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
|
## What it does
|
||||||
|
|
||||||
1. Opens a "Publish to Jekyll" modal for the currently active markdown file.
|
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.
|
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.
|
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.
|
5. Copies any embedded images according to the selected strategy.
|
||||||
6. Commits and pushes to your configured remote and branch.
|
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/
|
<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
|
## Settings
|
||||||
|
|
||||||
| Setting | Description | Default |
|
| Setting | Description | Default |
|
||||||
|---|---|---|
|
|-------------------------|-----------------------------------------------------|----------------------|
|
||||||
| Remote URL | Git remote URL for your Jekyll site (HTTPS or SSH) | _(empty)_ |
|
| Remote URL | Git remote URL for your Jekyll site (HTTPS or SSH) | _(empty)_ |
|
||||||
| Branch | Branch to push to | `main` |
|
| Branch | Branch to push to | `main` |
|
||||||
| Posts directory | Destination directory inside the repo | `_posts` |
|
| Posts directory | Destination directory inside the repo | `_posts` |
|
||||||
| Images directory | Where images are copied inside the repo | `assets/img` |
|
| Images directory | Where images are copied inside the repo | `assets/img` |
|
||||||
| Default image strategy | `flat-slug` or `per-post-folder` (see below) | `flat-slug` |
|
| Default image strategy | `flat-slug` or `per-post-folder` (see below) | `flat-slug` |
|
||||||
| Preset frontmatter | Key/value pairs always injected into every post | _(empty)_ |
|
| Preset frontmatter | Key/value pairs always injected into every post | _(empty)_ |
|
||||||
| Commit message template | Template; `{{title}}` is replaced by the note title | `Publish: {{title}}` |
|
| Commit message template | Template; `{{title}}` is replaced by the note title | `Publish: {{title}}` |
|
||||||
| Author name | Git author name for commits | _(empty)_ |
|
| Author name | Git author name for commits | _(empty)_ |
|
||||||
| Author email | Git author email for commits | _(empty)_ |
|
| Author email | Git author email for commits | _(empty)_ |
|
||||||
|
|
||||||
## Image strategies
|
## 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
|
## 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).
|
- **HTTPS remotes** — git uses your configured credential helper: **Git
|
||||||
- **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.
|
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
|
## Development
|
||||||
|
|
||||||
@@ -70,11 +92,13 @@ npm run build
|
|||||||
npm test
|
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
|
### 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:**
|
**Prerequisites:**
|
||||||
|
|
||||||
@@ -87,9 +111,14 @@ npm run e2e
|
|||||||
```
|
```
|
||||||
|
|
||||||
The script:
|
The script:
|
||||||
|
|
||||||
1. Extracts the AppImage (once, cached).
|
1. Extracts the AppImage (once, cached).
|
||||||
2. Provisions a throwaway vault at `.obsidian-e2e/` with the plugin installed.
|
2. Provisions a throwaway vault at `.obsidian-e2e/` with the plugin installed.
|
||||||
3. Launches Obsidian with `--remote-debugging-port` and connects Playwright over CDP.
|
3. Launches Obsidian with `--remote-debugging-port` and connects Playwright over
|
||||||
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".
|
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.
|
||||||
|
|||||||
Reference in New Issue
Block a user