Hledger Plugin - Render plain-text accounting journals in topics

Customization Plugin
1
:information_source: Summary Render hledger journals as a live dashboard in the first post of a topic.
:hammer_and_wrench: Repository gitea.kosmos.org/raucao/discourse-hledger
:open_book: Install Guide README

Features

Put an hledger journal in a fenced hledger code block in a topic’s first post and it is replaced by a dashboard with five reports, generated on demand by the server’s hledger executable:

  • :clipboard: Accounts — the full balance tree, every parent account expanded.

  • :balance_scale: Balance sheet — assets, liabilities and equity, folded into sections.

  • :chart_increasing: P&L — revenues and expenses.

  • :busts_in_silhouette: Equity — a per-commodity distribution of contributed capital.

  • :receipt: Journal — a transaction log with each posting.

  • Reports can be filtered by a From/To date range; the end date is inclusive.

  • Account segments written as @username (for example equity:@alice) become
    Discourse mention links with the usual profile card; only existing users are
    linked.

  • Reports are generated on demand and cached per post revision, so editing the
    journal refreshes them.

Example block

```hledger
2024-01-01 Opening balances
    assets:bank:checking       1000.00 EUR
    equity:alice               -600.00 EUR
    equity:bob                 -400.00 EUR
```

Screenshots

Accounts
Accounts1400×1200 72.7 KB

P&L
P&L1400×1200 52.1 KB

Journal
Journal1400×1200 103 KB

Requirements

  • The hledger executable on the server (tested with hledger 1.32.3).
  • Discourse 2.7.0 or newer.

With the standard Docker install, install the plugin and the hledger package through your app.yml and rebuild:

hooks:
  after_code:
    - exec:
        cd: $home/plugins
        cmd:
          - git clone https://gitea.kosmos.org/raucao/discourse-hledger.git discourse-hledger
    - exec:
        cd: $home
        cmd:
          - apt-get update
          - DEBIAN_FRONTEND=noninteractive apt-get install -y hledger

Configuration

  1. Enable the plugin in Admin > Settings > Plugins (hledger enabled).
  2. Add an hledger journal to the first post of a topic.
  3. Optionally set hledger path if the executable is not on the default PATH.

Settings

Name Description
hledger enabled Enable the plugin.
hledger path Path to the hledger executable (default hledger).
hledger max journal bytes Maximum size of an accepted journal, in bytes (default 262144).
hledger max journal lines Maximum number of lines in a journal (default 5000).
hledger timeout seconds Wall-clock limit for each hledger invocation (default 10).
hledger max output bytes Cap on captured hledger output (default 1048576).
hledger memory limit mb Memory cap for the hledger process; 0 disables it (default 256).
hledger global rate limit per minute Cap on report generation across all users; 0 disables it (default 120).

Security

Journals are untrusted input. The plugin runs hledger as an unprivileged subprocess with a scrubbed environment, a private working directory, a hard timeout, CPU/file-size/memory limits and an output cap, and it rejects include directives. Reports are only returned for topics the viewer can see, and requests are rate-limited per IP (30/min) and globally.

Compatibility and license

  • MIT license
  • Feedback, bug reports and translations are welcome in this topic or via email, social media (ActivityPub), or chat (XMPP) to raucao@kosmos.org
2 Likes