Contributing to obsidian.nvim

Thanks for considering contributing! Please read this document to learn the various steps you should take before submitting a pull request.

TL;DR

• Start an issue to discuss the planned changes
• To submit a pull request
  • Start developing your feature in a branch
  • Make sure that your codes complies the obsidian.nvim code style, run make chores
  • The PR should contain
    • The code changes
    • Tests for the code changes
    • Documentation for the code changes (in the code itself and in the README.md)
    • CHANGELOG.md entry for the code changes

Details

Note: we automate tedious tasks using a Makefile in the root of the repository. Just call make to see what you can do, or make chores to run the most important tasks on your code.

If you don't want to install the dependency need for some of the checks, you can also just open a PR to leverage GitHub actions for the check.

Keeping the CHANGELOG.md up-to-date

This project maintains a CHANGELOG with a format based on Keep a Changelog.

If your PR addresses a bug or makes any other substantial change, please be sure to add an entry under the "Unreleased" section at the top of CHANGELOG.md. Entries should always be in the form of a list item under a level-3 header of either "Added", "Fixed", "Changed", or "Removed" for the most part. If the corresponding level-3 header for your item does not already exist in the "Unreleased" section, you should add it.

Formatting code

TL;DR: make style

Lua code should be formatted using StyLua. Once you have StyLua installed, you can run make style to automatically apply styling to all of the Lua files in this repo.

Linting code

TL;DR: make lint

• We use selene to lint the Lua code and typos to catch typos.
• Once you have selene and typos installed, you can run make lint to get a report.

Checking types

TL;DR: make types

• We use EmmyLua Analyzer Rust to check the type annotations in the lua code.
• Contributions should have type annotations.

Running tests

TL;DR: make test

• Tests are written in the tests/ folder and are run using mini.test. The make command will download the dependencies for you.
  • For a reference of using mini.test, see this guide.
• For async tests, use the helpers in tests/helpers.lua:
  • h.child_await(child, lua, { desc = "..." }) for callback-style child-Neovim async code.
  • h.child_wait(child, lua, { desc = "..." }) or focused helpers like h.child_wait_for_buf_name() for eventual child state.
  • Avoid raw vim.wait() and fixed sleeps in tests; always wait for a specific condition with a timeout message.

Building the vim user documentation

TL;DR: make user-docs

• The Vimdoc help lives at doc/obsidian.txt, which is automatically generated from the README.md using markdoc
• Please only commit documentation changes to the README.md, not doc/obsidian.txt.
• This step don't need to be done locally since CI will auto run.

Building the vim API documentation

TL;DR: make api-docs

• The API docs lives in doc/obsidian_api.txt and is generated from the source code using mini.docs.
• This step don't need to be done locally since CI will auto run.

Contribute to the user wiki

See Edit user wiki