DOCSEARCHbyAlgolia
Submit Docs

obsidiantools Documentation

repository·main·Indexed 20 days ago

https://github.com/mfarragher/obsidiantools

A Python package for extracting structured metadata and content from Obsidian.md vaults. It provides tools for network analysis via NetworkX, statistical summaries using Pandas DataFrames, and text extraction for NLP tasks. The library supports retrieving front matter, tags, LaTeX math, and canvas file data, while also identifying orphan files and broken links within a vault.

Tokens
984
Snippets
4
Records
8
Agent score
19%

What's inside obsidiantools

  1. Analyze vault structure with NetworkX

    main

    The vault.graph attribute provides access to a networkx graph of your entire vault. This allows you to perform sophisticated network analysis or export the graph to other data formats. When instantiating the Vault, you can filter the analysis to specific subdirectories.

    # Access the NetworkX graph
graph = vault.graph

  2. Initialize a Vault object

    main

    To begin analyzing your Obsidian vault, import obsidiantools.api and use the fluent interface to connect and gather data.

    • connect(): Builds a graph structure of your notes and metadata (links, backlinks, etc.). You can optionally include 'attachment' files in the graph.
    • gather(): Extracts plaintext content from your notes. You can pass arguments to specify which text to remove (e.g., code blocks).

    Note: The package supports the 'shortest path when possible' option for links, which covers most standard Obsidian vaults.

    import obsidiantools.api as otools

# Replace <VAULT_DIRECTORY> with the path to your Obsidian vault
vault = otools.Vault(<VAULT_DIRECTORY>).connect().gather()

  4. Inspect Obsidian Canvas files

    main

    For Obsidian Canvas files, you can access the underlying data structure:

    • vault.canvas_content_index: A dictionary containing the JSON content of each canvas file.
    • vault.canvas_graph_detail_index: A dictionary containing data required to recreate the layout of content within a canvas file.

  5. Access backlinks and links

    main

    You can inspect the relationship between notes using these methods:

    • vault.backlinks_index: A collection of all backlinks in the vault.
    • vault.get_backlinks(<NOTE>): Retrieves the backlinks for a specific note.

    Supported link types include Wikilinks (including header links and alt text), Embedded files, Backlinks, and standard Markdown links.

  6. Retrieve note metadata and content

    main

    The vault object provides several ways to inspect individual notes and their properties:

    Metadata Indices

    • md_file_index: Index of Markdown files.
    • media_file_index: Index of media files.
    • canvas_file_index: Index of canvas files.

    Note Content & Properties

    • vault.get_front_matter(<NOTE>): Retrieves front matter for a specific note.
    • vault.front_matter_index: Access all front matter via an index.
    • vault.get_tags(<NOTE>): Retrieves tags for a note (supports nested tags).
    • vault.tags_index: Access all tags via an index.
    • vault.get_math(<NOTE>): Retrieves LaTeX math from a note.
    • vault.math_index: Access all math via an index.

    Text Extraction (Requires gather())

    • vault.get_source_text(<NOTE>): Returns the 'source text' representing how the note appears in Obsidian's 'source mode'.
    • vault.get_readable_text(<NOTE>): Returns reduced markdown text (preserving paragraphs, headers, etc.) optimized for NLP analysis.

  7. Get summary statistics as Pandas DataFrames

    main

    You can retrieve summary statistics for different file types in your vault as Pandas DataFrames using the following methods:

    • vault.get_note_metadata(): Metadata for Markdown (.md) files.
    • vault.get_media_file_metadata(): Metadata for media files embedded in notes.
    • vault.get_canvas_file_metadata(): Metadata for Obsidian Canvas files.
    # Example: Get metadata for all notes
df_notes = vault.get_note_metadata()

  8. Identify orphans and broken links

    main

    Use the following attributes to find files that are disconnected or have broken references:

    Nonexistent Files (Broken Links)

    • vault.nonexistent_notes
    • vault.nonexistent_media_files
    • vault.nonexistent_canvas_files

    Isolated Files (Orphans)

    • vault.isolated_notes
    • vault.isolated_media_files
    • vault.isolated_canvas_files