Usage Guide

This guide provides detailed examples and workflows for using the Seeder Tool effectively.

Basic Workflows

Creating a Simple Note

Goal: Create a basic note with minimal configuration

bun run tools/seeder/src/index.ts

1. Select "🌱 Seed a new note"
2. Enter title: My Note
3. Enter date: 06-11-2024
4. Choose content source: "Paste markdown content"
5. Enter content in editor
6. Pin? No
7. Folder? No
8. Custom position? No
9. Link tasks? No

Result: Note created at end of root folder

Creating a Pinned Note

Goal: Create a note pinned to the top

bun run tools/seeder/src/index.ts

1. Select "🌱 Seed a new note"
2. Enter title: Important Note
3. Enter date: 06-11-2024
4. Choose content source: "From .md or .mdx file"
5. Enter file path: ./docs/important.md
6. Pin? Yes ✓

Result: Note pinned at position 0, cannot be in folder

Creating a Note in a Folder

Goal: Organize note in a specific folder

bun run tools/seeder/src/index.ts

1. Select "🌱 Seed a new note"
2. Enter title: Project Notes
3. Enter date: 06-11-2024
4. Choose content source: "From .md or .mdx file"
5. Enter file path: ./notes/project.md
6. Pin? No
7. Place in folder? Yes ✓
8. Select folder: Projects → Frontend
9. Custom position? No

Result: Note created at end of selected folder

Creating a Note at Custom Position

Goal: Insert note at specific position

bun run tools/seeder/src/index.ts

1. Select "🌱 Seed a new note"
2. Enter title: Inserted Note
3. Enter date: 06-11-2024
4. Choose content source: "Paste markdown content"
5. Enter content
6. Pin? No
7. Place in folder? No
8. Custom position? Yes ✓
9. Enter position: 5

Result: Note inserted at position 5, other notes shifted

Linking Tasks to a Note

Goal: Connect existing tasks to a note

bun run tools/seeder/src/index.ts

1. Select "🌱 Seed a new note"
2. Enter title: Task List
3. Enter date: 06-11-2024
4. Choose content source: "Paste markdown content"
5. Enter content
6. Pin? No
7. Folder? No
8. Custom position? No
9. Link tasks? Yes ✓
10. Select tasks: [x] Task 1, [x] Task 2

Result: Note created with linked tasks

Advanced Workflows

Moving a Note to Different Folder

Goal: Reorganize existing notes

bun run tools/seeder/src/index.ts

1. Select "📦 Move/reposition an existing note"
2. Select note: My Note
3. Select target folder: Archive → 2024
4. Select position: End

Result: Note moved to archive folder at end

Repositioning a Note

Goal: Change note order without moving folder

bun run tools/seeder/src/index.ts

1. Select "📦 Move/reposition an existing note"
2. Select note: Project Notes
3. Select target folder: (same folder)
4. Select position: After "Another Note"

Result: Note repositioned within same folder

Moving Note to Top

Goal: Bring note to front

bun run tools/seeder/src/index.ts

1. Select "📦 Move/reposition an existing note"
2. Select note: Important Note
3. Select target folder: Root (no folder)
4. Select position: Top (position 0)

Result: Note moved to position 0, other notes shifted

Content Management

Importing from Markdown Files

Best Practice: Keep your markdown files organized

# Project structure
notes/
├── projects/
│   ├── frontend.md
│   └── backend.md
├── docs/
│   └── api.md
└── personal/
    └── ideas.md

Usage:

1. Choose "From .md or .mdx file"
2. Enter path: ./notes/projects/frontend.md
3. Content is automatically loaded

Using Editor Mode

Best Practice: For longer content

1. Choose "Paste markdown content"
2. Editor opens (uses $EDITOR or default)
3. Write/paste content
4. Save and close
5. Content is imported

Tip: Set your preferred editor:

export EDITOR=cursor  # or vim, nano, etc.

Folder Organization

Understanding Folder Trees

The seeder displays folders in a tree structure:

Root (no folder)
  Projects
    Frontend
    Backend
  Archive
    2024
    2023

Indentation shows nesting level:

• No indent = Root level
• 2 spaces = First level
• 4 spaces = Second level
• etc.

Organizing Notes by Topic

Workflow:

1. Create notes with descriptive titles
2. Group related notes in folders
3. Use consistent naming
4. Maintain hierarchy

Example Structure:

Projects/
├── Frontend/
│   ├── React Notes
│   └── Vue Notes
└── Backend/
    ├── API Design
    └── Database Schema

Date Management

Using Dutch Date Format

Format: dd-mm-yyyy

Examples:

• 06-11-2024 = November 6, 2024
• 01-01-2024 = January 1, 2024
• 31-12-2023 = December 31, 2023

Validation:

• Must be valid date
• Month 01-12
• Day valid for month
• Year 4 digits

Historical Dates

You can create notes with past dates:

? Created at date (dd-mm-yyyy): 01-01-2020

Useful for:

• Migrating old content
• Backdating notes
• Historical documentation

Task Linking

Understanding Task Relationships

Important: Tasks link TO notes, not the reverse.

When you link tasks to a note:

• Tasks reference the note
• Note doesn't reference tasks directly
• Multiple tasks can link to one note
• One task can link to multiple notes

Linking Multiple Tasks

Workflow:

1. Create note first
2. Select "Link tasks" option
3. Choose multiple tasks from list
4. All selected tasks link to note

Use Cases:

• Project task lists
• Meeting action items
• Checklist notes
• Todo collections

Position Management

Understanding Positions

Position Rules:

• Lower numbers = Higher in list
• Position 0 = Top
• Pinned notes always position 0
• Positions are folder-specific

Custom Position Strategy

When to Use:

• Inserting at specific location
• Maintaining exact order
• Placing between existing notes

How It Works:

1. Select custom position
2. Enter position number
3. Notes at/after position shift +1
4. Your note takes the position

Automatic Position Strategy

When to Use:

• Adding to end of list
• Don't care about exact position
• Quick note creation

How It Works:

1. Select automatic position
2. Seeder calculates max position
3. Adds note at max + 1
4. No other notes affected

Error Handling

Common Errors

"NEXT_PUBLIC_INSTANT_APP_ID is not defined"

• Solution: Add to .env file

"Failed to read file"

• Solution: Check file path and permissions

"Invalid date format"

• Solution: Use dd-mm-yyyy format

"No notes found"

• Solution: Create notes first before moving

Recovery

If an error occurs:

• Transaction is rolled back
• No partial data created
• Can retry operation
• Check error message for details

Best Practices

Organization

1. Use Folders: Organize related notes
2. Consistent Naming: Clear, descriptive titles
3. Date Accuracy: Use correct creation dates
4. Position Strategy: Use automatic unless specific order needed

Content Management

1. File Organization: Keep markdown files organized
2. Version Control: Track markdown files in git
3. Content Quality: Write clear, structured content
4. Regular Seeding: Seed notes as you create them

Workflow

1. Plan Structure: Think about folder organization
2. Batch Operations: Create related notes together
3. Review Positions: Check note order after creation
4. Link Tasks: Connect related tasks when relevant

Integration with SK

Using SK Menu

bun run sk
# Navigate to: Tools → Run Database Seeder

Benefits:

• Unified interface
• No need to remember paths
• Consistent with other tools
• Quick access

Command Line Usage

For automation or scripts:

# Direct execution
bun run tools/seeder/src/index.ts

# From seeder directory
cd tools/seeder && bun run start

Next Steps

• Build custom CLI Commands
• Troubleshoot Common Issues
• Explore All Features