MarkdownDB

A lightweight markdown-based document database for managing and searching markdown documents with metadata.

Features

• 📝 Store documents as markdown files with YAML front matter
• 🔍 Full-text search across titles and content
• 🏷️ Tag-based organization and filtering
• 📅 Automatic timestamp tracking (created_at, updated_at)
• 📊 Table-based display of documents
• 🎯 Simple, intuitive Python API
• 💾 File-based storage (no external dependencies)

Installation

Using pip

pip install markdowndb

Using uv

uv pip install markdowndb

Development Installation

# Clone the repository
git clone https://github.com/yourusername/markdowndb.git
cd markdowndb

# Install in development mode
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

Quick Start

Python API

from markdowndb import MarkdownDb

# Initialize database
db = MarkdownDb()

# Create a document
doc = db.create(
    title="My First Document",
    content="This is the document content",
    tags=["python", "tutorial"]
)

# Search documents
results = db.search("python")

# Search by title
results = db.search_by_title_only("tutorial")

# Search by content
results = db.search_by_content_only("content")

# Find by tag
results = db.find_by_tag("python")

# Get a specific document
doc = db.get(doc.id)

# Update a document
updated_doc = db.update(doc.id, title="Updated Title")

# Delete a document
db.delete(doc.id)

# Display all documents in table format
db.print_table()

Command Line Interface

# Search for documents
markdowndb search "python"

# List all documents
markdowndb list

# Get a specific document
markdowndb get <document-id>

# Use custom data directory
markdowndb -d /path/to/data search "query"

Standalone Script

python main.py

API Reference

MarkdownDb Class

Methods

• __init__(directory='data') - Initialize the database with a storage directory
• create(title, content, tags=None) - Create a new document
• get(document_id) - Retrieve a document by ID
• delete(document_id) - Delete a document
• search(query) - Search in titles and content
• search_by_title_only(query) - Search only titles
• search_by_content_only(query) - Search only content
• find_by_tag(tag) - Find documents by tag
• get_by_title(title) - Get document by exact title match
• update(document_id, title=None, content=None, tags=None) - Update a document
• print_table() - Display documents in table format

Properties

• doc_list - Get list of document paths
• documents - Get list of all Document objects

Document Class

A dataclass representing a document with the following fields:

• id - Unique identifier
• title - Document title
• content - Document content
• tags - List of tags
• created_at - ISO format creation timestamp
• updated_at - ISO format update timestamp

Storage Format

Documents are stored as markdown files with YAML front matter:

---
id: 550e8400-e29b-41d4-a716-446655440000
title: Example Document
tags: ['python', 'example']
created_at: 2024-07-24T11:51:58.215000+08:00
updated_at: 2024-07-24T11:51:58.215000+08:00
---

# Document Content

This is the actual markdown content of the document.

Project Structure

markdowndb/
├── markdowndb/              # Main package
│   ├── __init__.py         # Package initialization
│   ├── markdowndb.py       # Core MarkdownDb class
│   ├── document.py         # Document dataclass
│   ├── storage.py          # Storage backend
│   └── print_table.py      # Table formatting utility
├── main.py                 # Example/CLI entry point
├── markdowndb_cli.py       # CLI module
├── pyproject.toml          # Project configuration
├── setup.py                # Setup script (legacy)
├── README.md               # This file
└── data/                   # Default data directory
    └── documents/          # Stored markdown files

Configuration

Using Custom Data Directory

from markdowndb import MarkdownDb

# Use custom directory
db = MarkdownDb(directory="/path/to/custom/data")

Requirements

• Python 3.8 or higher
• No external dependencies required

Development

Running Tests

pytest

Running with Coverage

pytest --cov=markdowndb

Code Style

• Code follows PEP 8
• Formatted with Black
• Linted with Ruff

black markdowndb/
ruff check markdowndb/

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues, questions, or suggestions, please open an issue on GitHub.