nuwiki/development/calendar-vim-integration.md

Calendar-Vim Integration Use Case Specification

Overview

This document describes how nuwiki (vimwiki) integrates with calendar-vim to provide graphical calendar navigation for wiki diary entries.

Integration Mechanism

Nuwiki auto-detects calendar-vim on the runtimepath (via a FileType vimwiki autocmd in plugin/nuwiki.vim) and wires calendar-vim's hook variables, unless the integration is disabled (default: enabled):

• g:calendar_action = 'vimwiki#diary#calendar_action'
• g:calendar_sign = 'vimwiki#diary#calendar_sign'

These hooks are only set when unset or still at calendar-vim's own defaults (calendar#diary / calendar#sign), so a user-chosen custom hook is preserved.

Primary Use Case: Viewing/Create Diary Entries

1. User executes :Calendar command
2. Calendar-vim displays navigable calendar interface
3. User navigates to target date using arrow keys
4. User presses <Enter> on selected date
5. vimwiki#diary#calendar_action function executes:
   • Formats date as YYYY-MM-DD
   • Opens existing diary file or creates new one (split/vsplit per dir)
   • Applies the vimwiki filetype to a brand-new entry
   • Closes the calendar window once the diary entry is open
6. User views/edits diary entry for selected date

Date Marking Functionality

• vimwiki#diary#calendar_sign function determines which dates show markers (*)
• Returns true if diary file exists for that date using wiki's path configuration
• Provides visual indication of dates with existing diary entries

Key Features

• Seamless navigation between calendar and diary entries
• Automatic file creation/opening for selected dates
• Visual indicators for dates with existing content
• Proper window splitting based on calendar orientation
• Calendar window closed automatically once the diary entry opens

Configuration

Controlled by:

• use_calendar Lua option (Neovim setup()), default true
• g:nuwiki_use_calendar / g:nuwiki_no_calendar (VimL global toggles)
• Individual wiki configurations in g:nuwiki_wikis (root, diary_rel_path, file_extension), or the scalar g:nuwiki_wiki_root / g:nuwiki_diary_rel_path / g:nuwiki_file_extension fallbacks
• Standard calendar-vim variables for appearance/customization

This integration leverages calendar-vim's strong date presentation while using nuwiki's diary system for file management, creating a cohesive experience for journal-style wiki usage.