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.