readthememo 2025.6

A minimalistic, self-hosted, statically rendered, micro-blogging engine.

readthememo

A minimalistic, self-hosted, statically rendered, micro-blogging engine.

Overview

readthememo (command: memos) is a simple tool that transforms memos into static HTML pages. It's designed for quick, low-friction publishing of short-form content without the complexity of traditional blogging platforms.

Features

• Minimal dependencies: Built with Python 3.11+ using only Jinja2, marko, and tyro
• Static output: Generates clean, standalone HTML files
• CommonMark (markdown) input: Write your content in a simple, readable format
• LogSeq-ready: Directory format works seamlessly with LogSeq
• Responsive design: Uses Pico CSS for clean, semantic styling
• CLI interface: Simple command-line tool for building your site
• Self-contained: No database or server requirements

Installation

Install from source:

git clone https://git.sr.ht/~docbibi/memos/
cd memos
python3 -mvenv .venv
. ./.venv/bin/activate
pip install -e .

Or install development dependencies:

pip install -e .[dev]

Usage

Basic Usage

Build HTML from a single CommonMark file:

memos path/to/your/memos.md output.html

Build HTML from a directory with CommonMark files:

memos path/to/your/memos/ output.html

Standard Input/Output

Read from stdin and write to stdout:

cat memos.md | memos > output.html

CommonMark Format

site.yaml:

---
title: "My Blog Title"
author: "Your Name"
headline: "My Blog"
moto:
  - "A description of your blog"
  - "by Your Name"
---

2025-01-01.md:

## My First Memo #InterstingTopic

This is the content of my first memo.
It can contain HTML tags and multiple paragraphs.

2025-01-02.md:

- ## Hello from LogSeq
    - This memo is bullet point heavy, as can be seen when reading raw content from a LogSeq journal.
    - The feature is similar, except that the first two levels of bullet points will be stripped by the parser to
      streamline the structure.

Key features:

• Natural prose: Write directly in markdown without TOML strings
• LogSeq compatible: Use YYYY-MM-DD.md or YYYY_MM_DD.md naming; strip the first level of bullet-points
• Multiple articles per day: Separate with --- horizontal rules
• Tag extraction: Add tags to titles using #tag format
• HTML support: Embed HTML directly in markdown content

Alternative: Single File with YAML Frontmatter

You can also use a single CommonMark file with YAML frontmatter:

---
title: "My Blog Title"
author: "Your Name"
headline: "My Blog"
moto:
  - "A description of your blog"
  - "by Your Name"
---

# 2025-01-01

## My First Memo

This is the content of my first memo.
It can contain HTML tags and multiple paragraphs.

# 2025-01-02

## Another Memo #tech #thoughts

This memo has tags listed after the title.

This format is useful for smaller blogs or when you prefer to keep everything in one file.

LogSeq Integration

The directory structure is designed to work seamlessly with LogSeq:

1. Set up LogSeq graph:

   # Your memos directory becomes a LogSeq graph
   # LogSeq will automatically detect the markdown files
   

2. File naming compatibility:

   • LogSeq uses YYYY_MM_DD.md format by default (underscores), but will happily use files named using hyphens ( YYYY-MM-DD.md)
   • readthememo supports both YYYY-MM-DD.md and YYYY_MM_DD.md

3. LogSeq workflow:

   • Open your memos directory as a LogSeq graph
   • Create daily notes using LogSeq's journal feature
   • Use ## Title #tag format for your memo titles
   • Write content underneath (nested)
   • Repeat for other articles on the same day

4. Publishing workflow:

   # Edit in LogSeq, then publish
   memos path/to/logseq-graph/ > output.html
   

5. LogSeq features that work:

   • Daily notes: Perfect for memo-style content
   • Tags: Use #tag in titles for automatic tag extraction
   • Block references: Can be used within memo content
   • Linked references: Work normally within LogSeq

6. What gets published:

   • Only files matching YYYY-MM-DD.md or YYYY_MM_DD.md patterns
   • Other LogSeq files (config, assets, etc.) are ignored
   • Content is processed as standard markdown with HTML passthrough

Project Structure

├── src/readthememo/        # Main application code
│   ├── cli.py              # Command-line interface
│   ├── core.py             # Core parsing and rendering logic
│   └── templates.py        # Template environment setup
├── src/templates/          # Jinja2 HTML templates
├── static/                 # CSS and static assets
├── tests/                  # Test suite
├── docs/decisions/         # Architecture Decision Records
└── memos/                  # Example memos documenting this project itself

Development

You will need uv, install it first through your method of choice. For example with pipx:

pipx install uv

Running Tests

uv run pytest

Code Quality

The project uses ruff for linting and formatting:

uv run ruff check
uv run ruff format

Pre-commit Hooks

Set up pre-commit hooks:

uv run pre-commit install

Architecture

This project follows a functional core, imperative shell architecture:

• Core: Pure functions for parsing TOML and rendering HTML
• Shell: CLI interface and I/O operations
• Templates: Jinja2 templates for HTML generation

See docs/decisions/ for detailed architecture decisions.

Requirements

• Python 3.11 or higher
• Jinja2 3.1.6+
• tyro 0.9.26+

License

GPL-3.0-or-later

Contributing

1. Check existing Architecture Decision Records in docs/decisions/
2. Follow the functional core, imperative shell pattern
3. Write tests for new functionality
4. Ensure code passes ruff linting
5. Update documentation as needed

Examples

See the memos/ directory for this very repository memos; with site.toml configuration and date-based .md files.

Also take a look at the test files (.md) in tests/cases/ for single-file examples.