Host integration

A host repository needs content, .github/jekyll-obsidian.yml, and a Pages workflow. The jekyll-obsidian-site gem supplies the compiler, themes, and prebuilt frontend assets. Its executable is jekyll-obsidian.

Deploy without installing a toolchain

Copy the configuration example to .github/jekyll-obsidian.yml and the Pages workflow to .github/workflows/pages.yml.

title: My Site
website:
  source: docs
  theme: minimal

Add a Markdown note with publish: true in docs/. Select Settings > Pages > Build and deployment > Source > GitHub Actions, then commit and push. Actions installs Ruby and the matching gem version; your computer does not need Ruby or Node.js.

website.source is relative to your repository root. docs/, website/docs/, and nested directories with spaces or Unicode names are supported. The project's own documentation lives in website/jekyll-obsidian-docs/ and is excluded from the gem.

Initialize locally

Install Ruby 4.0.x on macOS, Linux, or WSL, then run these commands from your repository root:

gem install jekyll-obsidian-site
jekyll-obsidian init --source website/docs --theme docs
jekyll-obsidian dev

init creates the configuration and Pages workflow. It creates a public welcome note only if the content directory is missing or empty. Repeating the same initialization leaves matching files unchanged; a conflict is reported before any files are written. For an existing configuration or workflow, edit the files directly using the examples above.

All configuration entries are editable, including source and theme. Changes take effect on the next build. See Customization for publication defaults and features.

Use Bundler

For a project with a Gemfile:

source "https://rubygems.org"
gem "jekyll-obsidian-site", "0.2.1"

bundle install
bundle exec jekyll-obsidian init --source docs
bundle exec jekyll-obsidian dev

Commit Gemfile and Gemfile.lock to pin dependencies for both local builds and the Action. When both files exist at the repository root, the Action installs the locked bundle in frozen mode and runs the CLI through bundle exec. It never generates or updates your lockfile. The locked jekyll-obsidian-site version must match the Action release.

With neither file, the Action installs its exact builder gem version directly. Indirect dependencies then follow the gem's version constraints. Having only one of the two files, omitting the builder from the lockfile, or locking a different builder version is an error. Keep the Action reference, Gemfile, and lockfile aligned when upgrading.

An existing Jekyll _config.yml and its plugins are not loaded by this tool.

Update

Change uses: wowfun/jekyll-obsidian@v0.2.1 in the workflow to the desired release tag. The Action installs that release's exact gem version.

For a direct installation, use gem update jekyll-obsidian-site. For Bundler, adjust the version constraint when necessary, run bundle update jekyll-obsidian-site, and commit the lockfile. Package updates do not rewrite host content or configuration.

The earlier copied-workspace installation is not supported by this release. Preserve your content and .github/jekyll-obsidian.yml, remove its managed-marker comments, replace the old workflow, and remove the old implementation files. Keep any user-authored files under website/.

Preview and build

jekyll-obsidian dev serves http://127.0.0.1:58000/ and watches content and configuration. Failed rebuilds preserve the last successful output.

jekyll-obsidian build --url https://example.com --baseurl /project
jekyll-obsidian clean

The built site is .jekyll-obsidian-cache/site/. clean removes the tool's cached state and output while retaining notes, configuration, installed dependencies, and unrelated _site/ directories. The installed gem is read-only during use.

Troubleshooting

• Missing configuration: run init in the repository root, or add the two example files.
• No public notes: add YAML boolean publish: true, or explicitly configure website.content.publish_by_default.
• Existing files conflict with init: edit those files directly; the command does not overwrite them.
• Installation selects a different project: the gem name is jekyll-obsidian-site, while the command name is jekyll-obsidian.
• Source or cache path contains a symbolic link: select a real directory inside the repository.