notex.nvim/README.md

Notex.nvim

A relational document system for Neovim that brings Notion-like database capabilities to your markdown files. Vibe-coded with z.ai glm-4.6.

Features

• Relational Document Management: Index markdown files and query them like databases
• Custom Query Syntax: Simple, powerful query language for document discovery
• Virtual Buffers: Interactive query results displayed in Neovim buffers
• YAML Header Parsing: Automatically extract and index document metadata
• Real-time Updates: Automatic reindexing when files change
• Performance Optimized: Multi-tier caching system for fast queries
• Extensible: Plugin architecture for custom parsers and views

Quick Start

Installation

Using lazy.nvim (recommended):

{
  'your-username/notex.nvim',
  dependencies = {
    'nvim-lua/plenary.nvim',
    'nvim-tree/nvim-web-devicons'
  },
  config = function()
    require('notex').setup({
      -- Configuration options
      database_path = vim.fn.stdpath('data') .. '/notex/notex.db',
      auto_index = true,
      performance = {
        enable_caching = true,
        cache_size = 100
      }
    })
  end
}

Using packer.nvim:

use {
  'your-username/notex.nvim',
  requires = {
    'nvim-lua/plenary.nvim',
    'nvim-tree/nvim-web-devicons'
  },
  config = function()
    require('notex').setup({
      -- Configuration options
      database_path = vim.fn.stdpath('data') .. '/notex/notex.db',
      auto_index = true,
      performance = {
        enable_caching = true,
        cache_size = 100
      }
    })
  end
}

Using vim-plug:

Plug 'your-username/notex.nvim'
Plug 'nvim-lua/plenary.nvim'
Plug 'nvim-tree/nvim-web-devicons'

lua << EOF
require('notex').setup({
  database_path = vim.fn.stdpath('data') .. '/notex/notex.db',
  auto_index = true
})
EOF

Basic Usage

1. Index your workspace:

   :lua require('notex').index_workspace()
   

2. Run a query:

   :lua require('notex').show_query_prompt()
   

3. Example queries:

   FROM documents WHERE status = "published"
   FROM documents WHERE tags LIKE "project" ORDER BY updated_at DESC
   FROM documents WHERE created_at > "2023-01-01" LIMIT 20
   

Configuration

require('notex').setup({
  -- Database configuration
  database_path = nil, -- Defaults to stdpath('data')/notex/notex.db
  auto_index = true,    -- Auto-index markdown files on save
  index_on_startup = false, -- Index entire workspace on startup

  -- File handling
  max_file_size = 10 * 1024 * 1024, -- 10MB max file size

  -- Performance settings
  performance = {
    max_query_time = 5000, -- 5 seconds max query time
    cache_size = 100,      -- Number of cached queries
    enable_caching = true   -- Enable query caching
  },

  -- UI settings
  ui = {
    border = "rounded",    -- Window border style
    max_width = 120,       -- Max window width
    max_height = 30,       -- Max window height
    show_help = true       -- Show help in query results
  },

  -- Default view type
  default_view_type = "table" -- "table", "list", or "grid"
})

Query Syntax

Notex uses a simple, SQL-like query syntax designed for document discovery:

Basic Structure

FROM documents
WHERE <conditions>
ORDER BY <field> <direction>
LIMIT <number>

WHERE Conditions

-- Exact match
WHERE status = "published"

-- Partial match
WHERE tags LIKE "project"

-- Date comparison
WHERE created_at > "2023-01-01"
WHERE updated_at >= "2023-12-25"

-- Multiple conditions
WHERE status = "published" AND priority > 3
WHERE tags LIKE "urgent" OR status = "review"

Ordering

-- Ascending (default)
ORDER BY title

-- Descending
ORDER BY created_at DESC

-- Multiple fields
ORDER BY priority DESC, created_at ASC

Limiting Results

-- Limit number of results
LIMIT 10

-- Get most recent 5 documents
ORDER BY updated_at DESC LIMIT 5

Document Metadata

Notex automatically extracts metadata from YAML frontmatter in your markdown files:

---
title: "My Document"
status: "published"
priority: 5
tags: ["project", "urgent"]
due_date: "2023-12-25"
author: "John Doe"
---

# Document Content

Your markdown content goes here...

All YAML fields become queryable properties.

Keybindings

Default keybindings (can be customized):

• <leader>nq - Show new query prompt
• <leader>nr - Show recent queries
• <leader>ns - Show saved queries
• <leader>ni - Index current workspace
• <leader>nv - Switch view type
• <leader>ne - Export current view
• <leader>nc - Cleanup database

In query result buffers:

• <Enter> - Open document
• e - Toggle inline editing
• v - Change view type
• s - Save query
• r - Refresh results
• q - Close buffer

Query Results

Query results are displayed in virtual buffers with:

• Interactive tables: Sort, filter, and navigate results
• Document preview: Quick document information
• Inline editing: Edit document properties directly
• Export options: Save results as CSV, JSON, or Markdown

View Types

1. Table View: Structured data display
2. List View: Compact document list
3. Grid View: Card-based layout

API Reference

Core Functions

-- Execute a query
local result = require('notex').execute_query_and_show_results(query_string)

-- Index a directory
require('notex').index_directory(path, options)

-- Get document details
local details = require('notex.index').get_document_details(document_id)

-- Save a query
require('notex.query').save_query(name, query_string)

-- Get statistics
local stats = require('notex').get_statistics()

Query Engine

local query = require('notex.query')

-- Execute query
local result = query.execute_query(query_string)

-- Validate query syntax
local validation = query.validate_query_syntax(query_string)

-- Get suggestions
local suggestions = query.get_suggestions(partial_query, cursor_pos)

Index Management

local index = require('notex.index')

-- Index documents
local result = index.index_documents(directory_path, options)

-- Search documents
local results = index.search_documents(criteria)

-- Get index statistics
local stats = index.get_statistics()

-- Validate index
local validation = index.validate_index()

Performance

Notex is optimized for performance:

• Multi-tier caching: Memory, LRU, and timed caches
• Incremental indexing: Only process changed files
• Database optimization: SQLite with proper indexing
• Lazy loading: Load document details on demand

Cache Configuration

require('notex').setup({
  performance = {
    enable_caching = true,
    cache_size = 200,        -- Increase for better performance
    max_query_time = 10000   -- Allow longer queries for complex datasets
  }
})

Troubleshooting

Common Issues

1. Database locked errors:

   • Ensure you have proper file permissions
   • Check if another Neovim instance is using the database

2. Slow queries:

   • Increase cache_size in configuration
   • Use more specific WHERE conditions
   • Check database file size and consider cleanup

3. Missing documents in results:

   • Run :lua require('notex').index_workspace() to reindex
   • Check file permissions and YAML syntax

Debug Mode

Enable debug logging:

vim.g.notex_debug = true

Check logs at :lua print(vim.fn.stdpath('data') .. '/notex/notex.log')

Development

Running Tests

# Install dependencies
luarocks install busted
luarocks install luafilesystem

# Run tests
busted tests/

Project Structure

notex.nvim/
├── lua/notex/
│   ├── database/     # Database layer
│   ├── parser/       # Document parsing
│   ├── query/        # Query engine
│   ├── ui/           # User interface
│   ├── index/        # Document indexing
│   └── utils/        # Utilities
├── tests/
│   ├── unit/         # Unit tests
│   ├── integration/  # Integration tests
│   └── performance/  # Performance tests
└── specs/           # Specifications

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Update documentation
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Inspired by Notion's database functionality
• Built with lsqlite3 for database operations
• UI components based on Neovim's native buffer API
• Testing with busted

Support

• 🐛 Report bugs: GitHub Issues
• 💡 Feature requests: GitHub Discussions
• 📖 Documentation: Wiki

---

Made with ❤️ for the Neovim community