Easy Bookkeeping

中文 | English

Project overview

Easy Bookkeeping is a minimalist local bookkeeping plugin for Obsidian, with separate desktop and mobile entry modes. It provides:

• Cross-platform support: use it on phones and computers, and transfer transactions through CSV;
• Multiple languages: support for 12 languages, including Simplified Chinese, Traditional Chinese, English, Japanese, and Korean;
• Minimalist bookkeeping: use concise categories and rapidly enter transactions for different dates in one continuous session;
• Multiple charts: income and expense trends, calendar charts, pie charts, tag summaries, budgets, and account balances;
• Multidimensional tables: clearly display transaction details with multiple sorting methods;
• Flexible filtering: basic filters, range filters, cross-month filters, and filter-result export.

Everyday bookkeeping works offline, with transactions stored locally as Markdown. Templates, recurring rules, exchange rates, saved filters, budget snapshots, savings goals, and plugin settings are stored in data.json. Optional AI analysis and rate fetching connect to external services only when requested. The project is completely open source and highly customizable.

Author on Bilibili: 北漠海 Introduction video: bilibili Change log: ChangeLog.md

The plugin has not yet undergone long-term use by the author or exhaustive testing. If you encounter a bug, contact the author on Bilibili or join QQ group 588526922. I may not review Issues and Pull requests promptly.

Quick start

Install from the Obsidian community plugin catalog

1. Search for Easy Bookkeeping under Settings → Community plugins → Browse, or open the plugin page directly;
2. Select Install, then Enable.

Install from GitHub Releases

1. Download the attached main.js, manifest.json, and styles.css from Releases;
2. Create .obsidian/plugins/easy-bookkeeping/ inside your vault and place all three files there. You may need to enable the display of hidden folders;
3. Restart Obsidian and enable Easy Bookkeeping under Settings → Community plugins.

For a manual update, replace only main.js, manifest.json, and styles.css. Keep the existing data.json, or settings, templates, recurring rules, and rate configuration will be lost. A complete backup includes both the ledger directory and data.json in the plugin directory.

Install from a cloud drive

1. Open the Quark Drive link, save it, and download the latest plugin;
2. Extract the easy-bookkeeping folder into .obsidian/plugins/ inside your vault, then restart Obsidian and enable the plugin.

Install with BRAT

1. Download BRAT from the Obsidian community plugin catalog;
2. Add a new beta plugin and paste https://github.com/beimohai/Easy-Bookkeeping-Obsidian into the repository field.

Build from source

npm ci
npm run build

The production build generates main.js in the project root.

Feature overview

The default interface and six basic settings categories follow stable release 2.0.11. New features live in Beta features at the end of settings. Both the master switch and individual switches default to off; related menus, commands, and configuration appear only when enabled. Beta covers storage switching, AI, loans, schedules, templates, currencies, linked transactions, planning, goals, saved views/reports, diagnostics/recovery tools, note embeds, extended periods, and advanced display settings. Disabling retains records and configuration. Existing daily files, currency snapshots, and linked records remain readable, and integrity protection and interrupted-operation recovery remain active.

1. Fast entry and input validation

   • The desktop mode uses a single-input keyboard workflow for date, account, type, necessity, category, attachment, description, amount, and notes, without requiring a mouse;
   • The mobile mode provides a complete touch-friendly form. The plugin can detect the device automatically or use a manually selected desktop or mobile mode;
   • Continuous entry can be enabled independently on desktop and mobile. Transactions created from the dashboard automatically use the currently displayed month;
   • Date, description, amount, notes, account, type, necessity, category, and attachments follow the configured entry order. Notes can be disabled, while date, description, and amount are always kept;
   • Add text or select entry fields to forms, keyboard entry, and transaction details. Select presets support defaults, unique codes, drag sorting, and restoration to their creation-time snapshot;
   • Amounts accept plain numbers and arithmetic expressions such as 11.4+5.1-4. A transaction is not created when an input contains invalid characters or more than two decimal places;
   • Desktop entry shortcuts, same-day duplicate-description validation, numeric-only description validation, empty-amount validation, and attachment drag-and-drop are configurable. Global shortcuts are configured through Obsidian's built-in hotkey settings.

2. Bookkeeping dashboard and annual statistics

   • View monthly income, expenses, net balance, and transaction count. Changing the displayed month also changes the month used for entry;
   • Choose whether closing the dashboard resets the page, preserves the current filter, or preserves an independent view for each month;
   • Header actions can be reordered by dragging and either shown directly or placed in the three-dot menu;
   • Annual statistics retain the monthly income, expense, net balance, count table, and configurable charts. Enable Extended period statistics in Beta to select weeks, months, quarters, or years;
   • Open chart management, tag management, CSV import/export, yearly statistics, rescanning, and settings directly from the dashboard.

3. Customizable charts

   • Daily trends support income, expenses, net balance, and account balance, with line, area, and bar styles;
   • Calendar charts support daily income, expenses, and net balance, with any day from Sunday through Saturday as the first day of the week;
   • Pie charts support expense categories, income categories, necessity, account expenses, account income, and account balances, with both amounts and percentages;
   • Tag summaries support income, expenses, net balance, and transaction count, sorted by amount or tag name in ascending or descending order;
   • Budget progress and account balances are independent charts with dedicated editors for budgets and monthly opening balances;
   • Charts can be added, removed, hidden, duplicated, reordered by dragging, and switched between half and full width. Summary cards, income/expense pies, and tag summaries use the filtered transaction-detail result. Account-balance pies use historical transactions and the selected accounts, rather than truncating balances to the displayed month or keyword matches.

4. Multidimensional transaction details

   • Customize column names, order, visibility, inline-edit permissions, and widths. Columns can be resized by dragging or restored to their default widths;
   • Permanently visible horizontal scrollbars above and below the table stay synchronized, while the selection column remains fixed on the left;
   • Date order can be locked as the primary sort. Transactions on the same date can then be sorted by time, description, type, necessity, category, account, or amount;
   • When inline editing is enabled, configured columns can directly edit dates, descriptions, preset fields, amount formulas, notes, and tags. Invalid input produces a localized message;
   • Edit foreign-currency amounts in the full transaction editor to keep original and base-currency amounts unambiguous;
   • Selected transactions can be updated in bulk for date, type, necessity, account, category, enabled custom select fields, and tags, or deleted together;
   • Results are paginated at 100 transactions per page. Enable Advanced display settings in Beta to change the limit. Select all covers the complete filtered result rather than only the current page;
   • Long descriptions, notes, tags, and preset values are automatically truncated according to the available width.

5. Linked filters and search

   • Type, necessity, category, account, tag, and custom select fields support multiple selection, select all, keyword search, and linked values based on the current result;
   • Search descriptions, notes, tags, and every custom field, and set minimum and maximum amounts or start and end dates. Search waits until IME composition is complete;
   • Amount ranges use the base currency and accept only non-negative values with at most two decimal places. Both amount and date ranges validate their lower and upper bounds;
   • Cross-month filtering applies to every filter condition and turns on automatically when the date range extends outside the displayed month;
   • Transaction details, income, expenses, net balance, transaction count, income/expense pies, and tag summaries use the same filtered result; account-balance pies retain historical balances;
   • Selecting an account balance, tag summary, or transaction tag applies the matching filter without changing the current page position or forcing a collapsed filter panel open.

6. Accounts, budgets, tags, and attachments

   • Support multiple accounts, custom account codes and order, transfers, editable monthly opening balances, and automatic carry-over; enable accounts and configure at least two accounts to record a transfer;
   • Set overall and category budgets and view their usage in budget progress charts;
   • Add or remove tags on individual transactions, create empty tags, or globally rename, delete, and batch-process tags and related transactions;
   • Tags can be entered directly in notes: leading #tag tokens are parsed as tags, spaces separate multiple tags, and parsed tags are not written to the note. Consecutive spaces count as one separator, while note text itself is preserved. After the first space-separated segment that does not start with #, everything after it remains note text, even if it contains more spaces or # characters;
   • Drop receipts or invoices into the desktop form or select files on mobile. Attachments are stored automatically in the configured folder and named after the corresponding transaction file;
   • Preview attachments in both Markdown files and the transaction editor, then select a preview to open the original file.

7. Data import, export, and migration

   • CSV import detects field and preset differences and requests confirmation before converting data to the current settings;
   • CSV can carry the complete entry-field configuration. Import can keep the current setup or enable the attached setup after a second confirmation and old-property cleanup;
   • CSV import and legacy conversion show percentage progress and report failed items with specific reasons;
   • CSV export supports all transactions, the current month, current filtered results, or a custom date range, with configurable filenames and destinations;
   • CSV preserves transaction IDs and financial metadata across both storage modes. Identical content with different IDs is not merged solely by content, and conflicting IDs are not silently overwritten. Exporting related entries without their originals produces health-check warnings. CSV is not a full backup of note bodies, templates, or settings;
   • On desktop, use the operating-system save dialog to export outside the Obsidian vault;
   • Legacy conversion can process a folder inside the vault into current Properties and moves each successfully converted vault file to the system trash; external-folder import leaves originals untouched;
   • Expressions found in legacy notes can be migrated to the current expression-storage mode, and duplicate transactions are skipped automatically.

8. Local storage and safe operations

   • The default is one Markdown file per transaction. Enable Markdown storage in Beta to switch to one file per day. Both layouts keep independent UUIDs, and conversion writes the destination before removing old files;
   • UUIDs enable record-level deletion and undo even when several transactions share one daily file;
   • Storage conversion preserves original properties and body text, keeping recovery backups in _bookkeeping-recovery. On startup, interrupted conversions are checked for recovery; conflicting external edits block further writes. Backups contain original ledger data and need the same protection. Pause editing on other devices during conversion; both layouts remain subject to file-sync and Git conflicts;
   • Enable AI analysis in Beta to configure Chat Completions-compatible, Anthropic Messages, Gemini generateContent, or keyless local endpoints. Analyze filtered results from the dashboard overflow menu, preview aggregates, and edit the prompt. Replies support Markdown preview and a source toggle. Payloads include currency and date scope, excluding individual descriptions, notes, tag values, account values, and attachments;
   • API keys are stored in plugin settings and may travel with vault or settings synchronization. They are excluded from analysis prompts but used for API authentication. Stopping the wait cannot withdraw a request already received by the server;
   • Expressions can optionally be written to notes. When this is disabled, newly saved transactions no longer keep a dedicated expression property, and existing files can be converted after the setting changes;
   • Deletion supports a confirmation dialog and a configurable undo period from 0 to 15 seconds;
   • When deleting a custom entry field, choose whether to preserve its historical Markdown property or remove that property from all existing transactions;
   • File changes refresh automatically, and the dashboard can also be rescanned manually;
   • After publication in the community plugin catalog, updates are handled by Obsidian. Manual installations can be updated by downloading the new files again from GitHub Releases or the cloud-drive mirror.

9. Extensive customization and multiple languages

   • Type, necessity, category, and account presets support adding, deleting, renaming, unique custom codes, drag sorting, restoring defaults, and default values;
   • Customize the currency symbol, resettable income and expense colors, number grouping, year-month format, date format, time format, and first day of the week;
   • Charts, header actions, entry fields, transaction columns, column widths, edit permissions, and shortcuts are configurable;
   • Phone, tablet, and desktop layouts adapt to the available width. Mobile summary cards remain in two columns, while charts switch to one column;
   • Supports Simplified Chinese, Traditional Chinese, English, French, Russian, Spanish, Arabic, Japanese, Korean, German, Portuguese, and Persian;
   • The interface, settings, filters, statistics, and messages follow the selected language, while transaction descriptions, user tags, and notes remain unchanged.

10. Ledger management and advanced entries

• Enable individual tools under Beta features. Ledger management and its settings shortcuts expose only enabled pages. Record overflow actions for refunds, reimbursements, splitting, and links also follow their switches;
• Loans track counterparties, due dates, overdue balances and partial repayments or collections. Principal affects account balances, not income or expenses; record interest separately;
• Daily, weekly, monthly and yearly rules preview due entries before confirmation, prevent repeated generation on this device, and retain month-end anchors. Nothing runs while the plugin is closed;
• Create templates manually or from existing entries and edit before posting. Currency snapshots retain original amounts, rates and quote dates; statistics and account balances use the base currency;
• Rates are manual and offline by default. Fetch latest rates uses Frankfurter reference rates without a key and sends currency codes only. Rate updates never reprice historical entries;
• Partial refunds and reimbursements link to original expenses and cannot exceed the unsettled amount. They appear as separate inflows while original expenses remain, so gross expenses stay unchanged and net cash flow reflects the inflows. Splits must total the original amount, retaining the first entry ID and assigning IDs to other parts;
• Read-only health checks can export reports and rebuild the index. Recovery tools inspect backups, recover interrupted operations, or undo completed conversions and batches only when affected files still match the saved states;
• Both storage modes share record-level operations. File events invalidate the index; bookkeeping note blocks embed entries and UUID links survive file moves and storage conversion.

See the advanced bookkeeping guide (Chinese) for accounting rules and synchronization boundaries. The project audit (Chinese) records fixes, test coverage, and unimplemented suggestions. New tools are grouped under Beta and documented in the 3.0.0 changelog; enable only the tools you need.

Limits and note integration

• Set a base currency before using multiple currencies, then maintain manual rates or explicitly fetch quotes. The base currency cannot be directly changed once financial snapshots, templates, or recurring rules exist. New rates never reprice historical entries. Exchange gains/losses and dual-currency transfer valuation are not provided; all currencies currently use two decimal places.
• Recurring entries require manual preview and confirmation while the plugin is open, with at most 120 occurrences per rule per batch. Local duplicate prevention is not a distributed lock. Loans do not calculate interest or amortization schedules, and reimbursement receipts do not implement an approval workflow.
• Both layouts share plugin-level record operations, but native Properties and Dataview do not automatically treat each daily-file record as a separate page. File-sync conflicts remain possible: back up first and pause other devices during migration. Recovery requires matching file states and never force-overwrites subsequent edits.

Embed a read-only list in any note using the following block. All filters are optional; the default limit is 20 and the maximum is 200. Select an entry to open its editor by UUID; copied transaction links are also independent of file paths.

```bookkeeping
month: 2026-10
account: 默认账户
currency: USD
limit: 20
```

Tasks, forecasts, goals, and reports

• Pending reimbursements and refunds: Set an expected base-currency amount and due date from an entry’s linked actions. Track partial receipts, close or reopen tasks, and record actual receipts separately without changing the original expense. Expectations do not create income. Remove the task before splitting its entry.
• Tasks and forecast: The ledger manager combines open tasks, due loans, and ungenerated recurring entries in a 90-day forecast by default. Configure lead days, sources, and an optional dashboard shortcut. There are no background notifications or automatic entries; projected net inflow is not an available balance. Undated tasks are excluded, overdue tasks remain visible, and foreign recurring entries use current manual rates.
• Saved filters and reports: Save the selected month and complete filters from the dashboard overflow menu. Preview reports using only the selection captured when the panel opened, including cross-month selections. Existing notes are never overwritten. Reports contain totals by default; configure details and destination in settings. Filter conditions and selected IDs are included, so check privacy before sharing.
• Budgets and goals: Choose no rollover, surplus-only rollover, or surplus-and-deficit rollover in settings. Accumulation begins in the first activation month; budget edits save a snapshot for the selected month. Budget cards show adjusted allowances. Savings goals support targets, due dates, and manually updated saved amounts, without altering or automatically binding account balances.
• Health explanations and repair previews: Read issue explanations and advice. Missing IDs support before/after previews, confirmed repair, recovery journals, and conflict checks. Other issues only preview and open the original for manual review; no automatic merging, deletion, or guessed amounts. ID repair may reformat YAML but preserves field values and body text.
• Customization: Switches and configuration are grouped under Beta features. Enabled tools offer 20–500 rows per page, report content, embed limits, and displayed health issue limits. Disabling retains data. Pending metadata survives both Markdown layouts and CSV; saved views, goals, and budget snapshots live in data.json and require backing up that file.

File structure

By default, each transaction is stored as an independent Markdown file, for example:

---
记账插件: true
账目ID: 3b6d8c8a-5f0c-4a36-a0f7-0a24f1ab5af7
时间: 2026-07-21 11:45
类型: 支出
标签: 必需
分类: 未分类
账户: 默认账户
内容: 午餐
金额: 19.19
备注: 无
附件: []
---

Enable Markdown storage under Beta features to choose one file per transaction or per day. Disabling Beta does not convert existing files. Daily files store records in 账目列表, each with its own 账目ID, for example:

---
记账插件: true
账目列表:
  - 账目ID: 3b6d8c8a-5f0c-4a36-a0f7-0a24f1ab5af7
    时间: 2026-07-21 11:45
    类型: 支出
    内容: 午餐
    金额: 19.19
    附件: []
---

Foreign-currency, loan, refund, and other financial entries also carry 财务扩展 metadata for original amounts, rate snapshots, or related IDs. 金额 always holds the base-currency amount used in statistics. Keep the 记账插件 compatibility marker and transaction IDs; manually duplicating an ID does not create a new transaction.

The transaction paths below are alternative layouts, not two required copies. Recovery backups and health reports are kept inside the ledger directory and excluded from transaction statistics.

Ledger directory/
├─ YYYY/MM/
│  ├─ DD/transaction.md    # One file per transaction
│  └─ DD.md                # One file per day
├─ _bookkeeping-recovery/  # Recovery backups containing original data
├─ .bookkeeping-reports/   # Health-check reports
├─ 导出/transactions.csv
└─ 附件/                  # Attachment location is configurable

Sponsorship and support

If you like my plugin, you can support me here. Thank you!

• Report a problem
• Author on GitHub
• Author on Bilibili

License

This project is open source under the MIT License.

Open source makes the world more wonderful.