docs(dev): integrate more of the old documentation

This commit is contained in:
Elian Doran
2025-11-03 22:48:14 +02:00
parent d9071f2d8e
commit 686c8936cb
21 changed files with 433 additions and 903 deletions

File diff suppressed because it is too large Load Diff

View File

@@ -2,7 +2,7 @@
The main workflow of the CI: The main workflow of the CI:
* Builds the Docker image and publishes in the GitHub Docker registry. * Builds the Docker image and publishes in the GitHub Docker registry.
* Builds using a portion of the [delivery script](../../Build%20deliveries%20locally.md) artifacts for the following platforms: * Builds using a portion of the [delivery script](../../Building/Build%20deliveries%20locally.md) artifacts for the following platforms:
* Windows `x86_64` as .zip file * Windows `x86_64` as .zip file
* Windows `x86_64` installer (using Squirrel) * Windows `x86_64` installer (using Squirrel)
* macOS `x86_64` and `aarch64`. * macOS `x86_64` and `aarch64`.

View File

@@ -21,7 +21,7 @@ These are stored in `images`:
## App icons ## App icons
<table><thead><tr><th>Name</th><th>Resolution</th><th>Description</th></tr></thead><tbody><tr><td><code>ios/apple-touch-icon.png</code></td><td>180x180</td><td>Used as <code>apple-touch-icon</code>, but only in <code>login.ejs</code> and <code>set_password.ejs</code> for some reason.</td></tr><tr><td><code>mac/icon.icns</code></td><td>512x512</td><td>Provided as <code>--icon</code> to <code>electron-packager</code> for <code>mac-arm64</code> and <code>mac-x64</code> <a href="../Old%20documentation/Build%20deliveries%20locally.md">builds</a>.</td></tr><tr><td><code>png/128x128.png</code></td><td>128x128</td><td>Used in <code>linux-x64</code> <a href="../Old%20documentation/Build%20deliveries%20locally.md">build</a>, to provide an <code>icon.png</code>.</td></tr><tr><td><code>png/256x256-dev.png</code></td><td>256x256</td><td>Used by the Electron window icon, if in dev mode.</td></tr><tr><td><code>png/256x256.png</code></td><td>Used by the Electron window icon, if not in dev mode.</td></tr><tr><td><code>win/icon.ico</code></td><td><ul><li>ICO 16x16</li><li>ICO 32x32</li><li>ICO 48x48</li><li>ICO 64x64</li><li>ICO 128x128</li><li>PNG 256x256</li></ul></td><td><ul><li>Used by the <code>win-x64</code> <a href="../Old%20documentation/Build%20deliveries%20locally.md">build</a>.</li><li>Used by Squirrel Windows installer for: setup icon, app icon, control panel icon</li><li>Used as the favicon.</li></ul></td></tr><tr><td><code>win/setup-banner.gif</code></td><td>640x480</td><td>Used by the Squirrel Windows installer during the installation process. Has only one frame.</td></tr></tbody></table> <table><thead><tr><th>Name</th><th>Resolution</th><th>Description</th></tr></thead><tbody><tr><td><code>ios/apple-touch-icon.png</code></td><td>180x180</td><td>Used as <code>apple-touch-icon</code>, but only in <code>login.ejs</code> and <code>set_password.ejs</code> for some reason.</td></tr><tr><td><code>mac/icon.icns</code></td><td>512x512</td><td>Provided as <code>--icon</code> to <code>electron-packager</code> for <code>mac-arm64</code> and <code>mac-x64</code> <a href="../Building/Build%20deliveries%20locally.md">builds</a>.</td></tr><tr><td><code>png/128x128.png</code></td><td>128x128</td><td>Used in <code>linux-x64</code> <a href="../Building/Build%20deliveries%20locally.md">build</a>, to provide an <code>icon.png</code>.</td></tr><tr><td><code>png/256x256-dev.png</code></td><td>256x256</td><td>Used by the Electron window icon, if in dev mode.</td></tr><tr><td><code>png/256x256.png</code></td><td>Used by the Electron window icon, if not in dev mode.</td></tr><tr><td><code>win/icon.ico</code></td><td><ul><li>ICO 16x16</li><li>ICO 32x32</li><li>ICO 48x48</li><li>ICO 64x64</li><li>ICO 128x128</li><li>PNG 256x256</li></ul></td><td><ul><li>Used by the <code>win-x64</code> <a href="../Building/Build%20deliveries%20locally.md">build</a>.</li><li>Used by Squirrel Windows installer for: setup icon, app icon, control panel icon</li><li>Used as the favicon.</li></ul></td></tr><tr><td><code>win/setup-banner.gif</code></td><td>640x480</td><td>Used by the Squirrel Windows installer during the installation process. Has only one frame.</td></tr></tbody></table>
## Additional locations where the branding is used ## Additional locations where the branding is used

View File

@@ -0,0 +1,34 @@
# Build deliveries locally
## Building the desktop
Go to `apps/desktop`, and:
* To generate the packages, run `pnpm electron-forge:make`.
* To only build the Flatpak, run `pnpm electron-forge:make-flatpak`.
* To only build without packaging it, run `pnpm electron-forge:package`.
## Building the server
Go to `apps/server` and run `pnpm package` to run the build script. The built artifacts will appear in `apps/server/dist`, whereas the packaged build will be available in `apps/server/out`.
## On NixOS
Under NixOS the following `nix-shell` is needed:
```
nix-shell -p jq
```
For Linux builds:
```
nix-shell -p jq fakeroot dpkg
```
To test the Linux builds, use `steam-run`:
```javascript
$ NIXPKGS_ALLOW_UNFREE=1 nix-shell -p steam-run
[nix-shell] cd dist/trilium-linux-x64
[nix-shell] steam-run ./trilium
```

View File

@@ -0,0 +1,17 @@
# Documentation
## 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.

View File

@@ -0,0 +1,33 @@
# Running a development build
First, follow the <a class="reference-link" href="../Environment%20Setup.md">Environment Setup</a>.
## Client
The client is not meant to be run by itself, despite being described as an app. See the documentation on the server instead.
## Server
* To run the server in development mode, run `server:start`. The dev port is `8080`.
* To run the server in production mode (with its own copy of the assets), run `server:start-prod`.
* To build for Docker, see <a class="reference-link" href="Docker.md">Docker</a>.
To run with a custom port, change the `TRILIUM_PORT` environment variable from the `package.json`.
## Desktop
* To run in development mode, use `pnpm desktop:start`.
* To run in production mode, use `pnpm desktop:start-prod`.
## Safe mode
Safe mode is off by default, to enable it temporarily on a Unix shell, prepend the environment variable setting:
```
pnpm cross-env TRILIUM_SAFE_MODE=1 pnpm server:start
```
## Running on NixOS
When doing development, the Electron binary retrieved from NPM is not going to be compatible with NixOS, resulting in errors when trying to run it. However Trilium handles it automatically when running `pnpm desktop:start`.
If there's no `electron` the system path it will attempt to use `nix-shell` to obtain it.

View File

@@ -1,32 +0,0 @@
# Build deliveries locally
In the project root:
| Platform | Architecture | Application | Build command |
| --- | --- | --- | --- |
| macOS | x86\_64 | Desktop / Electron app | `./bin/build-mac-x64.sh` |
| ARM 64 | Desktop / Electron app | `./bin/build-mac-arm64.sh` | |
| Linux | x86\_64 | Desktop / Electron app | `./bin/build-linux-x64.sh` |
| Server | `./bin/build-server.sh` | | |
| Windows | x86\_64 | Desktop / Electron app | `./bin/build-win-x64.sh` |
Under NixOS the following `nix-shell` is needed:
```
nix-shell -p jq
```
For Linux builds:
```
nix-shell -p jq fakeroot dpkg
```
The resulting build will be in the `dist` directory under the project root.
### Testing the Linux builds under NixOS
<table><thead><tr><th>Desktop client</th><th>Server</th></tr></thead><tbody><tr><td><pre><code class="language-text-plain">$ NIXPKGS_ALLOW_UNFREE=1 nix-shell -p steam-run
[nix-shell] cd dist/trilium-linux-x64
[nix-shell] steam-run ./trilium</code></pre></td><td><pre><code class="language-text-plain">$ NIXPKGS_ALLOW_UNFREE=1 nix-shell -p steam-run
[nix-shell] cd dist/trilium-linux-x64-server
[nix-shell] steam-run ./trilium.sh</code></pre></td></tr></tbody></table>

View File

@@ -1,2 +0,0 @@
# Build deliveries locally
This is a clone of a note. Go to its [primary location](../Build%20deliveries%20locally.md).

View File

@@ -1,34 +0,0 @@
# Documentation
Development notes are published on [triliumnext.github.io/Notes](https://triliumnext.github.io/Notes) by the CI using GitHub Pages.
The GitHub Pages deployment works by taking the files from the Notes repository, in the `docs` directory.
## How it works
There is a script that uses `wget` to download all the files from a share, that means:
1. You must have a local instance of Trilium Notes server.
2. You must have the documentation imported, up to date and shared.
Note that currently the documentation source file is not distributed (the note export), until a way is found to automate this process. Contact `eliandoran` should you require to obtain a copy of the documentation.
## Setting up `.env` file
Go to `bin/docs` and copy `.env.example` to `.env` and edit it:
1. Change the `SHARE_PROTOCOL` to either `http` or `https` depending on your setup.
2. Change `SHARE_HOST` to match the domain name or the URL to the host (without the protocol or any slashes).
Generally `ROOT_NOTE_ID` should not be changed since the note ID must match if the files were imported correctly.
## Triggering a build
Run:
```
./bin/docs/prepare.sh
```
This will attempt to download all the notes from the share URL and put them in `docs`, rewritten for GitHub Pages.
Commit the results and follow the normal development process to push them.

View File

@@ -1,2 +0,0 @@
# Releasing a version
This is a clone of a note. Go to its [primary location](../Releasing%20a%20version.md).

View File

@@ -1,2 +0,0 @@
# Running a development build
This is a clone of a note. Go to its [primary location](../Running%20a%20development%20build.md).

View File

@@ -1,116 +0,0 @@
# Adding a new client library
In the past some libraries have been copy-pasted (and adapted if needed) to the repository. However, new libraries must be obtained exclusively through npm.
The first step is to install the desired library. As an example we are going to install `i18next`:
```
npm i i18next
```
### Step 1. Understanding the structure of the import
After installing the dependency, it's important to know how it's structured. You can do this by looking at the directory structure of the newly imported dependency:
```
$ tree node_modules/i18next
node_modules/i18next
├── dist
│ ├── cjs
│ │ └── i18next.js
│ ├── esm
│ │ ├── i18next.bundled.js
│ │ ├── i18next.js
│ │ └── package.json
│ └── umd
│ ├── i18next.js
│ └── i18next.min.js
├── i18next.js
├── i18next.min.js
├── index.d.mts
├── index.d.ts
├── index.js
├── index.v4.d.ts
├── LICENSE
├── package.json
├── README.md
└── typescript
├── helpers.d.ts
├── options.d.ts
├── t.d.ts
└── t.v4.d.ts
```
Generally you should be looking for a `.min.js` file. Note that the `esm` and `cjs` variants generally don't work, we are looking for the classic, no module dependency.
### Step 2. Exposing the library from the server
The library must be delivered by the server and this is done via `src/routes/assets.ts`. In the `register` function, add a new entry near the bottom of the function:
```javascript
app.use(`/${assetPath}/node_modules/i18next/`, persistentCacheStatic(path.join(srcRoot, "..", 'node_modules/i18next/')));
```
### Step 3. Adding it to the library loader
The library loader is a client module which is in charge of downloading the library from the server and importing it. The loader is located in `src/public/app/services/library_loader.js`.
To add a new library, start by creating a constant for it, with the value pointing to the minified JS identified at the first step:
```javascript
const I18NEXT = {
js: [
"node_modules/i18next/i18next.min.js"
]
};
```
Then add it to the `export default` section:
```diff
export default {
requireCss,
requireLibrary,
CKEDITOR,
CODE_MIRROR,
ESLINT,
RELATION_MAP,
PRINT_THIS,
CALENDAR_WIDGET,
KATEX,
WHEEL_ZOOM,
FORCE_GRAPH,
MERMAID,
EXCALIDRAW,
- MARKJS
+ MARKJS,
+ I18NEXT
}
```
### Step 4. Using the library
To import the library, simply use the following mechanism:
```diff
import library_loader from "./library_loader.js";
await library_loader.requireLibrary(library_loader.I18NEXT);
```
Make sure to replace `I18NEXT` with the library that was created at the previous steps.
Note that because we are not using a module management mechanism such as ES Modules or Common.js modules, the `requireLibrary` method does not actually return anything. 
To benefit from the library, it must export on its own an object in `window`.
In the case of `i18next`, it sets `window.i18next` and that can be used directly:
```diff
i18next.init({});
```
### Step 5. Adding Electron support
For Electron, the `node_modules` are copied as a separate step by `bin/copy-dist.ts`.
Scroll all the way down to the `nodeModulesFolder` and append an entry for the newly added libraries.

View File

@@ -1,8 +0,0 @@
# Having a simpler packaging system
The current build scripts are a bit complicated and maintaining them is not easy.
[Electron Forge](https://www.electronforge.io/) seems more mature and has a boatload of features, including Flatpak, snaps, Windows installers & more.
Have a look also at the [Plugins](https://www.electronforge.io/config/plugins) section since there are quite a few interesting things there as well.
Afterwards consider running a new round of <a class="reference-link" href="#root/GAP7blNiSoX3/ftdNqJtBT1RD">Reducing binary size</a>, especially taking into consideration removing of the unnecessary locales.

View File

@@ -1,36 +0,0 @@
# Node.js, Electron and `better-sqlite3`
## Node.js, Electron and `better-sqlite3`
`better-sqlite3` requires a native module in order to work. In order to ease the installation process, prebuilt binaries are provided by the library developers.
Trilium Next started with version [8.4.0](https://github.com/WiseLibs/better-sqlite3/releases/tag/v8.4.0) for `better-sqlite3`
| | | | |
| --- | --- | --- | --- |
| `better-sqlite3` version | SQLite version | Node.js prebuilds | Electron.js prebuilds |
| 8.4.0 | <3.43.0 | v20 | ??? |
| 8.5.0 | v20 | v25 | |
| 8.5.1 | | v26 | |
| 8.5.2 | v20 (macOS + arm64) | | |
| 8.6.0 | 3.43.0 | | |
| 8.7.0 | 3.43.1 | | |
| 9.0.0 | 3.43.2 | | v27 |
| 9.1.0 | 3.44.0 | | |
| 9.1.1 | macOS + Alpine | | |
| 9.2.0 | 3.44.2 | | |
| 9.2.1 / 9.2.2 | | v28 | |
| 9.3.0 | 3.45.0 | | |
| 9.4.0 | 3.45.1 | | |
| 9.4.1 | Windows arm, arm64 | | |
| 9.4.2 | | <v29 | |
| 9.4.3 | | <v29 | |
| 9.4.4 | | v29 | |
| 9.4.5 | Better prebuilds | | |
| 9.5.0 | 3.45.2 | | |
| 9.6.0 | 3.45.3 | | v30 |
| 10.0.0 | v22 | | |
| 10.1.0 | 3.46.0 | | |
| 11.0.0 | \>21 | | |
| 11.1.0 (prerelease) | | | v31 |
| 11.1.1 | | | |
| 11.1.2 | | | |

View File

@@ -1,15 +0,0 @@
# Testing compatibility
| `better-sqlite3` version <br>[Change log](https://github.com/WiseLibs/better-sqlite3/releases) | SQLite version <br>[Change log](https://www.sqlite.org/changes.html) | Compatibility with upstream Trilium |
| --- | --- | --- |
| 8.4.0 | <3.43.0 | Compatible, same version. |
| 8.6.0 | 3.43.0 | |
| 8.7.0 | 3.43.1 | |
| 9.0.0 | 3.43.2 | |
| 9.1.0 + 9.1.1 | 3.44.0 | |
| 9.2.0 + 9.2.1 + 9.2.2 | 3.44.2 | |
| 9.3.0 | 3.45.0 | |
| 9.4.0, 9.4.1, 9.4.2, 9.4.3, 9.4.4, 9.4.5 | 3.45.1 | |
| 9.5.0 | 3.45.2 | |
| 9.6.0 / 10.0.0 | 3.45.3 | |
| 10.1.0 / 11.0.0 / 11.1.1 / 11.1.2 / 11.2.0 / 11.2.1 | 3.46.0 | |
| 11.3.0 | 3.46.1 | |

View File

@@ -20,7 +20,7 @@ the module (for instance, using `npm rebuild` or `npm install`).
Locally, this can be fixed by rebuilding the binaries, which is what `npm run switch-electron` does, which uses `electron-rebuild` under the hood. 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="../../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/).  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`. The build script manages the natives for `better-sqlite3` by keeping a copy of the `.node` file for every platform in `bin/better-sqlite3`.
@@ -35,7 +35,7 @@ If you get errors during download, check on the [releases page](https://github.c
To determine the `NODE_MODULE_VERSION` that is required, look for `This version of Node.js requires` 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: `NODE_MODULE_VERSION` in the error when starting Trilium via:
* `npm run start-electron` (or run any Electron [delivery](../../Build%20deliveries%20locally.md)), case in which the `ELECTRON_VERSION` variable needs to be changed. * `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. * `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="../../Build%20deliveries%20locally.md">Build deliveries locally</a> or via the CI. 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.

View File

@@ -17,6 +17,6 @@ If a version ends with `-beta`, it will automatically be marked as pre-release i
This will automatically generate a release in GitHub if everything goes according to plan. This will automatically generate a release in GitHub if everything goes according to plan.
Note that the Windows installer is not automatically uploaded yet, it has to be taken from the [main workflow of the CI from the `develop` branch](Building%20and%20deployment/CI/Main.md). Note that the Windows installer is not automatically uploaded yet, it has to be taken from the [main workflow of the CI from the `develop` branch](../Architecture/CI/Main.md).
Make sure to check test the artifacts of the release. Make sure to check test the artifacts of the release.

View File

@@ -1,89 +0,0 @@
# Running a development build
As always, install the dependencies for the first time (and re-run whenever there are errors about missing dependencies):
```
npm install
```
## Run server
Run with default settings:
```
npm run start-server
```
Run with custom port:
```
TRILIUM_PORT=8082 npm run start-server
```
## Run Electron
Rebuild `better-sqlite3` dependency:
```
npm run switch-electron
```
Then run Electron:
```
npm run start-electron
```
To run Electron using the same data directory as the production version:
```
npm run start-electron-no-dir
```
When done, switch back the `better-sqlite3` dependency:
```
npm run switch-server
```
## Quick switch
To start Electron without running `switch-electron` first:
```
npm run qstart-electron
```
Similarly, to start the server without running `switch-server` first:
```
npm run qstart-server
```
## Safe mode
Safe mode is off by default, to enable it temporarily on a Unix shell, prepend the environment variable setting:
```
TRILIUM_SAFE_MODE=1 npm run start-server
```
To have the same behaviour on Windows, we would need to alter `package.json`:
```diff
-"start-electron": "npm run prepare-dist && cross-env TRILIUM_DATA_DIR=./data TRILIUM_SYNC_SERVER_HOST=http://tsyncserver:4000 TRILIUM_ENV=dev electron ./dist/electron-main.js --inspect=5858 .",
+"start-electron": "npm run prepare-dist && cross-env TRILIUM_SAFE_MODE=1 TRILIUM_DATA_DIR=./data TRILIUM_SYNC_SERVER_HOST=http://tsyncserver:4000 TRILIUM_ENV=dev electron ./dist/electron-main.js --inspect=5858 .",
```
## Running on NixOS
When doing development, the Electron binary retrieved from NPM is not going to be compatible with NixOS, resulting in errors when trying to run it. To bypass this, there is a special command to run electron using `nix-shell`:
```
npm run start-electron-nix
```
Similarly to the original command, to use the same data directory as the production version:
```
npm run start-electron-no-dir-nix
```

View File

@@ -20,25 +20,9 @@ For example to run the server instance:
pnpm server:start pnpm server:start
``` ```
## Important tasks ## Running and building
Each application has a number of tasks. Here's a non-exhaustive list of the tasks that are useful during development. Each application has a number of tasks. Here's a non-exhaustive list of the tasks that are useful during development. See <a class="reference-link" href="Building">Building</a>.
To run any of the tasks, use `pnpm project:task`:
* `client`:
* The client is not meant to be run by itself, despite being described as an app. See the documentation on the server instead.
* `server`:
* To run the server in development mode, run `server:start`. The dev port is `8080`.
* To run the server in production mode (with its own copy of the assets), run `server:start-prod`.
* To build for Docker, see <a class="reference-link" href="Building/Docker.md">Docker</a>.
* `desktop`:
* To run the desktop in development mode with watch, run `desktop:start`.
* To run the desktop in production mode, run `desktop:start-prod`.
## Building packages
Generally, the building process of a project generates a `dist` folder containing everything needed for production.
## Managing dependencies across the mono-repo ## Managing dependencies across the mono-repo