86 lines
3.1 KiB
Markdown
86 lines
3.1 KiB
Markdown
# **hledger** Discourse Plugin
|
|
|
|
[](https://gitea.kosmos.org/raucao/discourse-hledger/actions)
|
|
[](https://gitea.kosmos.org/raucao/discourse-hledger/releases)
|
|
|
|
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.
|
|
|
|
Account names can reference Discourse users: a path segment written as
|
|
`@username` (for example `equity:@alice`) is rendered as a mention link, with the
|
|
same profile card as mentions in posts. Only segments matching an existing user
|
|
are linked; anything else stays plain text.
|
|
|
|
## 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
|
|
|
|
## Contact
|
|
|
|
E-Mail, Chat, Social, Lightning: raucao@kosmos.org
|