mirror of
https://github.com/zadam/trilium.git
synced 2025-11-08 06:15:48 +01:00
docs(dev): reorganize and clean up technical documentation
This commit is contained in:
Elian Doran
1412
docs/Developer Guide/!!!meta.json
vendored
1412
docs/Developer Guide/!!!meta.json
vendored
File diff suppressed because it is too large
Load Diff
@@ -1,24 +0,0 @@
|
||||
# Documentation
|
||||
## Editing the documentation
|
||||
|
||||
To edit the documentation run `pnpm edit-docs:edit-docs`. This will spin up a custom Trilium desktop instance which automatically imports the documentation into memory. Any changes will update in the background the files which can then be committed.
|
||||
|
||||
## Automation
|
||||
|
||||
The documentation is built via `apps/build-docs`:
|
||||
|
||||
1. The output directory is cleared.
|
||||
2. The User Guide and the Developer Guide are built.
|
||||
1. The documentation from the repo is archived and imported into an in-memory instance.
|
||||
2. The documentation is exported using the shared theme.
|
||||
3. The API docs (internal and ETAPI) are statically rendered via Redocly.
|
||||
4. The script API is generated via `typedoc`
|
||||
|
||||
The `deploy-docs` workflow triggers the documentation build and uploads it to CloudFlare Pages.
|
||||
|
||||
## Building locally
|
||||
|
||||
In the Git root:
|
||||
|
||||
* Run `pnpm docs:build`. The built documentation will be available in `site` at Git root.
|
||||
* To also run a webserver to test it, run `pnpm docs:preview` (this will not build the documentation) and navigate to `localhost:9000`.
|
||||
@@ -8,7 +8,7 @@ Releases are usually made directly from the `main` branch.
|
||||
|
||||
The process is as follows:
|
||||
|
||||
1. Edit the <a class="reference-link" href="Documentation.md">Documentation</a> to add a corresponding entry in the _Release notes_ section.
|
||||
1. Edit the <a class="reference-link" href="../Documentation.md">Documentation</a> to add a corresponding entry in the _Release notes_ section.
|
||||
2. In the root `package.json`, set `version` to the new version to be released.
|
||||
3. Run `chore:update-version` to automatically update the version of the rest of the `package.json` files.
|
||||
4. Run `pnpm i` to update the package lock as well.
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
# Differences from upstream
|
||||
* Embeds [`~~isaul32/ckeditor5-math~~`](https://github.com/isaul32/ckeditor5-math) <a class="reference-link" href="../ckeditor5-math.md">ckeditor5-math</a>, which is a third-party plugin for adding math support. CKEditor itself also has a [math plugin](https://ckeditor.com/docs/ckeditor5/latest/features/math-equations.html) with MathType and ChemType but it's premium-only.
|
||||
* Embeds [`~~isaul32/ckeditor5-math~~`](https://github.com/isaul32/ckeditor5-math) <a class="reference-link" href="ckeditor5-math.md">ckeditor5-math</a>, which is a third-party plugin for adding math support. CKEditor itself also has a [math plugin](https://ckeditor.com/docs/ckeditor5/latest/features/math-equations.html) with MathType and ChemType but it's premium-only.
|
||||
* Zadam left a TODO in `findandreplaceUI`: `// FIXME: keyboard shortcut doesn't work:` [`https://github.com/ckeditor/ckeditor5/issues/10645`](https://github.com/ckeditor/ckeditor5/issues/10645)
|
||||
* `packages\ckeditor5-build-balloon-block\src\mention_customization.js` introduces note insertion via `@` character.
|
||||
|
||||
16
docs/Developer Guide/Developer Guide/Dependencies/CKEditor/ckeditor5-math.md
vendored
Normal file
16
docs/Developer Guide/Developer Guide/Dependencies/CKEditor/ckeditor5-math.md
vendored
Normal file
@@ -0,0 +1,16 @@
|
||||
# ckeditor5-math
|
||||
<figure class="image image-style-align-right"><img src="ckeditor5-math_image.png"><figcaption><code>ckeditor5-math</code> in action.</figcaption></figure>
|
||||
|
||||
A fork of [isaul32/ckeditor5-math](https://github.com/isaul32/ckeditor5-math), which is the CKEditor5 plugin which adds the math functionality. We keep our own version to be able to use it on the latest version of CKEditor, alongside some custom improvements.
|
||||
|
||||
## Development environment
|
||||
|
||||
* Tested on Node.js 20.
|
||||
* The package manager is yarn 1 (v1.22.22 is known to be working fine for it at the time of writing).
|
||||
|
||||
Important commands:
|
||||
|
||||
* To check if the code has any formatting issues: `yarn lint`
|
||||
* To start a live preview: `yarn start`
|
||||
* To run the tests: `yarn test`
|
||||
* Note that this requires Chromium, on NixOS this can be achieved by running a `nix-shell -p chromium`, and running `CHROME_BIN=$(which chromium) yarn test` inside it.
|
||||
|
Before Width: | Height: | Size: 10 KiB After Width: | Height: | Size: 10 KiB |
@@ -1,2 +1,2 @@
|
||||
# Updating dependencies
|
||||
<table class="ck-table-resized"><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Dependency</th><th>Name in <code>library_loader</code></th><th>Things to check for a basic sanity check</th><th> </th><th>Protected by unit tests</th></tr></thead><tbody><tr><td><code>better-sqlite3</code></td><td> </td><td>See <a class="reference-link" href="Updating%20dependencies/bettersqlite%20binaries.md">bettersqlite binaries</a>.</td><td> </td><td> </td></tr><tr><td><code>jsdom</code></td><td> </td><td><ul><li>Note map</li><li>Clipper</li><li>Note similarity</li></ul></td><td>Protected by typings, should catch any potential changes in API.</td><td>Yes</td></tr><tr><td><code>async-mutex</code></td><td> </td><td><ul><li>Sync</li></ul></td><td> </td><td> </td></tr><tr><td><code>axios</code></td><td> </td><td><ul><li>Can't be directly tested, as it's exposed only via the backend script API.</li></ul></td><td> </td><td> </td></tr><tr><td><code>sax</code></td><td> </td><td><ul><li>EverNote imports</li></ul></td><td> </td><td> </td></tr><tr><td><ul><li><code>ws</code></li><li><code>debounce</code></li></ul></td><td> </td><td><ul><li>Check any action is reported from server to client (e.g. delete a note).</li></ul></td><td> </td><td> </td></tr><tr><td><code>ejs</code></td><td> </td><td><ul><li>Onboarding / first setup</li></ul></td><td> </td><td> </td></tr><tr><td><code>dayjs</code></td><td> </td><td><ul><li>Day notes</li></ul></td><td> </td><td> </td></tr><tr><td><code>semver</code></td><td> </td><td><ul><li>Application should start.</li></ul></td><td> </td><td> </td></tr><tr><td><code>https-proxy-agent</code></td><td> </td><td>???</td><td> </td><td> </td></tr><tr><td><code>sax</code></td><td> </td><td><ul><li>EverNote import</li></ul></td><td> </td><td> </td></tr><tr><td><code>ini</code></td><td> </td><td><ul><li>Affects config, generally if the application starts then it should be OK.</li></ul></td><td> </td><td> </td></tr><tr><td><code>jsplumb</code></td><td><code>RELATION_MAP</code></td><td><ul><li>Relation map note type</li></ul></td><td> </td><td> </td></tr><tr><td><code>jquery.mark.es6</code></td><td><code>MARKJS</code></td><td><ul><li>In search, when highlighting the text that matched.</li><li>In search in HTML, which might not actually be used since it seems to have been replaced by CKEditor's own find & replace dialog.</li></ul></td><td> </td><td> </td></tr><tr><td><code>knockout.js</code></td><td> </td><td><ul><li>Used in rendering the login and main layout of the application.</li></ul></td><td> </td><td> </td></tr><tr><td><code>normalize.min.css</code></td><td> </td><td><ul><li>Used in shared notes.</li></ul></td><td> </td><td> </td></tr><tr><td><code>wheel-zoom.min.js</code></td><td><code>WHEEL_ZOOM</code></td><td><ul><li>When opening a image that is in attachment.</li><li>When opening a stand-alone image note.</li><li>When zooming in a mermaid chart.</li></ul></td><td> </td><td> </td></tr><tr><td><code>fancytree</code></td><td> </td><td><ul><li>The note tree should be fully functional.</li></ul></td><td> </td><td> </td></tr><tr><td><code>bootstrap</code></td><td> </td><td><ul><li>Check mostly the on-boarding pages, when there is no database.</li></ul></td><td> </td><td> </td></tr><tr><td><code>electron-debug</code></td><td> </td><td><ul><li>Run electron using <code>npm run start-electron</code> and check that the debug hotkeys are still working (Ctrl+Shift+I on Windows/Linux, Cmd+Alt+I for dev tools, Cmd/Ctrl+R for reload).</li></ul></td><td> </td><td> </td></tr><tr><td><code>electron-dl</code></td><td> </td><td> </td><td> </td><td> </td></tr><tr><td><code>eslint</code></td><td> </td><td> </td><td> </td><td> </td></tr><tr><td><code>marked</code></td><td> </td><td><ul><li>Importing a markdown note.</li></ul></td><td> </td><td>Yes</td></tr><tr><td><code>force-graph</code></td><td> </td><td><ul><li>Note map</li></ul></td><td> </td><td> </td></tr></tbody></table>
|
||||
# Per-dependency checks
|
||||
<table class="ck-table-resized"><colgroup><col> <col> <col> <col> <col></colgroup><thead><tr><th>Dependency</th><th>Name in <code>library_loader</code></th><th>Things to check for a basic sanity check</th><th> </th><th>Protected by unit tests</th></tr></thead><tbody><tr><td><code>better-sqlite3</code></td><td> </td><td>See <a class="reference-link" href="Per-dependency%20checks/bettersqlite%20binaries.md">bettersqlite binaries</a>.</td><td> </td><td> </td></tr><tr><td><code>jsdom</code></td><td> </td><td><ul><li>Note map</li><li>Clipper</li><li>Note similarity</li></ul></td><td>Protected by typings, should catch any potential changes in API.</td><td>Yes</td></tr><tr><td><code>async-mutex</code></td><td> </td><td><ul><li>Sync</li></ul></td><td> </td><td> </td></tr><tr><td><code>axios</code></td><td> </td><td><ul><li>Can't be directly tested, as it's exposed only via the backend script API.</li></ul></td><td> </td><td> </td></tr><tr><td><code>sax</code></td><td> </td><td><ul><li>EverNote imports</li></ul></td><td> </td><td> </td></tr><tr><td><ul><li><code>ws</code></li><li><code>debounce</code></li></ul></td><td> </td><td><ul><li>Check any action is reported from server to client (e.g. delete a note).</li></ul></td><td> </td><td> </td></tr><tr><td><code>ejs</code></td><td> </td><td><ul><li>Onboarding / first setup</li></ul></td><td> </td><td> </td></tr><tr><td><code>dayjs</code></td><td> </td><td><ul><li>Day notes</li></ul></td><td> </td><td> </td></tr><tr><td><code>semver</code></td><td> </td><td><ul><li>Application should start.</li></ul></td><td> </td><td> </td></tr><tr><td><code>https-proxy-agent</code></td><td> </td><td>???</td><td> </td><td> </td></tr><tr><td><code>sax</code></td><td> </td><td><ul><li>EverNote import</li></ul></td><td> </td><td> </td></tr><tr><td><code>ini</code></td><td> </td><td><ul><li>Affects config, generally if the application starts then it should be OK.</li></ul></td><td> </td><td> </td></tr><tr><td><code>jsplumb</code></td><td><code>RELATION_MAP</code></td><td><ul><li>Relation map note type</li></ul></td><td> </td><td> </td></tr><tr><td><code>jquery.mark.es6</code></td><td><code>MARKJS</code></td><td><ul><li>In search, when highlighting the text that matched.</li><li>In search in HTML, which might not actually be used since it seems to have been replaced by CKEditor's own find & replace dialog.</li></ul></td><td> </td><td> </td></tr><tr><td><code>knockout.js</code></td><td> </td><td><ul><li>Used in rendering the login and main layout of the application.</li></ul></td><td> </td><td> </td></tr><tr><td><code>normalize.min.css</code></td><td> </td><td><ul><li>Used in shared notes.</li></ul></td><td> </td><td> </td></tr><tr><td><code>wheel-zoom.min.js</code></td><td><code>WHEEL_ZOOM</code></td><td><ul><li>When opening a image that is in attachment.</li><li>When opening a stand-alone image note.</li><li>When zooming in a mermaid chart.</li></ul></td><td> </td><td> </td></tr><tr><td><code>fancytree</code></td><td> </td><td><ul><li>The note tree should be fully functional.</li></ul></td><td> </td><td> </td></tr><tr><td><code>bootstrap</code></td><td> </td><td><ul><li>Check mostly the on-boarding pages, when there is no database.</li></ul></td><td> </td><td> </td></tr><tr><td><code>electron-debug</code></td><td> </td><td><ul><li>Run electron using <code>npm run start-electron</code> and check that the debug hotkeys are still working (Ctrl+Shift+I on Windows/Linux, Cmd+Alt+I for dev tools, Cmd/Ctrl+R for reload).</li></ul></td><td> </td><td> </td></tr><tr><td><code>electron-dl</code></td><td> </td><td> </td><td> </td><td> </td></tr><tr><td><code>eslint</code></td><td> </td><td> </td><td> </td><td> </td></tr><tr><td><code>marked</code></td><td> </td><td><ul><li>Importing a markdown note.</li></ul></td><td> </td><td>Yes</td></tr><tr><td><code>force-graph</code></td><td> </td><td><ul><li>Note map</li></ul></td><td> </td><td> </td></tr></tbody></table>
|
||||
25
docs/Developer Guide/Developer Guide/Dependencies/Per-dependency checks/bettersqlite binaries.md
vendored
Normal file
25
docs/Developer Guide/Developer Guide/Dependencies/Per-dependency checks/bettersqlite binaries.md
vendored
Normal file
@@ -0,0 +1,25 @@
|
||||
# bettersqlite binaries
|
||||
### The native node bindings
|
||||
|
||||
`better-sqlite3` has native Node bindings. With updates of `better-sqlite3`, but also of Electron and Node.js versions, these bindings need to be updated.
|
||||
|
||||
Note that Electron and Node.js versions need different versions of these bindings, since Electron usually packs a different version of Node.js.
|
||||
|
||||
During development, `pnpm install` tries to build or reuse prebuilt natives for the current Node.js version. This makes `npm run start-server` work out of the box. Trying to run `npm run start-electron` with these versions generally causes an error such as this:
|
||||
|
||||
```
|
||||
Uncaught Exception:
|
||||
Error: The module '/Users/elian/Projects/Notes/node_modules/better-sqlite3/build/Release/better_sqlite3.node'
|
||||
was compiled against a different Node.js version using
|
||||
NODE_MODULE_VERSION 108. This version of Node.js requires
|
||||
NODE_MODULE_VERSION 116. Please try re-compiling or re-installing
|
||||
the module (for instance, using `npm rebuild` or `npm install`).
|
||||
```
|
||||
|
||||
### How the natives are handled
|
||||
|
||||
To avoid issues between the `server` and the `desktop`, the `desktop` build gets its own copy of the `bettersqlite3` dependency in its `node_module`. This copy is then rebuilt automatically to match the Electron version.
|
||||
|
||||
This process of rebuilding is handled by `scripts/electron-rebuild.mts` which runs automatically after `pnpm install` (via `postinstall`).
|
||||
|
||||
If needed, the script can be run manually again via `pnpm postinstall`.
|
||||
@@ -1,29 +1,32 @@
|
||||
# Documentation
|
||||
<figure class="image image-style-align-right"><img style="aspect-ratio:205/162;" src="Documentation_image.png" width="205" height="162"></figure>
|
||||
|
||||
There are multiple types of documentation for Trilium:
|
||||
There are multiple types of documentation for Trilium:<img class="image-style-align-right" src="api/attachments/2bUrJyt2yfsd/image/Documentation_image.png" width="205" height="162">
|
||||
|
||||
* The _User Guide_ represents the user-facing documentation. This documentation can be browsed by users directly from within Trilium, by pressing <kbd>F1</kbd>.
|
||||
* The _Developer's Guide_ represents a set of Markdown documents that present the internals of Trilium, for developers.
|
||||
* _Release Notes_, this contains the change log for each released or soon-to-be-released version. The release notes are used automatically by the CI when releasing a version.
|
||||
* The _Script API_, which is an automatically generated documentation for the front-end and back-end APIs for scripts.
|
||||
|
||||
## Editing documentation
|
||||
## Location of the documentation
|
||||
|
||||
All documentation is stored in the [Trilium](https://github.com/TriliumNext/Trilium) repository:
|
||||
|
||||
* `docs/Developer Guide` contains Markdown documentation that can be modified either externally (using a Markdown editor, or internally using Trilium).
|
||||
* `docs/Release Notes` is also stored in Markdown format and can be freely edited.
|
||||
* `docs/Script API` contains auto-generated files and thus must not be modified.
|
||||
* `docs/User Guide` contains also Markdown-only documentation but must generally not be edited externally.
|
||||
* The reason is that the `pnpm edit-docs:edit-docs` feature will not only import/export this documentation, but also generate the corresponding HTML documentation and meta structure in `src/public/app/doc_notes/en/User Guide`.
|
||||
* It's theoretically possible to edit the Markdown files externally and then run `docs:edit` and trigger a change in order to build the documentation, but that would not be a very productive workflow.
|
||||
|
||||
## Editing the documentation
|
||||
|
||||
There are two ways to modify documentation:
|
||||
|
||||
* Using a special mode of Trilium.
|
||||
* By manually editing the files.
|
||||
|
||||
### Using `docs:edit`
|
||||
### Using the `edit-docs` app
|
||||
|
||||
To edit the documentation using Trilium, set up a working development environment and run the following commands:
|
||||
|
||||
* On most operating systems, `npm run electron:switch` followed by `npm run docs:edit`
|
||||
* On NixOS, `npm run docs:edit-nix`.
|
||||
|
||||
> [!NOTE]
|
||||
> `npm run docs:edit` acts very similar to `npm run electron:start` in the sense that you cannot both be editing documentation and starting a server. Using both `npm run electron:start` and `docs:edit` is possible, since they are using the same Electron instance.
|
||||
To edit the documentation using Trilium, set up a working development environment via <a class="reference-link" href="Environment%20Setup.md">Environment Setup</a> and run the following command: `pnpm edit-docs:edit-docs`.
|
||||
|
||||
How it works:
|
||||
|
||||
@@ -50,24 +53,30 @@ Important aspects to consider:
|
||||
* The Trilium import/export mechanism is not perfect, so if you make some modifications to the documentation using `docs:edit`, at the next import/export/import cycle some whitespace might get thrown in. It's generally safe to commit the changes as-is.
|
||||
* Since we are importing Markdown, editing HTML and then exporting the HTML back to Markdown there might be some edge cases where the formatting is not properly preserved. Try to identify such cases and report them in order to get them fixed (this will benefit also the users).
|
||||
|
||||
## Location of the documentation
|
||||
## Automation
|
||||
|
||||
All documentation is stored in the [Notes](https://github.com/TriliumNext/Trilium) repository:
|
||||
The documentation is built via `apps/build-docs`:
|
||||
|
||||
* `docs/Developer Guide` contains Markdown documentation that can be modified either externally (using a Markdown editor, or internally using Trilium).
|
||||
* `docs/Release Notes` is also stored in Markdown format and can be freely edited.
|
||||
* `docs/Script API` contains auto-generated files and thus must not be modified.
|
||||
* `docs/User Guide` contains also Markdown-only documentation but must generally not be edited externally.
|
||||
* The reason is that the `docs:edit` feature will not only import/export this documentation, but also generate the corresponding HTML documentation and meta structure in `src/public/app/doc_notes/en/User Guide`.
|
||||
* It's theoretically possible to edit the Markdown files externally and then run `docs:edit` and trigger a change in order to build the documentation, but that would not be a very productive workflow.
|
||||
1. The output directory is cleared.
|
||||
2. The User Guide and the Developer Guide are built.
|
||||
1. The documentation from the repo is archived and imported into an in-memory instance.
|
||||
2. The documentation is exported using the shared theme.
|
||||
3. The API docs (internal and ETAPI) are statically rendered via Redocly.
|
||||
4. The script API is generated via `typedoc`
|
||||
|
||||
The `deploy-docs` workflow triggers the documentation build and uploads it to CloudFlare Pages.
|
||||
|
||||
## Updating the Script API
|
||||
|
||||
As mentioned previously, the Script API is not manually editable since it is auto-generated using TypeDoc.
|
||||
|
||||
To update the API documentation, simply run `npm run docs:build`. Compare the changes (if any) and commit them.
|
||||
To update the API documentation, simply run `pnpm docs:build`. Compare the changes (if any) and commit them.
|
||||
|
||||
Note that in order to simulate the environment a script would have, some fake source files (in the sense that they are only used for documentation) are being used as entrypoints for the documentation:
|
||||
Note that in order to simulate the environment a script would have, some fake source files (in the sense that they are only used for documentation) are being used as entrypoints for the documentation. Look for `backend_script_entrypoint` and `frontend_script_entrypoint` in `apps/build-docs/src`.
|
||||
|
||||
* For back-end scripts, the script is located in `src/services/backend_script_entrypoint.ts`.
|
||||
* For front-end scripts, the script is located in `src/public/app/services/frontend_script_entrypoint.ts`.
|
||||
## Building locally
|
||||
|
||||
In the Git root:
|
||||
|
||||
* Run `pnpm docs:build`. The built documentation will be available in `site` at Git root.
|
||||
* To also run a webserver to test it, run `pnpm docs:preview` (this will not build the documentation) and navigate to `localhost:9000`.
|
||||
@@ -13,6 +13,8 @@ https://triliumnext.github.io/Docs/Wiki/
|
||||
|
||||
There is a pattern of “?” buttons throughout the application which make use of the `data-help-page` attribute. Whenever these buttons are pressed, the user is redirected to the corresponding wiki page by prepending the wiki root URL to the `data-help-page` attribute.
|
||||
|
||||
### Deprecated `help-page` attribute
|
||||
|
||||
Since the current wiki has a different structure than the original, for example to link to [https://github.com/TriliumNext/Docs/blob/main/Wiki/tree-concepts.md](https://github.com/TriliumNext/Docs/blob/main/Wiki/tree-concepts.md) the `data-help-page` attribute must be set to `tree-concepts.md`.
|
||||
|
||||
For links to headings, simply add the heading after the `.md`: `tree-concepts.md#prefix`
|
||||
@@ -20,4 +22,12 @@ For links to headings, simply add the heading after the `.md`: `tree-concepts.md
|
||||
You can identify those by looking for:
|
||||
|
||||
* `.attr("data-help-page"`
|
||||
* `data-help-page="`
|
||||
* `data-help-page="`
|
||||
|
||||
### More modern `data-in-app-help` attribute
|
||||
|
||||
Instead of opening in a web browser, this opens the help directly in the application in a split view. This is handled via the `data-in-app-help` attribute, where the value is the note ID of the help page without the `_help_` prefix.
|
||||
|
||||
### React
|
||||
|
||||
Use the `HelpButton` component in the same fashion as the `data-in-app-help` attribute.
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 7.1 KiB |
@@ -1,12 +0,0 @@
|
||||
# Download latest nightly and install it
|
||||
On Ubuntu:
|
||||
|
||||
```
|
||||
#!/usr/bin/env bash
|
||||
|
||||
name=TriliumNotes-linux-x64-nightly.deb
|
||||
rm -f $name*
|
||||
wget https://github.com/TriliumNext/Trilium/releases/download/nightly/$name
|
||||
sudo apt-get install ./$name
|
||||
rm $name
|
||||
```
|
||||
@@ -1,41 +0,0 @@
|
||||
# bettersqlite binaries
|
||||
### The native node bindings
|
||||
|
||||
`better-sqlite3` has native Node bindings. With updates of `better-sqlite3`, but also of Electron and Node.js versions, these bindings need to be updated.
|
||||
|
||||
Note that Electron and Node.js versions need different versions of these bindings, since Electron usually packs a different version of Node.js.
|
||||
|
||||
During development, `npm install` tries to build or reuse prebuilt natives for the current Node.js version. This makes `npm run start-server` work out of the box. Trying to run `npm run start-electron` with these versions generally causes an error such as this:
|
||||
|
||||
```
|
||||
Uncaught Exception:
|
||||
Error: The module '/Users/elian/Projects/Notes/node_modules/better-sqlite3/build/Release/better_sqlite3.node'
|
||||
was compiled against a different Node.js version using
|
||||
NODE_MODULE_VERSION 108. This version of Node.js requires
|
||||
NODE_MODULE_VERSION 116. Please try re-compiling or re-installing
|
||||
the module (for instance, using `npm rebuild` or `npm install`).
|
||||
```
|
||||
|
||||
### How the natives are handled
|
||||
|
||||
Locally, this can be fixed by rebuilding the binaries, which is what `npm run switch-electron` does, which uses `electron-rebuild` under the hood.
|
||||
|
||||
When the deliveries are built (see <a class="reference-link" href="../../../Building/Build%20deliveries%20locally.md">Build deliveries locally</a>), it is not feasible to rebuild the dependencies since we are building for multiple platforms. Luckily, `better-sqlite3` provides these prebuilt binaries from us, available as artifacts on [their GitHub releases page](https://github.com/WiseLibs/better-sqlite3/releases/).
|
||||
|
||||
The build script manages the natives for `better-sqlite3` by keeping a copy of the `.node` file for every platform in `bin/better-sqlite3`.
|
||||
|
||||
Whenever the version of `better-sqlite3` changes, the `.node` files must also be renewed based on their releases page. To simplify this process, a script was created in `bin/better-sqlite3/update.sh`.
|
||||
|
||||
## How to update the natives
|
||||
|
||||
The update script needs to know the version of Electron or Node.js for which to download the prebuilt binaries.
|
||||
|
||||
If you get errors during download, check on the [releases page](https://github.com/WiseLibs/better-sqlite3/releases/) to ensure that this particular combination of Electron/Node actually exists for the given release.
|
||||
|
||||
To determine the `NODE_MODULE_VERSION` that is required, look for `This version of Node.js requires`
|
||||
`NODE_MODULE_VERSION` in the error when starting Trilium via:
|
||||
|
||||
* `npm run start-electron` (or run any Electron [delivery](../../../Building/Build%20deliveries%20locally.md)), case in which the `ELECTRON_VERSION` variable needs to be changed.
|
||||
* `npm run start-server` (or run the Linux server delivery), case in which the `NODE_VERSION` variable needs to be changed.
|
||||
|
||||
Check which files got changed after running the update script and for each platform that got changed, test it locally via <a class="reference-link" href="../../../Building/Build%20deliveries%20locally.md">Build deliveries locally</a> or via the CI.
|
||||
@@ -1,16 +0,0 @@
|
||||
# Server-side imports
|
||||
Trilium Notes allowed the use of Common.js module imports inside backend scripts, such as:
|
||||
|
||||
```
|
||||
const isBetween = require('dayjs/plugin/isBetween')
|
||||
api.dayjs.extend(isBetween)
|
||||
```
|
||||
|
||||
For TriliumNext, the backend has been switched to use ESM which has a slightly more complicated syntax. Instead of `require` we now have `import` but which is asynchronous so it will require an `await`:
|
||||
|
||||
```
|
||||
const isBetween = (await import("dayjs/plugin/isBetween")).default;
|
||||
api.dayjs.extend(isBetween);
|
||||
```
|
||||
|
||||
Note that `.default` is also usually needed to obtain the same behaviour as a CJS import. When in doubt, use `console.log` to see the output of the value returned by `await import`.
|
||||
@@ -1,33 +0,0 @@
|
||||
# Widgets
|
||||
To create a basic widget, simply create a code note with type “JS frontend”. Add the `#widget` label in order for it to be loaded at startup.
|
||||
|
||||
```
|
||||
const template = `<div id="my-widget"><button>Click Me!</button></div>`;
|
||||
|
||||
class MyWidget extends api.BasicWidget {
|
||||
get position() { return 1; }
|
||||
get parentWidget() { return "left-pane" }
|
||||
|
||||
doRender() {
|
||||
this.$widget = $(template);
|
||||
return this.$widget;
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = new MyWidget();
|
||||
```
|
||||
|
||||
`parentWidget()` can be given the following values:
|
||||
|
||||
* `left-pane` - This renders the widget on the left side of the screen where the note tree lives.
|
||||
* `center-pane` - This renders the widget in the center of the layout in the same location that notes and splits appear.
|
||||
* `note-detail-pane` - This renders the widget _with_ the note in the center pane. This means it can appear multiple times with splits.
|
||||
* `right-pane` - This renders the widget to the right of any opened notes.
|
||||
|
||||
* * *
|
||||
|
||||
Reference:
|
||||
|
||||
* [https://trilium.rocks/X7pxYpiu0lgU](https://trilium.rocks/X7pxYpiu0lgU)
|
||||
* [https://github.com/zadam/trilium/wiki/Widget-Basics](https://github.com/zadam/trilium/wiki/Widget-Basics)
|
||||
* [https://github.com/zadam/trilium/wiki/Frontend-Basics](https://github.com/zadam/trilium/wiki/Frontend-Basics)
|
||||
@@ -1,15 +0,0 @@
|
||||
# CSS
|
||||
In `doRender()`:
|
||||
|
||||
```
|
||||
this.cssBlock(`#my-widget {
|
||||
position: absolute;
|
||||
bottom: 40px;
|
||||
left: 60px;
|
||||
z-index: 1;
|
||||
}`)
|
||||
```
|
||||
|
||||
* * *
|
||||
|
||||
Reference: [https://trilium.rocks/X7pxYpiu0lgU](https://trilium.rocks/X7pxYpiu0lgU)
|
||||
@@ -1,32 +0,0 @@
|
||||
# Right pane widget
|
||||
* `doRender` must not be overridden, instead `doRenderBody()` has to be overridden.
|
||||
* `parentWidget()` must be set to `“rightPane”`.
|
||||
* `widgetTitle()` getter can optionally be overriden, otherwise the widget will be displayed as “Untitled widget”.
|
||||
|
||||
```
|
||||
const template = `<div>Hi</div>`;
|
||||
|
||||
class ToDoListWidget extends api.RightPanelWidget {
|
||||
|
||||
get widgetTitle() {
|
||||
return "Title goes here";
|
||||
}
|
||||
|
||||
get parentWidget() { return "right-pane" }
|
||||
|
||||
doRenderBody() {
|
||||
this.$body.empty().append($(template));
|
||||
}
|
||||
|
||||
async refreshWithNote(note) {
|
||||
this.toggleInt(false);
|
||||
this.triggerCommand("reEvaluateRightPaneVisibility");
|
||||
this.toggleInt(true);
|
||||
this.triggerCommand("reEvaluateRightPaneVisibility");
|
||||
}
|
||||
}
|
||||
|
||||
module.exports = new ToDoListWidget();
|
||||
```
|
||||
|
||||
The implementation is in `src/public/app/widgets/right_panel_widget.js`.
|
||||
@@ -1,21 +0,0 @@
|
||||
# Building the editor
|
||||
First, make sure <a class="reference-link" href="Environment%20setup.md">Environment setup</a> is set up.
|
||||
|
||||
## Trigger the build
|
||||
|
||||
```
|
||||
cd packages/ckeditor5-build-trilium
|
||||
yarn build
|
||||
```
|
||||
|
||||
This will trigger a change in the `build` directory.
|
||||
|
||||
## Copy the build artifact to the main repo
|
||||
|
||||
Go to `packages/ckeditor5-build-balloon-trilium/build` and copy `ckeditor.js` and `ckeditor.js.map` to `libraries/ckeditor` in the `Notes` repository.
|
||||
|
||||
An example shell command to copy it:
|
||||
|
||||
```
|
||||
cp build/ckeditor.* ~/Projects/TriliumNext/Notes/libraries/ckeditor/
|
||||
```
|
||||
@@ -1,26 +0,0 @@
|
||||
# Environment setup
|
||||
## Clone the repository
|
||||
|
||||
To set up the repository:
|
||||
|
||||
```
|
||||
git clone https://github.com/TriliumNext/trilium-ckeditor5.git
|
||||
```
|
||||
|
||||
## Install dependencies
|
||||
|
||||
First, install root dependencies:
|
||||
|
||||
```
|
||||
cd trilium-ckeditor5
|
||||
yarn install
|
||||
```
|
||||
|
||||
Secondly, install the Trilium build dependencies:
|
||||
|
||||
```
|
||||
cd packages/ckeditor5-build-trilium
|
||||
yarn install
|
||||
```
|
||||
|
||||
To trigger the build, see <a class="reference-link" href="Building%20the%20editor.md">Building the editor</a>.
|
||||
@@ -1,65 +0,0 @@
|
||||
# Updating to a newer version of CKEditor
|
||||
## Before updating
|
||||
|
||||
Make sure that all the plugins are compatible with this version: <a class="reference-link" href="Versions%20and%20external%20plugins.md">Versions and external plugins</a>. If not, they will need to be updated to the same version as the one you are updating, by altering their `package.json`.
|
||||
|
||||
If the plugin is external to the Trilium organisation, it needs to be forked first.
|
||||
|
||||
## Environment setup
|
||||
|
||||
The first step is to add the CKEditor source as a remote. This only needs to be done once.
|
||||
|
||||
```
|
||||
git remote add upstream ssh://git@github.com/ckeditor/ckeditor5.git
|
||||
git fetch upstream
|
||||
```
|
||||
|
||||
## Update steps
|
||||
|
||||
Due to how the repository is structured, updates to the CKEditor are a bit difficult.
|
||||
|
||||
1. `git fetch upstream`
|
||||
2. Pick a version and merge with it: `git merge -X theirs v99.2.0`
|
||||
3. When there are complicated conflicts, sometimes it's easier to take everything from the target version instead, for a given path: `git checkout v99.2.0 -- "packages/ckeditor5-list/**"`.
|
||||
4. Go in `packages/ckeditor5-build-trilium/package.json` and run `node sync-version.js` to update the `package.json` with the new versions. Review and commit the change.
|
||||
5. Follow again the dependency setup in <a class="reference-link" href="Environment%20setup.md">Environment setup</a>, as they have changed.
|
||||
6. [Run the build](Building%20the%20editor.md) and check that it works.
|
||||
|
||||
## Final steps
|
||||
|
||||
1. Start the TriliumNext server
|
||||
2. If updated to a newer version of CKEditor, check type `CKEDITOR_VERSION` in the browser/Electron console to ensure that the correct version is used.
|
||||
3. Do a basic sanity check as well.
|
||||
4. Commit and push the change on both sides (in the `trilium-ckeditor5` repo and in the `Notes` repo).
|
||||
|
||||
## Troubleshooting client side errors
|
||||
|
||||
These errors might show up when testing the Trilium app:
|
||||
|
||||
```
|
||||
ReferenceError: CKEditor is not defined
|
||||
```
|
||||
|
||||
Usually this is a side effect of another error, check the logs carefully to see if there is any other related error (perhaps a `CKEditorError`).
|
||||
|
||||
* * *
|
||||
|
||||
```
|
||||
Uncaught error: Message: CKEditorError: ckeditor-duplicated-modules
|
||||
```
|
||||
|
||||
Most likely cause is one of the external plugins is incompatible with this version.
|
||||
|
||||
For example, to disable the Math plugin, go to `packages/ckeditor5-build-trilium/src/config.ts` and modify:
|
||||
|
||||
```diff
|
||||
-import Math from '@triliumnext/ckeditor5-math/src/math';
|
||||
-import AutoformatMath from '@triliumnext/ckeditor5-math/src/autoformatmath';
|
||||
|
||||
export const COMMON_PLUGINS = [
|
||||
- Math,
|
||||
- AutoformatMath,
|
||||
]
|
||||
```
|
||||
|
||||
In this case, make sure to align the version of all the external plugins with the one you are updating to, usually by forking the external plugin and updating its versions.
|
||||
@@ -1,8 +0,0 @@
|
||||
# Versions and external plugins
|
||||
## External plugins
|
||||
|
||||
| | | |
|
||||
| --- | --- | --- |
|
||||
| trilium-ckeditor5 | 43.2.0 | |
|
||||
| `ckeditor5-math` | | See <a class="reference-link" href="../ckeditor5-math.md">ckeditor5-math</a>. |
|
||||
| | | |
|
||||
@@ -1,29 +0,0 @@
|
||||
# ckeditor5-math
|
||||
<figure class="image image-style-align-right"><img src="ckeditor5-math_image.png"><figcaption><code>ckeditor5-math</code> in action.</figcaption></figure>
|
||||
|
||||
A fork of [isaul32/ckeditor5-math](https://github.com/isaul32/ckeditor5-math), which is the CKEditor5 plugin which adds the math functionality. The fork was created to handle <a class="reference-link" href="#root/OeKBfN6JbMIq/MF99QFRe1gVy/orRZgNnWETTw/tXFiNo5IYd31/jMHQCKORhZge">#297: Insert Math appears to be broken</a>.
|
||||
|
||||
## Development environment
|
||||
|
||||
* Tested on Node.js 20.
|
||||
* The package manager is yarn 1 (v1.22.22 is known to be working fine for it at the time of writing).
|
||||
|
||||
Important commands:
|
||||
|
||||
* To check if the code has any formatting issues: `yarn lint`
|
||||
* To start a live preview: `yarn start`
|
||||
* To run the tests: `yarn test`
|
||||
* Note that this requires Chromium, on NixOS this can be achieved by running a `nix-shell -p chromium`, and running `CHROME_BIN=$(which chromium) yarn test` inside it.
|
||||
|
||||
## 📦 Packages
|
||||
|
||||
The built artifact of the plugin is released by the CI and available on the [GitHub NPM registry](https://github.com/TriliumNext/ckeditor5-math/pkgs/npm/ckeditor5-math).
|
||||
|
||||
Note that due to limitations on GitHub's registry, it is not possible to install this package without setting up a personal access token (even though the package itself is public). See <a class="reference-link" href="#root/ZlxZh8NH5frM/jUH2zJGXM67N">[missing note]</a> for more information.
|
||||
|
||||
## ⬆️ Integrating with <a class="reference-link" href="CKEditor">CKEditor</a>
|
||||
|
||||
1. Release a new version: <a class="reference-link" href="ckeditor5-math/Release%20management%20%26%20continuou.md">Release management & continuous integration</a>
|
||||
2. In `trilium-ckeditor5`, go to `packages/ckeditor5-build-trilium/package.json` in the CKEditor repository and change the dependency of `@triliumnext/ckeditor5-math` to the newly released version.
|
||||
3. Run `yarn install`.
|
||||
4. Proceed with <a class="reference-link" href="CKEditor/Building%20the%20editor.md">Building the editor</a> to integrate everything into TriliumNext and then commit the change.
|
||||
@@ -1,16 +0,0 @@
|
||||
# Release management & continuous integration
|
||||
To automate the release process, a GitHub workflow has been added which builds the package and releases it over to GitHub NPM registry.
|
||||
|
||||
The workflow publishes a release whenever a tag with the correct format is pushed.
|
||||
|
||||
The steps are as follows:
|
||||
|
||||
1. Ensure that the source code is clean and ready for a release.
|
||||
2. Go to `package.json` and bump the `version` field.
|
||||
3. Commit the changes.
|
||||
4. Tag the commit with `v1.2.3`, with the correct version number.
|
||||
5. Push the changes.
|
||||
|
||||
Then follow the CI and it should indicate success. Afterwards, check the [package](https://github.com/TriliumNext/ckeditor5-math/pkgs/npm/ckeditor5-math)section to ensure that the package is in the “Recent Versions” section.
|
||||
|
||||
If the changes could benefit upstream, consider opening a pull request with the changes there as well.
|
||||
@@ -1,21 +0,0 @@
|
||||
# Updating with upstream
|
||||
If there was a change in the upstream repository ([isaul32/ckeditor5-math](https://github.com/isaul32/ckeditor5-math)), it can be integrated as follows:
|
||||
|
||||
1. Add the upstream as remote (`git remote add upstream ssh://git@github.com/isaul32/ckeditor5-math.git`).
|
||||
2. Fetch the changes: `git fetch upstream`
|
||||
3. Merge with a tag: `git merge v43.1.2`
|
||||
4. Solve the conflict in `package.json` by:
|
||||
1. Taking the same version as the upcoming one and appending `-hotfix1`.
|
||||
2. Keeping the `@triliumnext/ckeditor5-math` name.
|
||||
5. Install dependencies: `yarn install`
|
||||
6. Check that the build works via `yarn prepublishOnly`.
|
||||
7. Commit the changes, push them.
|
||||
8. Release a version with <a class="reference-link" href="Release%20management%20%26%20continuou.md">Release management & continuous integration</a>.
|
||||
|
||||
## CI job not triggered after pushing all the upstream tags
|
||||
|
||||
If the CI job was not triggered, you might have accidentally pushed a lot of tags using `git push --tags`. Manually delete the tag and push it again:
|
||||
|
||||
```diff
|
||||
git push -d origin v43.1.2-hotfix1 && git push --tags
|
||||
```
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 9.7 KiB |
@@ -1,38 +0,0 @@
|
||||
# Running tests
|
||||
## First-time run
|
||||
|
||||
Before starting Playwright, it has to be installed locally via:
|
||||
|
||||
```
|
||||
npx playwright install
|
||||
```
|
||||
|
||||
## Starting the integration test server
|
||||
|
||||
There are two types of integration test servers:
|
||||
|
||||
* `npm run integration-mem-db` will run a server with dev mode disabled.
|
||||
* This is usually what the end user will see when accessing a server instance.
|
||||
* It will not test the Electron/desktop side of the application.
|
||||
* Changes to the public scripts will not take effect until running `npm run webpack`.
|
||||
* `npm run integration-mem-db-dev` will run a server with dev mode enabled.
|
||||
* This is usually what a dev sees when running `npm run start-server`.
|
||||
* The difference with the production one is that the assets are loaded directly from files and as such it does not require `npm run webpack` to see changes.
|
||||
|
||||
Either options will open up a server on [localhost:8082](http://localhost:8082) that can be accessed either manually via the browser or via Playwright.
|
||||
|
||||
When asked for a password, the password is `demo1234`.
|
||||
|
||||
## Starting the interactive test runner
|
||||
|
||||
After starting the integration test server, to run the Playwright UI, run in the terminal:
|
||||
|
||||
```
|
||||
npx playwright test --ui
|
||||
```
|
||||
|
||||
It is also possible to run the interactive code generator instead:
|
||||
|
||||
```
|
||||
npx playwright codegen
|
||||
```
|
||||
@@ -1,12 +0,0 @@
|
||||
# Setting up authentication
|
||||
There is a setup test that stores the authentication token so that it can be reused throughout all the tests.
|
||||
|
||||
If tests fail due to being stuck on login, then it must be run.
|
||||
|
||||
To run it manually press “all” near the “Status:” text on top-left of the window
|
||||
|
||||
<figure class="image"><img src="1_Setting up authentication_.png"></figure>
|
||||
|
||||
Then check “setup” and look for `auth.setup.ts` and press its corresponding Run button:
|
||||
|
||||
<figure class="image"><img src="Setting up authentication_.png"></figure>
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 15 KiB |
@@ -17,17 +17,14 @@ Note that some integration tests rely on an in-memory database in order to funct
|
||||
|
||||
### REST API testing for the server
|
||||
|
||||
Some original work was done by Zadam in `/test-etapi`, using `.http` files.
|
||||
|
||||
New effort using `vitest` and `supertest` to initialize the Express server and run assertions without having to make actual requests to the server.
|
||||
API tests are handled via `vitest` and `supertest` to initialize the Express server and run assertions without having to make actual requests to the server.
|
||||
|
||||
An important aspect is that we have access to the Express `app` which allows for interesting assertions such as checking the state of the server, registering debug middleware and so on.
|
||||
|
||||
One example is `src/share/routes.spec.ts`.
|
||||
One example is `src/share/routes.spec.ts`, or for the ETAPI in `apps/server/spec/etapi`.
|
||||
|
||||
These integration tests are run alongside unit tests.
|
||||
|
||||
## End-to-end testing
|
||||
|
||||
* This tests both the client and the server, by running the server and then using Playwright to query the state of the page.
|
||||
* These can be found in `/e2e`.
|
||||
See <a class="reference-link" href="Testing/End-to-end%20tests.md">e2e tests</a>.
|
||||
31
docs/Developer Guide/Developer Guide/Testing/End-to-end tests.md
vendored
Normal file
31
docs/Developer Guide/Developer Guide/Testing/End-to-end tests.md
vendored
Normal file
@@ -0,0 +1,31 @@
|
||||
# End-to-end tests
|
||||
* This tests both the client and the server, by running the server and then using Playwright to query the state of the page.
|
||||
* These can be found in `apps/server-e2e` and `apps/desktop/e2e`.
|
||||
|
||||
## First-time run
|
||||
|
||||
Before starting Playwright, it has to be installed locally via:
|
||||
|
||||
```
|
||||
pnpm playwright install
|
||||
```
|
||||
|
||||
## Starting the integration test server
|
||||
|
||||
Simply run `pnpm e2e` in one of the e2e projects.
|
||||
|
||||
The integration server doesn't have authentication enabled to avoid login issues.
|
||||
|
||||
## Starting the interactive test runner
|
||||
|
||||
After starting the integration test server, to run the Playwright UI, run in the terminal:
|
||||
|
||||
```
|
||||
pnpm playwright test --ui
|
||||
```
|
||||
|
||||
It is also possible to run the interactive code generator instead:
|
||||
|
||||
```
|
||||
pnpm playwright codegen
|
||||
```
|
||||
0
docs/Developer Guide/Developer Guide/Testing/Integration testing.md
vendored
Normal file
0
docs/Developer Guide/Developer Guide/Testing/Integration testing.md
vendored
Normal file
@@ -36,5 +36,5 @@ The solution is to remove `node_modules` and reinstall all dependencies:
|
||||
|
||||
```
|
||||
rm -r node_modules
|
||||
npm install
|
||||
pnpm install
|
||||
```
|
||||
Reference in New Issue
Block a user