markdown-org-extract

CLI utility for extracting tasks from markdown files with support for Emacs Org-mode markers.

Table of contents

• Installation and build
• For downstream packagers
• Usage
• Example files
• Agenda modes
• Supported markers
• Locale support
• Output format
• Repeating tasks
• Project layout
• Dependencies
• License

Installation and build

Requirements

• Rust 1.85 or newer. The bundled comrak 0.50+ ships on Rust edition 2024 and therefore requires a 1.85+ toolchain; this crate itself is still on edition 2021 (see TODO.md for the planned migration).
• Cargo

Install from crates.io

If you only need the binary and do not want to clone the repository:

cargo install markdown-org-extract

After installation the binary lands in ~/.cargo/bin/markdown-org-extract (this path must be on your PATH).

Shell completions

The binary can emit its own completion script for bash, zsh, fish, elvish, and powershell via --completions <SHELL>. The script is printed to stdout; redirect it to wherever your shell expects completions.

# bash (user-local)
mkdir -p ~/.local/share/bash-completion/completions
markdown-org-extract --completions bash \
    > ~/.local/share/bash-completion/completions/markdown-org-extract

# zsh (add a directory to $fpath, e.g. ~/.zfunc)
markdown-org-extract --completions zsh \
    > ~/.zfunc/_markdown-org-extract

# fish
markdown-org-extract --completions fish \
    > ~/.config/fish/completions/markdown-org-extract.fish

Reload the shell or re-source its config after writing the file.

Building the project

The rest of this section — building, running from a checkout, and testing — is for contributors and people building from source. If you installed the binary with cargo install (above), skip to Usage; you do not need to clone the repository.

Debug build:

cargo build

Optimised release build:

cargo build --release

The resulting binary appears in:

• Debug: target/debug/markdown-org-extract
• Release: target/release/markdown-org-extract

Running

After building, run the utility:

# Debug build
./target/debug/markdown-org-extract [OPTIONS]

# Release build
./target/release/markdown-org-extract [OPTIONS]

Or use cargo to run it without an explicit build step:

cargo run -- [OPTIONS]

Testing

Run the test suite:

cargo test

Run with verbose output:

cargo test -- --nocapture

Static checks:

cargo check
cargo clippy

Run the full CI-equivalent locally before pushing or opening a PR:

scripts/check.sh

scripts/check.sh chains cargo fmt --check, yamllint .github/workflows/, cargo clippy --all-targets -D warnings, cargo doc --no-deps -D warnings, and cargo test. It is the single command that mirrors the CI configuration; running cargo test alone will not catch rustfmt or yamllint regressions that block CI on a subsequent push.

Workday handling

Workday-aware scheduling is exercised by tests across three modules: holidays (the RU calendar, weekend/holiday classification, and the next-working-day walk), timestamp::repeater (the +Nwd / ++Nwd / .+Nwd repeater grammar and holiday-skipping occurrence arithmetic), and timestamp::parser (timestamps that carry a workday repeater). For the authoritative, always-current list of cases, read the #[test] functions in those modules (cargo test -- --list prints the names).

For downstream packagers

This section documents the contract that the GitHub Release artefacts keep for downstream packagers (distro maintainers, Nix derivations, private mirrors, automated bootstrappers). Within a major version the layout below will not change without a CHANGELOG entry and a CHANGELOG-referenced ADR.

Asset naming

Each release publishes one archive per platform target:

Target	Archive extension	Binary name
x86_64-unknown-linux-gnu	.tar.gz	markdown-org-extract
x86_64-apple-darwin	.tar.gz	markdown-org-extract
aarch64-apple-darwin	.tar.gz	markdown-org-extract
x86_64-pc-windows-msvc	.zip	markdown-org-extract.exe

The archive filename template is:

markdown-org-extract-<version>-<target>.<ext>

Example asset set for tag v0.4.1:

markdown-org-extract-0.4.1-x86_64-unknown-linux-gnu.tar.gz
markdown-org-extract-0.4.1-x86_64-apple-darwin.tar.gz
markdown-org-extract-0.4.1-aarch64-apple-darwin.tar.gz
markdown-org-extract-0.4.1-x86_64-pc-windows-msvc.zip

<version> is the tag stripped of its leading v, identical to the [package].version field in Cargo.toml for that commit (the publish job in .github/workflows/release.yml fails the release if the two diverge).

Archive layout

Each archive extracts to a single top-level directory whose name matches the archive stem:

markdown-org-extract-<version>-<target>/
├── markdown-org-extract       # markdown-org-extract.exe on Windows
├── README.md
└── LICENSE

No nested target subdirectories, no separate debug symbols, no manpages. Adding a file to the staged directory is a contract change (CHANGELOG entry + ADR).

Checksums

Every archive ships with a sibling .sha256 file in the standard sha256sum format (<hex> <filename>):

markdown-org-extract-<version>-<target>.<ext>
markdown-org-extract-<version>-<target>.<ext>.sha256

Verification with the GNU tool:

sha256sum -c markdown-org-extract-0.4.1-x86_64-unknown-linux-gnu.tar.gz.sha256

A SHA256SUMS aggregate file is not currently published. If one is added later, the per-archive .sha256 companions will remain in place for at least one major-version cycle.

Reproducibility

Linux and macOS archives are produced with tar --sort=name --owner=0 --group=0 --numeric-owner --mtime='@0'; the Windows zip uses 7z -mtc=off to strip per-file timestamps. Re-running the release workflow on the same commit produces byte-identical archives and matching SHA-256 values.

Compatibility floor

• Crate MSRV: 1.85 (declared in Cargo.toml and verified by the msrv CI job). Building from source requires at least this toolchain version.
• Build hosts: GitHub-hosted runners current at release time (ubuntu-24.04, macos-latest, windows-latest). The Linux binary links against the glibc bundled with Ubuntu 24.04; older glibc baselines require building from source.
• No runtime native dependencies: the Russian holiday calendar is embedded at compile time via build.rs.

Download patterns

The GitHub Release download URL is stable across releases:

https://github.com/VitalyOstanin/markdown-org-extract/releases/download/v<version>/markdown-org-extract-<version>-<target>.<ext>
https://github.com/VitalyOstanin/markdown-org-extract/releases/download/v<version>/markdown-org-extract-<version>-<target>.<ext>.sha256

releases/latest resolves to the most recent non-pre-release; suitable for unattended downloads when a specific tag is not required.

Out of scope

• The binaries are unsigned. Trust is anchored in TLS to GitHub plus the published SHA-256 values.
• Distribution-specific repacks (.deb, .rpm, AUR, MacPorts, Homebrew formula) are not maintained by this project; the upstream artefact is the GitHub Release archive.
• Additional targets (aarch64-unknown-linux-gnu, musl variants, aarch64-pc-windows-msvc) may be added in a future minor release. Removal of a previously published target requires a major-version bump.

Usage

markdown-org-extract [OPTIONS]

Options

• --dir <DIR> — directory to scan (default: .)
• --glob <GLOB> — file filter pattern (default: *.md)
• --format <FORMAT> — output format: json, md, html (default: json)
• --output <OUTPUT> — file to write the result to; - means stdout (default: stdout)
• --locale <LOCALE> — weekday locales, comma-separated (default: ru,en)
• --agenda <MODE> — agenda mode: day, week, month, tasks (default: day)
• --tasks — show all TODO tasks sorted by priority (alias for --agenda tasks)
• --tasks-include-done — also include DONE tasks in the flat --tasks / --agenda tasks list (default: TODO only). No effect in day/week/month mode
• --tasks-include-cancelled — also include cancelled tasks (either spelling, CANCELLED or CANCELED) in the flat --tasks / --agenda tasks list (default: TODO only). Independent of --tasks-include-done. No effect in day/week/month mode
• --date <DATE> — window anchor for day/week/month mode in YYYY-MM-DD. In day mode the window is exactly this date; in week/month it is the week / month containing this date. Overridden by --from/--to. Not allowed in tasks mode. Default: --current-date (or today)
• --from <DATE> — window start (YYYY-MM-DD) for day/week/month mode. Together with --to, an explicit range that overrides --date. If --to is omitted, the window ends at --current-date (or today). Not allowed in tasks mode
• --to <DATE> — window end (YYYY-MM-DD) for day/week/month mode. Together with --from, an explicit range that overrides --date. If --from is omitted, the window starts at --current-date (or today). Not allowed in tasks mode
• --tz <TIMEZONE> — IANA timezone for determining the current date (default: Europe/Moscow)
• --current-date <DATE> — override of "today" (YYYY-MM-DD). Used as the reference for overdue / upcoming markers and as the default for a missing --from/--to edge. Not allowed in tasks mode. Default: today in --tz
• --holidays <YEAR> — print the holiday list for the given year (1900–2100) as JSON
• --absolute-paths — emit absolute file paths instead of paths relative to --dir. With -v/-vv/-vvv, diagnostic stderr also logs file paths and timestamp content; under --absolute-paths these stderr entries carry absolute paths too. Combine with --quiet when sharing logs externally.
• --max-tasks <N> — task limit (1..=10_000_000, default 10_000). Acts as a global cap on the number of extracted tasks; the same value is reused as a per-file cap so a single hostile file cannot exhaust the global budget on its own. The scan stops as soon as either cap is hit. A separate hard limit of 10 MiB per file is built in; oversized files are skipped and counted under files_skipped_size in the processing summary
• -v, --verbose — verbose stderr log (-v = info, -vv = debug, -vvv = trace). Mutually exclusive with --quiet. The RUST_LOG environment variable takes precedence: when set, it overrides --verbose/--quiet entirely (e.g. RUST_LOG=error mutes -vv)
• -q, --quiet — suppress all diagnostic messages except critical errors
• --color <MODE> — control ANSI colour in logs: auto (default), always, never
• --no-color — disable ANSI colour in logs; equivalent to --color never. The NO_COLOR environment variable has the same effect (see no-color.org)

In --color auto mode the following env vars are honoured (precedence from highest to lowest, after CLI flags):

Variable	Effect
NO_COLOR	Any value (incl. empty) disables colour. Wins over CLICOLOR_FORCE. See no-color.org.
CLICOLOR_FORCE	Non-zero, non-empty value enables colour even when stderr is not a TTY. See bixense CLI colours.
CLICOLOR	Exactly 0 disables colour. Other values leave the TTY-based default in place.

CLI flags --color always, --color never, and --no-color override any of the above.

Environment variables

The CLI reads no configuration files; behaviour is driven by flags and a small set of environment variables:

• RUST_LOG — sets the diagnostic log filter (tracing syntax, e.g. RUST_LOG=debug or RUST_LOG=markdown_org_extract=trace). When set, it overrides --verbose / --quiet entirely (see ADR-0016).
• NO_COLOR, CLICOLOR_FORCE, CLICOLOR — control ANSI colour in the diagnostic log; see the colour-precedence table under Options.

The timezone is not taken from the TZ environment variable; it is controlled only by --tz (default Europe/Moscow). "Today" can be pinned with --current-date for reproducible output.

File selection

The scan walks --dir with the ignore crate's standard filters, so it behaves like other Rust tooling (ripgrep, fd):

• .ignore files (including nested ones deeper in the tree) are always honoured; matching files are not scanned.
• .gitignore, the global gitignore, and .git/info/exclude are honoured only when the scanned tree is inside a git repository — the ignore crate evaluates them relative to the enclosing .git. A .gitignore in a directory with no .git has no effect; use .ignore for VCS-independent rules.
• Hidden files and directories (dot-prefixed) are skipped.
• Symbolic links are not followed, and the walk stays on the starting filesystem (it will not cross a mount point).
• Of the files that survive those filters, only those matching --glob (default *.md) are parsed.

Examples

Extract tasks from the current directory as JSON:

markdown-org-extract

Extract tasks from a specific directory:

markdown-org-extract --dir ./notes

Save the result to an HTML file:

markdown-org-extract --dir ./notes --format html --output agenda.html

Emit markdown:

markdown-org-extract --dir ./notes --format md

Run against the bundled examples:

markdown-org-extract --dir ./examples
markdown-org-extract --dir ./examples --format md
markdown-org-extract --dir ./examples --format html --output examples-agenda.html

Use only Russian weekday names:

markdown-org-extract --dir ./notes --locale ru

Use only English weekday names:

markdown-org-extract --dir ./notes --locale en

Agenda examples

Today's tasks (default):

markdown-org-extract --dir ./notes

Tasks for a specific date:

markdown-org-extract --dir ./notes --agenda day --date 2025-12-10

Retrieve the holiday list for a year:

markdown-org-extract --holidays 2025
markdown-org-extract --holidays 2026

Sample holiday output:

[
  "2025-01-01",
  "2025-01-02",
  "2025-01-03",
  "2025-01-04",
  "2025-01-05",
  "2025-01-06",
  "2025-01-07",
  "2025-01-08",
  "2025-02-23",
  "2025-03-08",
  "2025-05-01",
  "2025-05-09",
  "2025-06-12",
  "2025-11-04"
]

Tasks for the current week:

markdown-org-extract --dir ./notes --agenda week

Tasks for the current month:

markdown-org-extract --dir ./notes --agenda month

Tasks across a date range:

markdown-org-extract --dir ./notes --agenda week --from 2025-12-01 --to 2025-12-07
markdown-org-extract --dir ./notes --agenda month --from 2025-12-01 --to 2025-12-31

All TODO tasks sorted by priority:

markdown-org-extract --dir ./notes --tasks

Use a different timezone:

markdown-org-extract --dir ./notes --tz UTC
markdown-org-extract --dir ./notes --tz America/New_York

Use an explicit current date (useful for tests and deterministic output):

markdown-org-extract --dir ./notes --agenda week --current-date 2024-12-05

Cap the number of extracted tasks (useful for batch processing of very large trees):

markdown-org-extract --dir ./notes --max-tasks 1000

Enable verbose processing logs on stderr:

markdown-org-extract --dir ./notes -v

Exit codes

The CLI maps error categories to distinct exit codes (sysexits-style) so shell pipelines can branch on the cause:

Code	Category	Examples
0	success	normal run, --holidays, --completions
2	usage / input-validation	invalid --dir, --glob, --date, --tz, --output parent, --locale ru,xx, from > to
70	internal software error (EX_SOFTWARE)	a regex we built ourselves did not compile, or our own serializer failed
74	IO failure (EX_IOERR)	unreadable input file, walker error, write failure on --output
130	scan aborted by signal (128 + SIGINT)	Ctrl-C during a long scan; SIGTERM on Unix. A partial processing summary is logged on stderr at warn.

A broken output pipe is not an error: when a downstream consumer closes the read end early (markdown-org-extract … | head -n 1), the write fails with EPIPE / BrokenPipe. By then the bytes the consumer kept have already been produced, so the CLI exits 0 silently with no diagnostic — matching cat, grep, and jq in the same situation. A broken pipe on --output (a real file) is reported normally as an IO error (74); only the stdout pipe is treated as a clean stop.

AppError::Io embeds the failing path or stream sentinel (<stdout>) in its Display, so an IO error reads error: io: /tmp/out.json: Permission denied (os error 13) instead of just the bare OS message.

A SIGINT or SIGTERM during the directory walk flips an internal flag that the scan loop polls between files. On the next iteration the walk stops, the partial processing summary is emitted on stderr (with interrupted = true), --output is not written, and the process exits with code 130. Sending the signal a second time after the scan has already finished has no effect; the process is past the polling point.

Example files

The examples/ directory contains markdown files with various markers. The integration tests in tests/cli.rs exercise the same files.

General scenarios:

• project-tasks.md — project development tasks
• personal-notes.md — personal notes and tasks
• meeting-notes.md — meeting notes
• work-log.md — mixed log with SCHEDULED, DEADLINE, and CLOCK entries

Org-mode marker demonstrations:

• priorities.md — tasks with priorities [#A], [#B], [#C]
• org-mode-timestamps.md — timestamp forms, ranges, and repeaters
• created-test.md — using CREATED: for the creation date
• workdays-test.md — workday repeaters (+1wd, +2wd) interacting with the holiday calendar

CLOCK-block demonstrations (time tracking):

• clock-formats.md — every supported CLOCK line form
• clock-inline.md — CLOCK inside inline code (`CLOCK: ...`)
• clock-test.md — closed CLOCK intervals with => HH:MM
• simple-clock.md — CLOCK inside fenced code blocks
• done-clock.md — CLOCK attached to a DONE task (post-completion accounting)

Try running (after cargo install, or substitute cargo run --release -- from a checkout):

markdown-org-extract --dir ./examples --format md

Agenda modes

The utility supports four task-listing modes, mirroring Emacs Org-mode:

day — tasks for a single day

Shows tasks whose timestamps (SCHEDULED, DEADLINE) fall on the given date. The default is today in the configured timezone.

# Today's tasks
markdown-org-extract --agenda day

# Tasks for a specific date
markdown-org-extract --agenda day --date 2025-12-10

week — tasks for a week

Shows tasks whose timestamps fall within a date range. The default is the current week (Monday–Sunday).

Each day lists:

• Tasks scheduled for that day (scheduled)
• Upcoming tasks relative to that day (upcoming)
• Overdue tasks (overdue) — only for the current date

# Current week
markdown-org-extract --agenda week

# Explicit range
markdown-org-extract --agenda week --from 2025-12-01 --to 2025-12-07

month — tasks for a month

Shows tasks whose timestamps fall within a date range. The default is the current month (first to last day).

Behaves the same way as week — each day surfaces scheduled, upcoming, and overdue tasks.

# Current month
markdown-org-extract --agenda month

# Explicit range
markdown-org-extract --agenda month --from 2025-12-01 --to 2025-12-31

tasks — all TODO tasks

Lists every task whose state is TODO, sorted by priority (A → B → C → no priority). Timestamps are ignored. Add --tasks-include-done to additionally surface DONE tasks (off by default), e.g. for a consumer that needs completed tasks to remove a linked calendar event. Add --tasks-include-cancelled to additionally surface cancelled tasks — either spelling, CANCELLED or CANCELED — (off by default, independent of --tasks-include-done), e.g. for a consumer that needs cancelled tasks to remove a linked calendar event.

# All TODO tasks by priority
markdown-org-extract --tasks

# TODO tasks plus completed (DONE) ones
markdown-org-extract --tasks --tasks-include-done

# TODO tasks plus cancelled ones
markdown-org-extract --tasks --tasks-include-cancelled

# TODO tasks plus both DONE and CANCELLED
markdown-org-extract --tasks --tasks-include-done --tasks-include-cancelled

Timezones

The --tz option controls which timezone is used to derive the current date and current week. All standard IANA timezones are accepted.

# Moscow time (default)
markdown-org-extract --agenda day --tz Europe/Moscow

# UTC
markdown-org-extract --agenda day --tz UTC

# New York
markdown-org-extract --agenda day --tz America/New_York

Supported markers

Task markers

The utility recognises the following task state markers in headings:

• TODO — task to be done.
• DONE — task completed.
• CANCELLED (or the single-L CANCELED, as used in upstream Org-mode) — task cancelled (must not be done; distinct from DONE). The spelling you write is preserved in the task_type output.

### TODO Implement feature
### DONE Complete task
### CANCELLED Abandoned idea
### CANCELED Dropped variant

Task priorities

Priorities follow the org-mode convention (letters A–Z inside square brackets):

### TODO [#A] Critical task
### TODO [#B] Important task
### TODO [#C] Regular task
### DONE [#A] Completed high-priority task

The priority appears after the task state marker (TODO/DONE/CANCELLED/CANCELED) and before the task text. The most common priorities are:

• [#A] — high priority (critical tasks)
• [#B] — medium priority (important tasks)
• [#C] — low priority (regular tasks)

Priority is optional.

Timestamps

Timestamps must be wrapped in backticks:

Simple timestamp:

`<2024-12-10 Mon 10:00-12:00>`

Planning markers:

`CREATED: [2024-12-01 Mon]`
`DEADLINE: <2024-12-15 Sun>`
`SCHEDULED: <2024-12-05 Wed>`
`CLOSED: [2024-12-01 Mon]`

The bracket form is per-keyword (see ADR-0014): SCHEDULED: and DEADLINE: carry active <...>; CLOSED: and CREATED: carry inactive [...].

Date range:

`<2024-12-20 Mon>--<2024-12-22 Wed>`

The dash separator follows Emacs' org-tr-regexp and accepts one, two, or three dashes (-, --, ---). The canonical form on output is two dashes.

Limitation: the start date and start / end times of a range are surfaced in the output, but the end date is not. A range task is therefore shown on its start day only, not on every day spanned by the range. See ADR-0002 for the documented scope and ADR-0009 for the agenda window model.

Active and inactive timestamps:

Emacs Org-mode distinguishes two bracket forms — active <...> drives the agenda; inactive [...] is descriptive metadata that never feeds agenda windows. The accepted form is fixed per context:

Context	Active <...>	Inactive [...]
SCHEDULED:	yes	no
DEADLINE:	yes	no
CLOSED:	no	yes
CREATED:	no	yes
Inline plain	yes	yes
CLOCK:	yes	yes

Mixed pairs <...] and [...> are rejected. Inactive timestamps never drive day / week / month agenda windows; they are surfaced in the JSON output via the timestamp_active field (true for <...>, false for [...]). See ADR-0014 for the upstream-Emacs sources and the breaking-change migration.

Note: CREATED is extracted separately from the other timestamps and stored in the created field. This lets consumers track the task creation date independently of SCHEDULED, DEADLINE, and CLOSED.

Warning-period cookie on DEADLINE:

A DEADLINE can carry a -N<unit> cookie that overrides the global 14-day upcoming-window for that one task. Units h/d/w/m/y are recognised; values are converted to whole days using upstream org-get-wdays's factors (d=1, w=7, m=30.4, y=365.25, h=1/24, floored).

`DEADLINE: <2025-12-10 Wed -3d>`   — show only 3 days before
`DEADLINE: <2025-12-20 Sat -30d>`  — start warning 30 days out
`DEADLINE: <2025-12-10 Wed +1y -3d>` — repeater + cookie together
`DEADLINE: <2025-12-10 Wed -3d +1y>` — order does not matter

Without a cookie the task uses the default 14-day window.

Time tracking (CLOCK)

The utility supports CLOCK entries for tracking time spent on tasks, mirroring Emacs Org-mode.

CLOCK format inside backticks (same as timestamps):

### TODO Implement feature

`SCHEDULED: <2024-12-10 Tue>`
`CLOCK: <2024-12-09 Mon 10:00>--<2024-12-09 Mon 12:30> => 2:30`
`CLOCK: <2024-12-09 Mon 14:00>--<2024-12-09 Mon 16:15> => 2:15`

Alternative format inside code blocks (as in org-mode):

### TODO Implement feature

`SCHEDULED: <2024-12-10 Tue>`

CLOCK: [2024-12-09 Mon 10:00]--[2024-12-09 Mon 12:30] => 2:30 CLOCK: [2024-12-09 Mon 14:00]--[2024-12-09 Mon 16:15] => 2:15

Open CLOCK entry (active work):

`CLOCK: <2024-12-10 Tue 09:00>`

Features:

• Automatic extraction of every CLOCK entry under a heading
• Total time (total_clock_time) summed across all entries
• Open (active) CLOCK entries without a close time
• Rendering in JSON, Markdown, and HTML
• Both square [...] (org-mode style) and angle <...> brackets are accepted

Sample JSON output:

{
  "heading": "Implement feature",
  "clocks": [
    {
      "start": "2024-12-09 Mon 10:00",
      "end": "2024-12-09 Mon 12:30",
      "duration": "2:30"
    },
    {
      "start": "2024-12-09 Mon 14:00",
      "end": "2024-12-09 Mon 16:15",
      "duration": "2:15"
    }
  ],
  "total_clock_time": "4:45"
}

Sample Markdown output:

## Implement feature
**Total Time:** 4:45

**Clock:**
- 2024-12-09 Mon 10:00 → 2024-12-09 Mon 12:30 (2:30)
- 2024-12-09 Mon 14:00 → 2024-12-09 Mon 16:15 (2:15)

Locale support

The utility recognises weekday names in different languages via the --locale option.

Supported locales

• en — English (Mon, Tue, Wed, Thu, Fri, Sat, Sun, Monday, Tuesday, ...)
• ru — Russian (Пн, Вт, Ср, Чт, Пт, Сб, Вс, Понедельник, Вторник, ...)

The default is both locales: --locale ru,en.

An unknown entry (e.g. --locale ru,fr) is rejected at CLI parse time with exit code 2 — --quiet does not mask it. Empty segments are tolerated, so --locale ru, and --locale ,en parse the same as --locale ru and --locale en respectively.

Russian-weekday examples

### TODO Встреча
`<2024-12-10 Пн 10:00>`

### Конференция
`<2024-12-20 Понедельник>--<2024-12-22 Среда>`

### TODO Задача
`DEADLINE: <2024-12-15 Вс>`

Russian weekday names are normalised to the English form during extraction.

Output format

The output format depends on the agenda mode.

--tasks mode (task list)

JSON

Optional fields (priority, created, timestamp_active, timestamp_time, timestamp_end_time, timestamp_repeater, clocks, total_clock_time, properties, task_type) are omitted when absent rather than serialised as null. timestamp_repeater carries the timestamp's org repeater in its canonical form (++7d, .+1m, +1wd) and is absent when the timestamp has no repeater; the repeater also remains present verbatim inside the raw timestamp string. This matches the #[serde(skip_serializing_if = "Option::is_none")] convention used in src/types.rs.

Example below is the actual output of --dir examples --glob 'project-tasks.md' --tasks --max-tasks 1 --current-date 2025-12-05.

[
  {
    "file": "project-tasks.md",
    "line": 5,
    "heading": "Design database schema",
    "content": "Need to finalize the database structure before implementation.",
    "task_type": "TODO",
    "priority": "A",
    "timestamp": "SCHEDULED: <2024-12-05 Wed>",
    "timestamp_type": "SCHEDULED",
    "timestamp_active": true,
    "timestamp_date": "2024-12-05"
  }
]

Markdown

# Tasks

## Design database schema
**File:** `project-tasks.md:5`
**Type:** TODO
**Priority:** A
**Time:** `SCHEDULED: <2024-12-05 Wed>`

Need to finalize the database structure before implementation.

--agenda day and --agenda week modes (day-grouped agenda)

In these modes tasks are grouped by day. Each day contains task categories (in display order):

1. Overdue (only for the current date) — overdue tasks, oldest first
2. Scheduled (with time) — that day's tasks with a time, earliest first
3. Scheduled (no time) — that day's tasks without a time
4. Upcoming — upcoming tasks relative to that day, nearest first

Important: Each day shows upcoming tasks relative to that day, not relative to a global reference date.

JSON

File paths are emitted relative to --dir (or absolute when --absolute-paths is set). Optional fields are omitted when absent, as in --tasks mode.

[
  {
    "date": "2025-12-05",
    "overdue": [
      {
        "file": "project-tasks.md",
        "line": 5,
        "heading": "Design database schema",
        "content": "Need to finalize the database structure before implementation.",
        "task_type": "TODO",
        "priority": "A",
        "timestamp": "SCHEDULED: <2024-12-05 Wed>",
        "timestamp_type": "SCHEDULED",
        "timestamp_active": true,
        "timestamp_date": "2024-12-05",
        "days_offset": -365
      }
    ],
    "scheduled_timed": [],
    "scheduled_no_time": [],
    "upcoming": [
      {
        "file": "project-tasks.md",
        "line": 47,
        "heading": "Review pull request #42",
        "content": "Critical bug fix needs review.",
        "task_type": "TODO",
        "timestamp": "DEADLINE: <2025-12-06 Sat>",
        "timestamp_type": "DEADLINE",
        "timestamp_active": true,
        "timestamp_date": "2025-12-06",
        "days_offset": 1
      }
    ]
  }
]

The days_offset field encodes:

• Positive number — days until the deadline (upcoming)
• Negative number — days the task is overdue
• Absent for tasks belonging to the day itself (scheduled)

Markdown

File paths and timestamps are wrapped in inline code (`...`) to preserve formatting. Type: uses TODO / DONE (not Todo / Done); Priority: is shown as a bare letter without the [#] wrapper.

# Agenda

## 2025-12-05

### Overdue

#### Design database schema (365 days ago)
**File:** `project-tasks.md:5`
**Type:** TODO
**Priority:** A
**Time:** `SCHEDULED: <2024-12-05 Wed>`

Need to finalize the database structure before implementation.

### Scheduled

#### Daily standup
**File:** `project-tasks.md:33`
**Time:** `<2025-12-05 Friday 09:00-09:15>`

Daily standup meeting.

### Upcoming

#### Review pull request \#42 (in 1 days)
**File:** `project-tasks.md:47`
**Type:** TODO
**Time:** `DEADLINE: <2025-12-06 Sat>`

Critical bug fix needs review.

Parsed timestamp fields

To let downstream consumers render agendas without re-parsing the timestamp string, the timestamp is split into structured fields:

• timestamp_type — SCHEDULED, DEADLINE, CLOSED, or PLAIN
• timestamp_active — bracket form: true for active <...>, false for inactive [...]; omitted when no timestamp is present (see ADR-0014)
• timestamp_date — date as YYYY-MM-DD
• timestamp_time — start time, e.g. 10:00 (when present)
• timestamp_end_time — end time, e.g. 12:00 (when a range was given)

Task properties

• properties (object, optional): per-task key/value pairs parsed from an org-properties fenced code block placed under the heading and its planning lines. Bare UPPER_SNAKE: value lines; absent when a task has no such block. See ADR-0020.

On disk the block sits under the heading and planning lines:

### TODO Ship release
`SCHEDULED: <2026-06-01 Mon 10:00>`
```org-properties
GCAL_EVENT_ID: abc123/primary
```

Repeating tasks

The utility honours org-mode repeater syntax for automatically scheduling follow-up occurrences.

Repeater kinds

Every standard org-mode unit is supported:

• +Nh — every N hours
• +Nd — every N days (strict; preserves the original date offset)
• +Nw — every N weeks
• +Nm — every N months
• +Ny — every N years
• +Nwd — every N working days (project extension; honours RF holidays and weekends)

Repeater modifiers:

• + — strict (cumulative); preserves the date offset
• ++ — catch-up (smart); preserves the weekday
• .+ — restart-from-completion (relative to the close date)

Working days

Repeaters with the wd (workday) suffix take into account:

• Regular weekends (Saturday, Sunday)
• Official RF holidays
• Holiday shifts

Holiday data lives in holidays_ru.json. At build time (build.rs) the data is compiled into static Rust constants — the JSON is parsed once during compilation rather than at runtime.

Examples

### TODO Hourly check
`SCHEDULED: <2025-12-05 Thu 10:00 +1h>`

### TODO Daily task
`SCHEDULED: <2025-12-05 Thu +1d>`

### TODO Weekly meeting
`SCHEDULED: <2025-12-05 Thu +1w>`

### TODO Monthly report
`SCHEDULED: <2025-12-05 Thu +1m>`

### TODO Annual review
`SCHEDULED: <2025-12-05 Thu +1y>`

### TODO Workday-only task
`SCHEDULED: <2025-12-05 Thu +1wd>`

### TODO Every two working days
`SCHEDULED: <2025-12-05 Thu +2wd>`

Project layout

markdown-org-extract/
├── src/
│   ├── main.rs             # CLI entry point, file walker, file I/O
│   ├── cli.rs              # Argument parsing (clap), tracing init
│   ├── agenda.rs           # Agenda logic (day/week/month), repeaters
│   ├── parser.rs           # Task extraction from the markdown AST
│   ├── render.rs           # Markdown/HTML rendering
│   ├── format.rs           # OutputFormat (clap ValueEnum)
│   ├── error.rs            # AppError
│   ├── types.rs            # Task / Priority / DayAgenda / ProcessingStats
│   ├── clock.rs            # CLOCK parsing and time aggregation
│   ├── holidays.rs         # RF workday calendar (singleton, binary search)
│   ├── regex_limits.rs     # `compile_bounded`: regex with size/DFA caps
│   └── timestamp/          # Org-mode timestamp parsing
│       ├── parser.rs       #   <2024-12-05 Thu 10:00 +1d> → ParsedTimestamp
│       ├── extract.rs      #   pull timestamp/CREATED out of arbitrary text
│       ├── repeater.rs     #   parsing and arithmetic of repeaters (+1d, ++2w, .+1wd…)
│       └── weekdays.rs     #   normalisation of Russian weekday names
├── tests/
│   └── cli.rs              # CLI integration tests (assert_cmd)
├── examples/               # Sample markdown files
├── docs/                   # Supplementary documentation
├── scripts/                # Developer helper scripts (see table below)
├── holidays_ru.json        # RF holiday / workday calendar
├── build.rs                # Generates holidays_data.rs at build time
├── rustfmt.toml            # Formatter settings (edition 2021, width 100)
├── rust-toolchain.toml     # Pinned channel = stable, components rustfmt+clippy
├── .github/workflows/
│   ├── ci.yml              # PR/push CI: lint + test matrix (Linux/macOS/Windows) + cargo audit
│   ├── release.yml         # Publish to crates.io on tag v* (+ workflow_dispatch)
│   └── outdated.yml        # Weekly non-blocking `cargo outdated`
├── Cargo.toml
├── CHANGELOG.md
├── TODO.md                 # Deferred technical tasks
├── LICENSE                 # MIT
└── README.md

Helper scripts

The scripts/ directory holds developer-facing helpers. None of them ship to end users on crates.io (the Cargo.toml exclude list omits the whole directory).

Script	Purpose
scripts/check.sh	Full CI parity locally: fmt --check + yamllint + clippy -D warnings + doc -D warnings + cargo test. Run before every commit; CI runs the same steps
scripts/install-hooks.sh	Install a git pre-commit hook that delegates to scripts/check.sh. Pass --force to overwrite an existing hook
scripts/audit.sh	RustSec advisory scan (cargo audit) for a pre-push / pre-release run. Kept out of check.sh so the commit loop stays offline and fast; skips with an install hint if cargo-audit is absent. CI runs the same check via rustsec/audit-check
scripts/check-changelog.sh	Validate CHANGELOG.md shape before tagging: ## [Unreleased] empty, latest version section present, version numbers monotonic
scripts/package-archive.sh	Build a release archive (.tar.gz on Linux / macOS, .zip on Windows) with a deterministic layout. Used by .github/workflows/release.yml
scripts/verify-archive.sh	Verify a release archive's filename, layout, and SHA-256. Mirrors what downstream packagers run
scripts/release-validate-tag.sh	Validate that a release tag follows vX.Y.Z[-pre+build]. Called from .github/workflows/release.yml on both push-tag and workflow_dispatch paths
scripts/release-prep.sh	Print the canonical annotated-tag message for a version: the v<X.Y.Z> subject plus the CHANGELOG.md section body (### subheadings included). Argument is the bare version, no v prefix (e.g. 0.7.0, not v0.7.0). Tag with git tag -a vX.Y.Z --cleanup=verbatim -F <(scripts/release-prep.sh X.Y.Z) — --cleanup=verbatim is required, otherwise the default cleanup deletes the ### headings as comment lines
scripts/release-verify-tag-body.sh	Check that the release tag is annotated and its body mirrors the CHANGELOG.md section (ADR-0011). Argument is the bare version, no v prefix (the script prepends v internally to look up the tag); e.g. scripts/release-verify-tag-body.sh 0.7.0 checks tag v0.7.0. Run from .github/workflows/release.yml before publishing; also runnable locally right after tagging

The Cargo.toml exclude list omits docs/, .github/, scripts/, TODO.md, and CHANGELOG.md from the published crate tarball on crates.io — these files matter for repository contributors but not for downstream cargo install users. The GitHub Release archives keep the binary, README, and LICENSE only (see "For downstream packagers" above).

See also:

• docs/adr/ — architectural and policy decisions index
• docs/adr/0002-supported-org-mode-subset.md — supported Org-mode subset
• docs/adr/0003-clock-metadata-support.md — CLOCK marker implementation details
• docs/adr/0014-active-and-inactive-timestamps.md — active vs inactive timestamp bracket policy
• CHANGELOG.md — version history
• TODO.md — deferred technical tasks

Dependencies

• clap — command-line argument parsing
• comrak — markdown parsing (without onig/syntect: default-features = false)
• regex — regular expressions (with size/DFA caps)
• serde / serde_json — data serialisation
• chrono / chrono-tz — dates and timezones
• grep-regex / grep-searcher — fast pre-filter over keywords
• ignore — directory tree walk that honours .gitignore
• globset — glob compilation for --glob
• tracing / tracing-subscriber — structured diagnostic logging (--verbose, --quiet, --color, --no-color)

Lazily initialised static regular expressions use std::sync::LazyLock from the standard library (Rust 1.80+; the project itself requires 1.85).

License

MIT — see the LICENSE file.

Provenance of holidays_ru.json

The holiday calendar and weekend-shift table in holidays_ru.json was compiled by the project author from the official RF government decrees on weekend rescheduling. This is public factual information and is not subject to copyright. For packaging convenience the file is distributed under the same MIT licence as the rest of the code.

Attribution and a schema description are duplicated inside the file itself under the _meta key (build.rs ignores underscore-prefixed top-level keys, so the block has no effect on the compiled output).