                                     ▒▓█▒░
                                    ▒█▓▓░▒░
                                   ██▓█▒▒▒▒
                                  ▒▓██▓░▒▒▒░
                                  ▓▒▒█▒▒░░░░
                                   ░▒▒░░░▒░
                                    ░▒▒▒▒░

                                   ⋅𝕭𝖆𝖘𝖆𝖑𝖙⋅

                      TUI Application to manage Obsidian
                 vaults and notes directly from the terminal.

───────────────────────────────────────────────────────────────────────────────
                                  %version-notice

DISCLAIMER

  Basalt is in its early stages, with a very limited set of features, and is
  therefore susceptible to changes. The experimental editor feature is disabled
  by default but can be enabled in the configuration file. When enabled, it
  provides a custom-built editor with limited capabilities for basic note
  modification.

  Quitting the application may feel a bit abrupt, as the application exits
  immediately after pressing ‹q›. I have some plans to handle this differently
  in the future. For example, through a series of button presses or by using
  command inputs similar to Vim's ‹:quit› or ‹:q›.

VAULT SELECTION

  On startup screen you can select the Vault you want to view. Any open vaults
  are shown with a ◆ symbol marker.

  DEFAULT KEY BINDINGS

    ‹q›,        Quit the application
    ‹Ctrl+C›
    ‹?›         Show this help
    ‹k›         Move selection up
    ‹j›         Move selection down
    ‹↩ Enter›   Select and open the highlighted vault

    ‹Tab›       Switch to next pane
    ‹Shift+Tab› Switch to previous pane

  The vault selection can be brought up as a modal by hitting ‹Ctrl+G› after
  the startup screen.

INTERFACE

  The application has two main panes: the Explorer (file browser) on the left
  and the Note Editor on the right. You can switch between these panes using
  the Tab key. The currently active pane will be highlighted and name of the
  active pane is displayed in the lower left corner of the application.

  EXPLORER PANE

    Browse and select notes from your vault.

    The explorer shows all notes and folders in your vault. You can navigate up
    and down through the list, and press Enter to select and view a note. The
    explorer panel can be toggled on/off to give more space to the note editor.

    Explorer panel can be expanded and hidden. The Explorer panel has a ⟹
    symbol indicator when it is expanded.

    DEFAULT KEY BINDINGS

      ‹q›,        Quit the application
      ‹Ctrl+C›
      ‹?›         Show this help
      ‹Esc›       Cancel/close modals
      ‹k / j›     Move selection up / down
      ‹↑ / ↓›     Move selection up / down
      ‹s›         Toggle note sorting
      ‹n›         Create new untitled note
      ‹N›         Create new untitled folder
      ‹r›         Rename selected note or directory
      ‹t›         Toggle explorer panel visibility
      ‹← / h›     Hide explorer panel
      ‹→ / l›     Expand explorer panel
      ‹↩ Enter›   Select and view the highlighted note

      ‹Tab›       Switch to next pane
      ‹Shift+Tab› Switch to previous pane

      ‹Ctrl+G›    Toggle vault selector modal
      ‹Ctrl+B›    Toggle explorer panel visibility
      ‹Ctrl+U›    Scroll up half a page
      ‹Ctrl+D›    Scroll down half a page

  OUTLINE PANE

    Browse and go to heading in a note.

    The outline shows all headings in the note. You can navigate up and down
    through the list, and press ‹Enter› to expand or collapse a heading. To
    move the cursor to the heading in the document press ‹g›. The outline pane
    can be toggled on/off to give more space to the note editor.

    DEFAULT KEY BINDINGS

      ‹q›,        Quit the application
      ‹Ctrl+C›

      ‹?›         Show this help
      ‹Esc›       Cancel/close modals
      ‹k / j›     Move selection up / down
      ‹↑ / ↓›     Move selection up / down
      ‹g›         Move editor cursor to currently selected heading
      ‹↩ Enter›   Expand or collapse heading

      ‹Tab›       Switch to next pane
      ‹Shift+Tab› Switch to previous pane

      ‹Ctrl+O›    Toggle outline pane visibility
      ‹Ctrl+G›    Toggle vault selector modal
      ‹Ctrl+B›    Toggle explorer pane visibility

  NOTE EDITOR PANE

    Read and navigate through your selected note. The note editor supports
    multiple modes when experimental editor is enabled.

    VIEW MODE (Default)

      View mode displays the rendered markdown content with navigation support.
      This is the default display mode for reading notes.

      DEFAULT KEY BINDINGS

        ‹q›         Quit the application
        ‹?›         Show this help
        ‹Esc›       Cancel/close modals
        ‹k / j›     Move cursor up / down
        ‹↑ / ↓›     Move cursor up / down
        ‹← / →›     Move cursor left / right (one character)
        ‹Alt+←›     Move cursor left by word
        ‹Alt+→›     Move cursor right by word
        ‹t›         Toggle explorer panel visibility

        ‹Tab›       Switch to next pane
        ‹Shift+Tab› Switch to previous pane

        ‹Ctrl+G›    Toggle vault selector modal
        ‹Ctrl+B›    Toggle explorer panel visibility
        ‹Ctrl+U›    Scroll up half a page
        ‹Ctrl+D›    Scroll down half a page

        EXPERIMENTAL EDITOR (when enabled):
        ‹i›         Enter edit mode
        ‹Shift+R›   Enter read mode
        ‹Ctrl+X›    Save note
        ‹Esc›       Exit current mode

    EDIT MODE (Experimental)

      Edit mode allows you to make changes to your note. The editor is built
      from scratch with limited capabilities. Single block editing is supported
      (navigating between blocks switches the active edit buffer).

      WARNING: Edit mode key mappings cannot be modified through configuration.

      SUPPORTED OPERATIONS:
        • Character insertion
        • Character deletion (backspace only)
        • Navigation (arrow keys, word jumping)
        • Newline insertion (Enter)

      EDITING COMMANDS

        ‹Backspace›              Delete character before cursor
        ‹Enter›                  Insert newline
        ‹Ctrl+E›                 Toggle to read mode
        ‹Esc›                    Exit edit mode

      CURSOR MOVEMENT

        ‹→›                      Move forward one character
        ‹←›                      Move backward one character
        ‹↑›                      Move up one line
        ‹↓›                      Move down one line
        ‹Alt+→›                  Move forward by word
        ‹Alt+←›                  Move backward by word

      LIMITATIONS:
        • No undo/redo support
        • No clipboard operations (copy/paste/cut)
        • No text selection
        • No multi-line deletion
        • No line/word deletion commands
        • No jumping to start/end of line or document

  INPUT MODAL

    The input modal appears when renaming notes or directories. It provides
    a text input field with basic editing capabilities.

    DEFAULT KEY BINDINGS

      ‹Esc›       Cancel and close modal without saving
      ‹↩ Enter›   Accept changes and save
      ‹i›         Enter edit mode for typing
      ‹h / l›     Move cursor left / right
      ‹← / →›     Move cursor left / right
      ‹Alt+F›     Move cursor forward by word
      ‹Alt+B›     Move cursor backward by word
      ‹Backspace› Delete character before cursor

    USAGE

      When renaming a note or directory from the explorer:
      1. Press ‹r› on the selected item
      2. The input modal will appear with the current name
      3. Press ‹i› to enter edit mode
      4. Modify the name as needed
      5. Press ‹Enter› to save or ‹Esc› to cancel

────────────────────────────────────────────────────────────────────────────

CONFIGURATION

  Basalt key mappings can be modified or extended by defining key mappings in
  the user configuration file. Each key mapping is associated with a specific
  'pane' and becomes active when that pane has focus. The global section
  applies to all panes and is evaluated first.

  The experimental editor feature is disabled by default. To enable editor
  functionality, set `experimental_editor = true` in your configuration file.

  Available commands are organized by pane:

  GLOBAL COMMANDS:
    quit, vault_selector_modal_toggle, help_modal_toggle

  SPLASH COMMANDS:
    splash_up, splash_down, splash_open

  EXPLORER COMMANDS:
    explorer_up, explorer_down, explorer_open, explorer_sort, explorer_toggle,
    explorer_new_untitled_note, explorer_new_untitled_folder,
    explorer_toggle_input_rename, explorer_switch_pane, explorer_scroll_up_one,
    explorer_scroll_down_one, explorer_scroll_up_half_page,
    explorer_scroll_down_half_page

  OUTLINE COMMANDS:
    outline_up, outline_down, outline_toggle, outline_toggle_explorer,
    outline_switch_pane_next, outline_switch_pane_previous outline_expand,
    outline_select

  NOTE EDITOR COMMANDS:
    note_editor_cursor_up, note_editor_cursor_down, note_editor_scroll_up_one,
    note_editor_scroll_down_one, note_editor_scroll_up_half_page,
    note_editor_scroll_down_half_page, note_editor_toggle_explorer,
    note_editor_switch_pane

  EXPERIMENTAL EDITOR COMMANDS:
    note_editor_experimental_set_edit_mode, note_editor_experimental_set_read_mode,
    note_editor_experimental_save, note_editor_experimental_exit_mode,
    note_editor_experimental_cursor_word_forward,
    note_editor_experimental_cursor_word_backward

  INPUT MODAL COMMANDS:
    input_modal_edit_mode, input_modal_accept, input_modal_cancel,
    input_modal_left, input_modal_right, input_modal_word_forward,
    input_modal_word_backward

  MODAL COMMANDS:
    help_modal_toggle, help_modal_close, help_modal_scroll_up_one,
    help_modal_scroll_down_one, help_modal_scroll_up_half_page,
    help_modal_scroll_down_half_page, vault_selector_modal_up,
    vault_selector_modal_down, vault_selector_modal_close,
    vault_selector_modal_open, vault_selector_modal_toggle

────────────────────────────────────────────────────────────────────────────

FEATURES

  • Navigate and read notes from any Obsidian Vault using terminal
  • Nested folders and notes are supported
  • Key bindings can be changed with configuration
  • View markdown notes in a readable, custom styled format
  • Toggle between focused note reading and vault exploration
  • Sort notes alphabetically
  • Create new notes and folders from the explorer
  • Rename notes and directories from the explorer
  • Input modal with text editing for interactive operations
  • Experimental editor mode for note modification (when enabled)
  • Multiple editor modes: View mode for reading, Edit mode for changes
  • Basic text editing capabilities in Edit mode (custom implementation)
  • Single block editing with character insertion and deletion

────────────────────────────────────────────────────────────────────────────

KNOWN LIMITATIONS

  • Images are not rendered
  • External links are not clickable
  • Markdown tables are not rendered properly
  • There is no syntax highlighting for code blocks
  • Markdown inline text styles are not rendered
  • Experimental editor is disabled by default and requires configuration
  • Edit mode key mappings cannot be customized
