Skip to content

Core Concepts

Jump to bottom
sysid edited this page Oct 12, 2025 · 2 revisions

Core Concepts

Understanding these core concepts will help you use bkmr effectively.

Bookmarks

In bkmr, a bookmark is any piece of content you want to store and retrieve later:

  • Web URLs
  • Code snippets
  • Shell scripts
  • Markdown documents
  • Environment variables
  • File references

Each bookmark has:

  • URL/Content: The actual content (can be a URL or text)
  • Title: A descriptive name
  • Description/Comments: Optional additional context
  • Tags: For organization and filtering
  • System Tags: Automatic tags that determine behavior (e.g., _snip_, _shell_)

Tags

Tags are the primary organization mechanism in bkmr.

User Tags

  • Free-form labels you assign
  • Comma-separated, no spaces: python,security,auth
  • Used for filtering and organization
  • Case-sensitive

Examples:

bkmr add <content> python,web,tutorial
bkmr search -t python,security

System Tags

Special tags that determine how bkmr handles content:

System Tag Purpose Default Action
_snip_ Code snippet Copy to clipboard
_shell_ Shell script Interactive edit + execute
_md_ Markdown document Render in browser
_env_ Environment variables Print for sourcing
_imported_ Imported file content Copy to clipboard

Automatic assignment:

  • Added with --type snip → Gets _snip_ tag
  • Added with --type shell → Gets _shell_ tag
  • Imported .md files → Get _md_ tag

Content Types

Content types determine how bkmr processes and presents your bookmarks. See Content Types for detailed information.

Common Content Types

1. URLs

bkmr add https://example.com dev,reference
# Opens in browser when accessed

2. Snippets

bkmr add "console.log('test')" javascript,_snip_ --title "Debug Log"
# Copies to clipboard when accessed

3. Shell Scripts

bkmr add "#!/bin/bash\necho 'Hello'" utils,_shell_ --title "Greeting"
# Interactive editor before execution

4. Markdown

bkmr add "# Title\n\n## Section" docs,_md_ --title "Documentation"
# Renders in browser with TOC

Smart Actions

bkmr automatically selects the appropriate action based on content type (system tag):

# Same command, different actions:
bkmr open <url-id>      # Opens in browser
bkmr open <snippet-id>  # Copies to clipboard
bkmr open <shell-id>    # Interactive editor + execute
bkmr open <md-id>       # Renders in browser

This context-aware behavior means you don't need different commands for different content types.

Database

bkmr stores everything in a local SQLite database:

  • Default location: ~/.config/bkmr/bkmr.db
  • Configurable via BKMR_DB_URL environment variable
  • Includes full-text search (FTS5) index
  • Optional: Semantic embeddings for AI-powered search

Search Methods

bkmr provides multiple ways to find content:

1. Full-Text Search (FTS)

bkmr search "python security"
bkmr search "containerization"

2. Tag Filtering

bkmr search -t python,tutorial       # Must have ALL tags
bkmr search -T deprecated,old        # Must NOT have these tags

3. Fuzzy Finding (Interactive)

bkmr search --fzf                    # Interactive picker
bkmr search --fzf -t python          # Pre-filtered fuzzy search

4. Semantic Search (AI-powered)

bkmr --openai sem-search "deploy automation"
# Finds conceptually similar content

See Search and Discovery for comprehensive search documentation.

File Integration

bkmr can import files with metadata and track changes:

# Import with frontmatter
bkmr import-files ~/scripts/backup.sh

# Smart editing (edits source file)
bkmr edit <imported-id>

See File Import and Editing for details.

Template Interpolation

Make content dynamic with Jinja2 templates:

# Dynamic date in URL
bkmr add "https://reports.com/{{ current_date | strftime('%Y-%m-%d') }}" reports

# Environment variables in scripts
bkmr add "export PATH={{ env('HOME') }}/bin:\$PATH" env,_env_

See Template Interpolation for details.

Next Steps

bkmr Documentation

Getting Started
User Guide
Advanced Features
Reference
Support

Clone this wiki locally