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 activates the integration by setting calendar-vim's hook variables when g:vimwiki_use_calendar is enabled (default: true):

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

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
   • Applies appropriate wiki filetype
   • Sets up autocmd to refresh calendar on file close
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
• Automatic calendar refresh after editing diary entries

Configuration

Controlled by:

• g:vimwiki_use_calendar (global toggle)
• Individual wiki configurations in g:vimwiki_list (path, diary_rel_path, ext)
• 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.