active library

curalist

Multi-collection curated awesome-list manager

Started 2026 Python

Resources & Distribution

Source Code

GitHub Repository

Package Registries

curalist

A general-purpose framework for building multi-collection curated awesome-lists. Each collection provides its own data, formatting, and categories; curalist handles CLI, site generation, and shared utilities.

Installation

pip install git+https://github.com/queelius/curalist.git

Or for development:

git clone https://github.com/queelius/curalist.git
cd curalist
pip install -e ".[dev]"

Usage

Run curalist from a directory that contains a collections/ folder:

# List all entries across all collections
curalist list-all

# List entries from a specific collection
curalist --collection books list-all

# Download free PDFs (collections that support it)
curalist --collection books download --out ./downloads

# Generate per-collection READMEs + top-level portal
curalist generate-readme

# Generate unified MkDocs site (docs/ + mkdocs.yml)
curalist generate-site

# Use a custom collections directory
curalist --collections-dir /path/to/collections list-all

Creating a Content Repo

  1. Create a collections/ directory with one or more collection subdirectories
  2. Each collection needs __init__.py, data.json, and collection.py
  3. collection.py must export the collection interface (see below)
  4. Install curalist and run commands from the content repo root

See curations for a working example.

Collection Interface

Each collections/{name}/collection.py must export:

COLLECTION_ID: str              # e.g. "books"
COLLECTION_TITLE: str           # Display name
COLLECTION_DESCRIPTION: str     # One paragraph
CATEGORY_NAMES: dict[str, str]  # slug → display name, in presentation order
HAS_DOWNLOADS: bool             # Supports --download?

def entry_bullet(entry: dict, local_pdf_path: str | None = None) -> str
def generate_readme(entries: list[dict], out_path: Path, local_pdfs: Path | None = None) -> None
def generate_docs(entries: list[dict], docs_dir: Path, local_pdfs: Path | None = None) -> dict

Entry Schema (base)

{
  "title": "Entry Title",
  "authors": "Author Names",
  "category": "category_slug",
  "year": "2024",
  "why": "Short recommendation reason",
  "tags": ["topic1", "topic2"],
  "sources": [
    {"type": "pdf", "url": "https://...", "notes": "License info"},
    {"type": "html", "url": "https://...", "notes": "Free online"},
    {"type": "reference", "notes": "Copyrighted"}
  ]
}

Collections may add extra fields (e.g. media_type, resource_type).

Development

pip install -e ".[dev]"
pytest tests/ -v --tb=short

Discussion