mirror of https://github.com/TriliumNext/Trilium.git synced 2026-10-12 02:09:59 +00:00

Files

T

Elian DoranandClaude Fable 5.1 b40e00f9cc feat(docs): writing-documentation skill and a headless edit-docs sync

The User Guide could only be regenerated by opening edit-docs in Electron
and nudging a note: the export runs 10 s after an entity change and never
on close, so a Markdown page edited by hand left the in-app help HTML and
both help metas stale. `pnpm edit-docs:sync-docs` runs the same import and
export with no window. The import/export half of edit-docs moves into
`docs_pipeline.ts`, which has no Electron import; `utils.ts` keeps the
window and IPC setup. On a clean tree the sync is byte-stable apart from
two hunks of the known editor normalization, and a
new → image → rename → move → delete cycle leaves `!!!meta.json` identical.

The skill records what the tree expects and puts the rest in a script.
`docs.mjs` scaffolds a page with a complete meta entry (noteId, notePath,
position, alias, icon), registers images as attachments, renames, moves
and deletes pages (refusing when a `helpPage` literal links the ID), maps
a branch's changed UI strings and touched components to the pages that
mention them, and audits the trees: meta against disk, links, images,
icon classes, alias-path uniqueness, help IDs and docs URLs hard-coded in
the app. `check` already found stale `[missing note]` pills, links to
private-tree note IDs and three broken website URLs, which come in
separate commits.

The references hold the house style extracted from the 276 pages
(register, pills, `<kbd>`, admonitions, figures, the `bx`/`cke` icon
spans), page skeletons per kind, and how the trees feed the in-app help
and the docs site. CLAUDE.md and CONTRIBUTING.md make the rule binding:
a user-facing change is documented in the same commit, checked with
`impact --diff`, `sync` and `check`.

Co-Authored-By: Claude Fable 5.1 <[email protected]>

2026-09-25 16:57:01 +03:00

5.3 KiB

Raw Permalink Blame History

Contributing to Trilium Notes

Thank you for wanting to help. Trilium is maintained by a small team, and small, focused contributions are the easiest to review and merge.

This guide is about code contributions. To help translate Trilium, use Weblate. To work on the documentation, see the Documentation guide.

Before you start

Search existing issues and pull requests first, so the work is not done twice.
For a bug fix or a documentation change, you can open a pull request directly.
For a feature of any size, first open or find a feature request or idea and wait for maintainer feedback before you start coding. Some well-made pull requests must be declined only because they do not fit the philosophy of Trilium; discussing first avoids that risk and saves effort on both sides.
To set up a build, see Environment Setup and Project Structure.

Project constraints

Trilium is a hierarchical note-taking application for building large personal knowledge bases. Keep these constraints in mind:

Everything must work offline. Features that need an online service cannot go into the core. A few features fetch external data, such as map tiles for geo maps or OCR data, but libraries must always be embedded in the application, never loaded from a CDN.
Bundle size is very important. A new dependency cannot be added without checking that it does not negatively impact the bundle size.
User data must stay usable for decades. We avoid dependencies with proprietary formats, unless the data can be fully imported or exported, as with the XLSX and CSV interoperability of spreadsheets.
Protect existing user data. Discuss changes to storage, sync, or encryption with maintainers before coding, because these changes can put existing databases at risk.

Bug fixes

Check whether the bug still occurs on the latest nightly build. If you cannot run nightly, say which version you tested.
Give reproduction steps, relevant logs, or a failing test. Fixes are much easier to accept when reviewers can verify the problem.
Fix the underlying cause rather than hiding the symptom. For example, a manual refresh button that hides a rendering bug will not be accepted.

Features

A feature is easier to review and accept when it:

implements an existing feature request that other users also want;
keeps current behavior unchanged by default (new behavior is opt-in);
reuses components that already exist in the application;
adds no new dependency, or only a small one that is useful in more places.

A feature idea will likely be declined when it:

can be built as a user script or custom widget instead. Trilium is very scriptable, and specialized needs fit well there;
duplicates something the application can already do;
adds a setting for a single use case. Each setting adds long-term maintenance and testing work;
is better handled outside Trilium, for example HTTP Basic Authentication at a reverse proxy, or packaging-only concerns.

Discuss every feature in a feature request or idea before implementation, especially changes to default behavior, visible UI defaults, or new settings.

Some areas are maintainer-led because they involve many architectural decisions: the mobile apps, sync and encryption architecture, the trilium:// protocol, the storage model, and areas under active maintainer redesign. Discuss these first; implementations without an agreed plan are unlikely to be reviewed.

For a large feature, agree on the design and the delivery phases before implementation. Explain how partial work will avoid disrupting existing users.

Pull requests

Keep the pull request small and focused on one problem. Split unrelated changes.
Link the related issue. Use a GitHub closing keyword only when the pull request fully resolves it.
Add or update tests for the behavior you change. See the Testing guide.
Include a screenshot or short recording when the user interface changes.
When behavior changes, update the User Guide (docs/User Guide) in the same pull request — in the editor (pnpm edit-docs:edit-docs) or by editing the Markdown and running pnpm edit-docs:sync-docs, which regenerates the in-app help from it. Never edit the generated files under apps/server/src/assets/doc_notes. The Developer Guide can be edited directly.
Every pull request is manually tested and reviewed by a maintainer. Review can take time, especially for large changes. Update the branch when it conflicts with main or when a maintainer asks.

AI-assisted contributions

You are responsible for everything you submit, whether or not you used AI tools. Review and test generated changes, and be ready to explain them.

Bulk or unverified submissions may be closed without detailed review. For architecture-scale work, agree with a maintainer on the design and on expectations for AI use before coding.

Conduct

Please treat each other with respect and understanding.

5.3 KiB Raw Permalink Blame History