Improve command naming for better intuitiveness and alignment with zk-nvim
Problem
The current command names are not intuitive and don't align well with zk-nvim's naming conventions. Several commands have cryptic suffixes or unclear purposes from their names alone.
Current Commands and Issues
Commands Needing Renaming:
-
:ZkNewTitleTand:ZkNewContentT- Issue: The "T" suffix is cryptic and unclear
-
Proposed:
:ZkNewFromTitleSelection→:ZkNewFromTitleSelectionWithTemplate(too long) OR better::ZkNewFromTitleand keep zk-nvim's as-is - Alternative: Make template selection a feature of existing commands via options
-
:ZkInsertSnippet- Current: Clear but could align better with zk-nvim patterns
- Proposed: Keep as-is (actually good name)
-
:ZkRemoveand:ZkRemovePick- Issue: "Remove" is ambiguous - could mean unlink/delete/archive
-
Proposed:
:ZkDeleteand:ZkDeletePickOR:ZkTrashand:ZkTrashPick
-
:ZkNewFromTemplate-
Issue: Redundant with
:ZkNewwhich already accepts a template parameter -
Proposed: Remove command, document using
:ZkNew { template = "name" }instead -
Alternative: Keep as convenience command but rename to
:ZkPickTemplate
-
Issue: Redundant with
-
:ZkSlides- Issue: Unclear what this does (present? create? export?)
-
Proposed:
:ZkPresentor:ZkPresentSlides
-
:ZkUpdate-
Current: Aligns well with zk CLI (
zk update) - Proposed: Keep as-is (good name)
-
Current: Aligns well with zk CLI (
-
Integration Commands (
:ZkOrphans,:ZkRecents,:ZkPinned,:ZkHub,:ZkLast)- Current: Clear and intuitive
- Proposed: Keep as-is (good names)
Recommended Changes
High Priority (Breaking Changes):
ZkNewTitleT → ZkNewFromTitle (shorter, clearer)
ZkNewContentT → ZkNewFromContent (shorter, clearer)
ZkRemove → ZkDelete (more explicit)
ZkRemovePick → ZkDeletePick (more explicit)
ZkSlides → ZkPresent (clearer purpose)
Medium Priority (Consider):
ZkNewFromTemplate → ZkPickTemplate (or remove entirely)
ZkInsertSnippet → ZkSnippet (shorter, still clear)
Keep As-Is:
ZkUpdate ✓ (aligns with zk CLI)
ZkOrphans ✓ (clear and intuitive)
ZkRecents ✓ (clear and intuitive)
ZkPinned ✓ (clear and intuitive)
ZkHub ✓ (clear and intuitive)
ZkLast ✓ (clear and intuitive)
Implementation Considerations
- Backward Compatibility: Create deprecated aliases for old commands
- Documentation: Update all docs with new names
- Migration Guide: Provide clear migration path for users
- Config Keys: Update config keys to match new names
zk-nvim Command Pattern Reference
For comparison, zk-nvim uses these patterns:
-
Zk + Action(ZkNew, ZkIndex, ZkCd) -
Zk + Action + Target(ZkInsertLink, ZkNewFromTitleSelection) -
Zk + Noun(ZkNotes, ZkTags, ZkBacklinks, ZkLinks)
We should follow similar patterns for consistency.
Proposed Config Structure After Rename
require('zk-extras').setup({
commands = {
ZkDelete = true, -- was ZkRemove
ZkDeletePick = true, -- was ZkRemovePick
ZkSnippet = true, -- was ZkInsertSnippet
ZkPickTemplate = true, -- was ZkNewFromTemplate
ZkNewFromTitle = true, -- was ZkNewTitleT
ZkNewFromContent = true, -- was ZkNewContentT
ZkPresent = true, -- was ZkSlides
ZkUpdate = true,
ZkIntegration = true, -- ZkOrphans, ZkRecents, etc.
}
})