ovault 0.0.9

Library for Managing your Obsidian Vault

OVault

A python library for accessing and editing your Obsidian vault.

[!WARNING] This library can easily make large changes to your vault which may be difficult to reverse. Make sure to have a backup of your vault before using OVault to modify it.

Check out the examples!

Code Example

import ovault

# Open a vault at a given path
vault = ovault.Vault("test-vaults/simple_vault")

print("Vault Path  :", vault.path)
print("Notes       :", len(vault.notes()))
print("Attachments :", len(vault.attachments()))
print("Tags        :", sorted(vault.tags()))
print()

# Get the note named 'first_note'
note = vault.note("first_note")

print("Note Name   :", note.name)
print("Note Path   :", note.path)
print("Note Tokens :", note.tokens())

Output:

Vault Path  : /home/balder/projects/ovault/test-vaults/simple_vault
Notes       : 11
Attachments : 3
Tags        : ['callout4youtag', 'frontmatter-tag1', 'frontmatter-tag2', 'linksaregood']

Note Name   : first_note
Note Path   : first_note.md
Note Tokens : [Header(# FIRST NOTE!), Text(Wuhuuuuuuuuuuu!Thi...), InternalLink(second note), Text(.Takes a look at t...), InternalLink(sub/todo), Text()]

Included Utilities

OVault includes runnable modules for common tasks. Get an overview by running the ovault module:

python -m ovault

Output:

OVault provies a few utilties out of the box.

You can run them like so: `python3 -m ovault.<module>`

Available modules:
    ovault.mv                     : Rename a file within an Obsidian vault, updating all links accordingly.
    ovault.help                   : Show a list of all utility modules included in `ovault`.
    ovault.check_links            : Check all external links to websites in an Obsidian vault and report any broken links.
    ovault.name_pasted_images     : Rename pasted images in the vault based on the note they are pasted into.
    ovault.filename_compatibility : Check filenames for compatibility across different operating systems.
    ovault.info                   : Show information about an Obsidian vault.

Install

pip install ovault

or locally

git pull https://github.com/BalderHolst/ovault
cd ovault
pip install .

Features

Vault Management

Indexing

• Indexing: Automatically indexes all notes and attachments within the vault upon initialization.
• Ignored Files: Respects and parses .vault-ignore files to exclude specified paths during indexing.
• Dangling Links: Identify and list links within your notes that point to non-existent files.

Note Handling

Access & Properties

• Access Notes & Attachments: Retrieve all notes or attachments in the vault as Python objects.
• Frontmatter Extraction: Manipulate YAML frontmatter from notes.

Modification

• Dynamic Note Modification: Programmatically insert or replace parts of a note

Tag Management

Querying Tags

• List All Tags: Get a complete list of tags present in your vault.
• Filter by Tag: Retrieve all notes associated with a specific tag.

Markdown Parsing & Tokenization

Token Representation

• Rich Token Representation: Notes are parsed into a detailed stream of Token objects, representing various markdown elements.
• Available Tokens:
  • Plain Text: This is text
  • Headers: (# Heading)
  • Internal Links: ([[Note Name]], ![[Image.png]])
  • External Links: ([link text](url), ![image alt](url))
  • Tags: (#tag)
  • Code Blocks: (fenced code, inline code)
  • Quotes: (> Quote)
  • Math: ($inline$ and $$display$$ LaTeX)
  • Dividers: (---)
  • Callouts: (> [!type] Title)
  • Frontmatter: (YAML metadata)
  • List: - item 1\n- item 2
  • NumericList: 1. first\n2. second
  • CheckList: - [x] done\n- [ ] not done
  • TemplaterCommand: (<% code goes here %>)

See lexer/tokens.rs for token definitions.

Contributing

I would be more than happy if anyone finds this useful enough to add to, or modify this code.

Development

Install ovault and development dependencies with

pip install -e ".[dev]"

or use the nix flake

nix develop

Build for Testing

maturin develop --release --features python

Test

./scripts/test.sh

Build Documentation

./scripts/build-docs.py

Release

1. Bump version in Cargo.toml
2. Commit change and push
3. Merge dev into main and push
4. Create a git tag with the same version: git tag <version>
5. Push new tag: git push --tags