Metadata-Version: 2.4
Name: readthememo
Version: 2025.6
Summary: A minimalistic, self-hosted, statically rendered, micro-blogging engine.
Author-email: Borjan Tchakaloff <borjan@steadymonkey.eu>
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-Expression: GPL-3.0-or-later
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Utilities
License-File: COPYING.txt
Requires-Dist: jinja2>=3.1.6
Requires-Dist: marko>=2.1.4
Requires-Dist: pyyaml>=6.0.2
Requires-Dist: tyro>=0.9.26
Project-URL: Homepage, https://readthememo.app
Project-URL: Repository, https://git.sr.ht/~docbibi/memos/

# `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:

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

Or install development dependencies:

```shell
pip install -e .[dev]
```

## Usage

### Basic Usage

Build HTML from a single CommonMark file:

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

Build HTML from a directory with CommonMark files:

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

### Standard Input/Output

Read from stdin and write to stdout:

```shell
cat memos.md | memos > output.html
```

### CommonMark Format

**site.yaml:**

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

**2025-01-01.md:**

```markdown
## My First Memo #InterstingTopic

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

**2025-01-02.md:**

```markdown
- ## 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:

```markdown
---
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:**

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

1. **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`

1. **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

1. **Publishing workflow:**

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

1. **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

1. **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`](https://docs.astral.sh/uv/), install it first through your method of choice.
For example with [pipx](https://pipx.pypa.io):

```shell
pipx install uv
```

### Running Tests

```shell
uv run pytest
```

### Code Quality

The project uses ruff for linting and formatting:

```shell
uv run ruff check
uv run ruff format
```

### Pre-commit Hooks

Set up pre-commit hooks:

```shell
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](COPYING.txt)

## Contributing

1. Check existing Architecture Decision Records in `docs/decisions/`
1. Follow the functional core, imperative shell pattern
1. Write tests for new functionality
1. Ensure code passes ruff linting
1. 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.

