diff --git a/README.md b/README.md index 7179c9c..3a85083 100644 --- a/README.md +++ b/README.md @@ -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/-.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. ``` /.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 `/`. A single image is renamed to `.`; multiple images are renamed to `-1.`, `-2.`, … (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 `/`. A +single image is renamed to `.`; multiple images are renamed to +`-1.`, `-2.`, etc. -**per-post-folder** — images are copied into `//` preserving their original filenames. Keeps each post's images grouped together; suitable for posts with many images. +**per-post-folder** — images are copied into `//` 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.