Tools/Notes
1
0
Fork 0
mirror of https://github.com/TriliumNext/Notes.git synced 2025-07-27 10:02:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

feat(docs): document writing documentation

Browse Source
This commit is contained in:
Elian Doran 2025-04-13 13:06:47 +03:00
parent 78778305ff
commit c719db03ab
No known key found for this signature in database
5 changed files with 108 additions and 40 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
docs/Developer Guide/!!!meta.json
View File

@ -2018,10 +2018,10 @@
},
{
"isClone": false,
"noteId": "LjqM0VUL1CrU",
"noteId": "Sow7ThJozkzJ",
"notePath": [
"jdjRLhLV3TtI",
"LjqM0VUL1CrU"
"Sow7ThJozkzJ"
],
"title": "Documentation",
"notePosition": 90,
@ -2032,18 +2032,27 @@
"attributes": [],
"format": "markdown",
"dataFileName": "Documentation.md",
"attachments": [],
"attachments": [
{
"attachmentId": "2bUrJyt2yfsd",
"title": "image.png",
"role": "image",
"mime": "image/png",
"position": 10,
"dataFileName": "Documentation_image.png"
}
],
"dirFileName": "Documentation",
"children": [
{
"isClone": false,
"noteId": "HptkyArOlRI5",
"noteId": "LjqM0VUL1CrU",
"notePath": [
"jdjRLhLV3TtI",
"LjqM0VUL1CrU",
"HptkyArOlRI5"
"Sow7ThJozkzJ",
"LjqM0VUL1CrU"
],
"title": "User-facing documentation",
"title": "Documentation references in the application",
"notePosition": 10,
"prefix": null,
"isExpanded": false,
@ -2051,7 +2060,7 @@
"mime": "text/html",
"attributes": [],
"format": "markdown",
"dataFileName": "User-facing documentation.md",
"dataFileName": "Documentation references in th.md",
"attachments": []
}
]
@ -2064,7 +2073,7 @@
"dtKC3FmoWOrv"
],
"title": "Testing",
"notePosition": 100,
"notePosition": 110,
"prefix": null,
"isExpanded": false,
"type": "text",
@ -2183,7 +2192,7 @@
"dHfw0XZE515z"
],
"title": "Sub-projects",
"notePosition": 110,
"notePosition": 120,
"prefix": null,
"isExpanded": false,
"type": "text",
@ -2486,7 +2495,7 @@
"ibAPHul7Efvr"
],
"title": "Notes for old development",
"notePosition": 120,
"notePosition": 130,
"prefix": null,
"isExpanded": false,
"type": "text",
@ -2551,7 +2560,7 @@
"QRLbiDXNxoWN"
],
"title": "Troubleshooting",
"notePosition": 130,
"notePosition": 140,
"prefix": null,
"isExpanded": false,
"type": "text",
@ -2590,7 +2599,7 @@
"x6lgrdztQwVB"
],
"title": "Installation",
"notePosition": 140,
"notePosition": 150,
"prefix": null,
"isExpanded": false,
"type": "text",

76
docs/Developer Guide/Developer Guide/Documentation.md
View File

@ -1,23 +1,73 @@
# Documentation
## Hard-coded links
<figure class="image image-style-align-right"><img style="aspect-ratio:205/162;" src="Documentation_image.png" width="205" height="162"></figure>
Hard-coded links are present throughout the application, either in dialogs or in the source code as comments.
There are multiple types of documentation for Trilium:
You can identify these links by searching for:
* 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.
```
https://triliumnext.github.io/Docs/Wiki/
```
## Editing documentation
## Help buttons
There are two ways to modify documentation:
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.
* Using a special mode of Trilium.
* By manually editing the files.
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`.
### Using `docs:edit`
For links to headings, simply add the heading after the `.md`: `tree-concepts.md#prefix`
To edit the documentation using Trilium, set up a working development environment and run the following commands:
You can identify those by looking for:
* On most operating systems, `npm run electron:switch` followed by `npm run docs:edit`
* On NixOS, `npm run docs:edit-nix`.
* `.attr("data-help-page"`
* `data-help-page="`
> [!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.
How it works:
* At startup, the documentation from `docs/` is imported from Markdown into a in-memory session (the initialization of the database is already handled by the application).
* Each modification will trigger after 10s an export from the in-memory Trilium session back to Markdown, including the meta file.
### Manual editing
Apart from the User Guide, it's generally feasible to make small modifications directly using a Markdown editor or VS Code, for example.
When making manual modifications, avoid:
* Uploading pictures, since images are handled as Trilium attachments which are stored in the meta file.
* Changing the file or directory structure in any way, since that is also handled by the meta file. A missing file will most certainly cause a crash at start-up when attempting to edit the docs using Trilium.
### Reviewing & committing the changes
Since the documentation is tracked with Git, after making the manual or automatic modifications (wait at least 10s after making the modification) the changes will reflect in Git.
Make sure to analyze each modified file and report possible issues.
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
All documentation is stored in the [Notes](https://github.com/TriliumNext/Notes) 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 `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.
## 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.
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:
* 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`.

23
docs/Developer Guide/Developer Guide/Documentation/Documentation references in th.md Normal file
View File

@ -0,0 +1,23 @@
# Documentation references in the application
## Hard-coded links
Hard-coded links are present throughout the application, either in dialogs or in the source code as comments.
You can identify these links by searching for:
```
https://triliumnext.github.io/Docs/Wiki/
```
## Help buttons
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.
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`
You can identify those by looking for:
* `.attr("data-help-page"`
* `data-help-page="`

14
docs/Developer Guide/Developer Guide/Documentation/User-facing documentation.md
View File

@ -1,14 +0,0 @@
# User-facing documentation
The user-facing documentation is available on a dedicated repository inside the organization: [https://github.com/TriliumNext/Docs](https://github.com/TriliumNext/Docs) 
It is currently organized as a flat tree of MarkDown notes.
The documentation started as an import of the existing upstream documentation in [https://github.com/zadam/trilium/wiki](https://github.com/zadam/trilium/wiki).
The public documentation is available at [https://triliumnext.github.io/Docs/Wiki](https://triliumnext.github.io/Docs/Wiki).
The repository is here: [https://github.com/TriliumNext/Docs](https://github.com/TriliumNext/Docs) 
The documentation is stored as Markdown files and is meant to be imported into Trilium Notes and then exported back in, as per the README. However, it's also possible to modify the Markdown files manually and push the changes.
The documentation is deployed automatically to GitHub Pages on every push on the `main` branch.

BIN
docs/Developer Guide/Developer Guide/Documentation_image.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 7.1 KiB