192 lines
No EOL
4 KiB
Markdown
192 lines
No EOL
4 KiB
Markdown
# Quickstart Guide: Notex Relational Document System
|
|
|
|
## Installation
|
|
|
|
1. Install the plugin using your preferred Neovim plugin manager
|
|
2. Ensure SQLite is available on your system
|
|
3. Restart Neovim to load the plugin
|
|
|
|
## Initial Setup
|
|
|
|
### 1. Index Your Documents
|
|
```vim
|
|
"Notex will automatically scan for markdown files in your workspace
|
|
"You can also manually trigger indexing:
|
|
:NotexIndex /path/to/your/documents
|
|
```
|
|
|
|
### 2. Create Your First Query
|
|
Open a markdown file and add a query block:
|
|
|
|
```markdown
|
|
# My Project Dashboard
|
|
|
|
```notex-query
|
|
status: "active"
|
|
priority: "high"
|
|
ORDER BY created_at DESC
|
|
```
|
|
```
|
|
|
|
### 3. View Query Results
|
|
- Hover over the query block with your cursor
|
|
- Press `<leader>q` to open the query in a virtual buffer
|
|
- The results will show all matching documents in a table format
|
|
|
|
## Basic Usage
|
|
|
|
### Querying Documents
|
|
|
|
#### Simple Property Filter
|
|
```markdown
|
|
```notex-query
|
|
status: "draft"
|
|
```
|
|
```
|
|
|
|
#### Multiple Properties
|
|
```markdown
|
|
```notex-query
|
|
status: "active"
|
|
priority: "high"
|
|
tags: ["urgent", "review"]
|
|
```
|
|
```
|
|
|
|
#### Advanced Filtering
|
|
```markdown
|
|
```notex-query
|
|
FROM priority: "high"
|
|
WHERE created_at >= "2024-01-01"
|
|
ORDER BY due_date ASC
|
|
LIMIT 10
|
|
```
|
|
```
|
|
|
|
### Working with Query Results
|
|
|
|
#### Open Documents
|
|
- Move cursor to any row in the results table
|
|
- Press `<Enter>` to open the document in a new split
|
|
- Press `o` to open in a new tab
|
|
|
|
#### Edit Properties
|
|
- Press `e` on any result row to enter edit mode
|
|
- Change property values directly in the table
|
|
- Press `<Enter>` to save changes to the source document
|
|
|
|
#### Save Queries
|
|
- Press `s` to save the current query for reuse
|
|
- Give your query a name like "My Active Tasks"
|
|
- Access saved queries with `:NotexQueries`
|
|
|
|
## Document Properties
|
|
|
|
### YAML Header Format
|
|
```yaml
|
|
---
|
|
title: "Project Documentation"
|
|
status: "active"
|
|
priority: "high"
|
|
tags: ["documentation", "project"]
|
|
created_at: "2024-03-15"
|
|
due_date: "2024-04-01"
|
|
assignee: "john@example.com"
|
|
progress: 75
|
|
---
|
|
```
|
|
|
|
### Supported Property Types
|
|
- **Text**: "draft", "documentation", "john@example.com"
|
|
- **Numbers**: 75, 1.5, -10
|
|
- **Booleans**: true, false
|
|
- **Dates**: "2024-03-15", "2024-03-15T10:30:00Z"
|
|
- **Arrays**: ["tag1", "tag2"], [1, 2, 3]
|
|
|
|
## Advanced Features
|
|
|
|
### Query Conditions
|
|
```markdown
|
|
```notex-query
|
|
WHERE priority > 5 AND status != "archived"
|
|
WHERE tags INCLUDES "urgent"
|
|
WHERE created_at BEFORE "2024-01-01"
|
|
WHERE title CONTAINS "important"
|
|
```
|
|
```
|
|
|
|
### Grouping and Aggregation
|
|
```markdown
|
|
```notex-query
|
|
GROUP BY status
|
|
ORDER BY priority DESC
|
|
```
|
|
```
|
|
|
|
### Custom Query Shortcuts
|
|
Add to your Neovim config:
|
|
```vim
|
|
lua
|
|
vim.keymap.set('n', '<leader>qt', ':NotexQuery<CR>')
|
|
vim.keymap.set('n', '<leader>qr', ':NotexRefresh<CR>')
|
|
vim.keymap.set('n', '<leader>qs', ':NotexSaveQuery<CR>')
|
|
```
|
|
|
|
## Testing Your Setup
|
|
|
|
### 1. Create Test Documents
|
|
Create two markdown files with YAML headers:
|
|
|
|
`doc1.md`:
|
|
```yaml
|
|
---
|
|
title: "First Document"
|
|
status: "draft"
|
|
priority: "high"
|
|
tags: ["test"]
|
|
---
|
|
```
|
|
|
|
`doc2.md`:
|
|
```yaml
|
|
---
|
|
title: "Second Document"
|
|
status: "review"
|
|
priority: "medium"
|
|
tags: ["test", "review"]
|
|
---
|
|
```
|
|
|
|
### 2. Create Test Query
|
|
```markdown
|
|
```notex-query
|
|
tags: "test"
|
|
```
|
|
```
|
|
|
|
### 3. Verify Results
|
|
The query should return both documents in a table format.
|
|
|
|
## Troubleshooting
|
|
|
|
### Query Not Working
|
|
- Check that YAML headers are properly formatted with `---` delimiters
|
|
- Ensure property names in queries match exactly with YAML keys
|
|
- Verify that documents have been indexed (`:NotexStatus`)
|
|
|
|
### Performance Issues
|
|
- Use more specific filters to reduce result sets
|
|
- Consider adding `LIMIT` to large queries
|
|
- Check `:NotexStatus` for indexing performance metrics
|
|
|
|
### File Not Found Errors
|
|
- Ensure file paths in your workspace are accessible
|
|
- Check file permissions for read/write access
|
|
- Run `:NotexReindex` to refresh the document database
|
|
|
|
## Next Steps
|
|
|
|
- Explore the query syntax documentation for advanced filtering
|
|
- Set up custom query templates for common workflows
|
|
- Integrate with your existing Neovim workflow and plugins
|
|
- Share queries with your team for consistent document management |