# **hledger** Discourse Plugin

Render [hledger](https://hledger.org) journal reports inside Discourse topics.

Put an hledger journal in a fenced `hledger` code block in a topic's first
post. The block is replaced by a dashboard with five reports, generated live
by the `hledger` command line tool:

- Accounts and balances (a full account tree, each name capitalized)
- Balance sheet (indented account tree under each section)
- Profit & loss / P&L (indented account tree under each section)
- Equity distribution (account tree with per-commodity shares; contributed
  capital, not legal ownership)
- Journal (a detailed transaction log: date, description and postings)

## Installation

Follow the [plugin installation guide](https://meta.discourse.org/t/install-a-plugin/19157).

The plugin requires the `hledger` executable on the server. Install it with
your package manager (for example `apt-get install hledger`) and point the
`hledger path` site setting at it if it is not on the default `PATH`.

### Docker development environment

Inside the Discourse dev container, install the plugin's system dependencies
(hledger, Chromium and the Playwright browser used by the test suite) with:

```sh
docker exec -u root discourse_dev bash /src/plugins/hledger/bin/setup-dev
```

## How to use

1. Enable the plugin under `Admin > Settings > Plugins` (`hledger enabled`).
2. Add an hledger journal to the first post of a topic:

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

3. The code block is replaced by the report dashboard. Reports can be filtered
   by a start and end date; the end date is inclusive.

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

## Security

Journals are untrusted input. The plugin runs `hledger` with a scrubbed
environment, a private working directory, a hard timeout, resource limits and
an output cap, and it rejects `include` directives so a journal cannot read
arbitrary server files.

## Development

```sh
# Ruby specs (run `bin/setup-dev` first for the integration specs)
bin/rspec plugins/hledger/spec/lib plugins/hledger/spec/requests
bin/rspec plugins/hledger/spec/system

# Frontend tests
DISCOURSE_DISABLE_BROWSER_SANDBOX=1 bin/qunit plugins/hledger/test/javascripts
```

## License

MIT