Skip to content

Build your personal knowledge base with Trilium Notes

docs: repair dangling links and describe the headless docs sync

Elian Doranb0069685a347
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/UI Elements/New Layout.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/UI Elements/New Layout.html
index e3e7087881..deb5b0f046 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/UI Elements/New Layout.html
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Basic Concepts and Features/UI Elements/New Layout.html
@@ -90,7 +90,7 @@ width="735" height="143">
</ul>
</li>
<li><em>Edited Notes</em>, which appears for&nbsp;<a class="reference-link"
- href="#root/_help_l0tKav7yLHGF">[missing note]</a>&nbsp;is now shown underneath
+ href="#root/_help_l0tKav7yLHGF">Day Notes</a>&nbsp;is now shown underneath
the title.
<ul>
<li>Whether the section is collapsed or not depends on the choice in&nbsp;<a
@@ -218,12 +218,12 @@ width="735" height="143">
<p>Most importantly, v0.105.0 splits the sidebar into multiple tabs with
additional functionality:</p>
<ul>
- <li><a class="reference-link" href="#root/_help_2dcGDhp9WFKb">[missing note]</a>,
+ <li><a class="reference-link" href="#root/_help_2dcGDhp9WFKb">Outline tab</a>,
which gathers the table of contents and highlights lists.</li>
- <li><a class="reference-link" href="#root/_help_uNtgN0cUKEBc">[missing note]</a>,
+ <li><a class="reference-link" href="#root/_help_uNtgN0cUKEBc">Attributes tab</a>,
which provides a graphical method of editing labels, relations and (promoted)
attribute definitions.</li>
- <li>A dedicated&nbsp;<a class="reference-link" href="#root/_help_LrKznOtw9cQD">[missing note]</a>.</li>
+ <li>A dedicated&nbsp;<a class="reference-link" href="#root/_help_LrKznOtw9cQD">AI chat tab</a>.</li>
<li><a class="reference-link" href="#root/_help_KRlZFoIH0j6p">Connections tab</a>,
which groups together the note map, note paths, backlinks and similar notes.</li>
</ul>
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Note Types/Text/Formatting toolbar.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Note Types/Text/Formatting toolbar.html
index 53fb3c7d5b..30a81fa5ce 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Note Types/Text/Formatting toolbar.html
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Note Types/Text/Formatting toolbar.html
@@ -2,7 +2,7 @@
on your preference.</p>
<p>The type of formatting toolbar can be changed by going to&nbsp;<a class="reference-link"
href="#root/_help_4TIF1oA4VQRO">Options</a>&nbsp;and then looking for the&nbsp;<a
- class="reference-link" href="#root/_options/_optionsTextNotes">Text Notes</a>&nbsp;section.
+ class="reference-link" href="#root/_hidden/_options/_optionsTextNotes">Text Notes</a>&nbsp;section.
In it, look for the <em>Formatting toolbar</em> category.</p>
<h2>Floating</h2>
<p>The floating bar is a more minimalist option, in which the formatting
diff --git a/docs/Developer Guide/Developer Guide/Architecture/Database/Database structure/attributes.md b/docs/Developer Guide/Developer Guide/Architecture/Database/Database structure/attributes.md
index c52a939f90..2a34f46a9c 100644
--- a/docs/Developer Guide/Developer Guide/Architecture/Database/Database structure/attributes.md
+++ b/docs/Developer Guide/Developer Guide/Architecture/Database/Database structure/attributes.md
@@ -15,7 +15,7 @@
<td>Text</td>
<td>Non-null</td>
<td>&nbsp;</td>
- <td>Unique Id of the attribute (e.g. <code>qhC1vzU4nwSE</code>), can also have a special unique ID for&nbsp;<a class="reference-link" href="#root/r11Bh3uxFGRj">Special notes</a>&nbsp;(e.g. <code>_lbToday_liconClass</code>).</td>
+ <td>Unique Id of the attribute (e.g. <code>qhC1vzU4nwSE</code>), can also have a special unique ID for special notes (e.g. <code>_lbToday_liconClass</code>).</td>
</tr>
<tr>
<th><code>noteId</code></th>
diff --git a/docs/Developer Guide/Developer Guide/Concepts/Icons.md b/docs/Developer Guide/Developer Guide/Concepts/Icons.md
index 1c092bc8bd..07d075a13c 100644
--- a/docs/Developer Guide/Developer Guide/Concepts/Icons.md
+++ b/docs/Developer Guide/Developer Guide/Concepts/Icons.md
@@ -71,4 +71,4 @@ These are stored in `images`:
* In the client, more specifically in `src/public/app/widgets/buttons/global_menu.js`, where the SVG content of the icon is directly embedded to allow styling via CSS.
* In the <a class="reference-link" href="Demo%20document.md">Demo document</a>, as an attachment.
-* In the <a class="reference-link" href="#root/OeKBfN6JbMIq/MF99QFRe1gVy/xkj1bqW7zJwQ/t6mT72MfEzb2">CKEditor</a> build, look for `packages/ckeditor5-build-balloon-block/src/icons/trilium.svg`. Make sure not to have any `fill` overrides in the SVG as the wrong color will be used.
\ No newline at end of file
+* In the <a class="reference-link" href="../Dependencies/CKEditor.md">CKEditor</a> build, look for `packages/ckeditor5-build-balloon-block/src/icons/trilium.svg`. Make sure not to have any `fill` overrides in the SVG as the wrong color will be used.
\ No newline at end of file
diff --git a/docs/Developer Guide/Developer Guide/Concepts/Note Types/Adding a new note type/Note type checklist.md b/docs/Developer Guide/Developer Guide/Concepts/Note Types/Adding a new note type/Note type checklist.md
index 9a3739ca0c..e872359144 100644
--- a/docs/Developer Guide/Developer Guide/Concepts/Note Types/Adding a new note type/Note type checklist.md
+++ b/docs/Developer Guide/Developer Guide/Concepts/Note Types/Adding a new note type/Note type checklist.md
@@ -13,7 +13,7 @@ The note type widget must be created according to <a class="reference-link" hre
* Add to note type selector
* Add the note to server allowed note types
* Update demo document to include this new note type
-* Increase server sync version (see <a class="reference-link" href="#root/XPSyrTI07rbd/DrIXfwu9CVJP">Mindmap gets turned as file</a>).
+* Increase server sync version (otherwise an older instance turns notes of the new type into file notes on sync).
## Validation checklist
diff --git a/docs/Developer Guide/Developer Guide/Documentation.md b/docs/Developer Guide/Developer Guide/Documentation.md
index 9ca93656c0..dac8a44b97 100644
--- a/docs/Developer Guide/Developer Guide/Documentation.md
+++ b/docs/Developer Guide/Developer Guide/Documentation.md
@@ -13,9 +13,11 @@ All documentation is stored in the [Trilium](https://github.com/TriliumNext/Tril
* `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.
* The _Script API_ is auto-generated and is **not** committed to the repository. It is built into the gitignored `site/` directory and published to [docs.triliumnotes.org](https://docs.triliumnotes.org/); see [Updating the Script API](#updating-the-script-api) below.
-* `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.
+* `docs/User Guide` contains Markdown documentation as well, together with a `!!!meta.json` file that describes the note tree (note IDs, share aliases, icons, attachments).
+ * From it, `apps/server/src/assets/doc_notes/en/User Guide` (the HTML rendered by the in-app help) and `apps/standalone/src/assets/help_meta.json` are generated. These generated files must never be edited by hand.
+ * The Markdown can be edited by hand, as long as the generated files are refreshed afterwards by running `pnpm edit-docs:sync-docs` (see below).
+
+The mappings between note trees and directories are listed in `edit-docs-config.yaml` at the root of the repository.
## Editing the documentation
@@ -26,31 +28,32 @@ There are two ways to modify documentation:
### Using the `edit-docs` app
-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`.
+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:
* 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.
+* Each modification will trigger after 10s an export from the in-memory Trilium session back to Markdown, including the meta file, as well as the HTML and meta files used by the in-app help.
### 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.
+Small modifications can be made directly using a Markdown editor or VS Code, for example. For the User Guide, run `pnpm edit-docs:sync-docs` afterwards: it performs the same import and export as the `edit-docs` app, without opening a window, so that the Markdown is normalized the same way and the in-app help is regenerated.
-When making manual modifications, avoid:
+When making manual modifications, keep in mind:
-* 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.
+* Images are handled as Trilium attachments which are stored in the meta file, so a picture cannot simply be dropped in the directory.
+* The file or directory structure is described by the meta file. A file that is not described in the meta file will cause the import to fail, and a file that is described but missing from the disk as well.
+* The `writing-documentation` skill in `.claude/skills` provides a `docs.mjs` script that handles these cases (creating a page, registering an image, renaming, moving or deleting a page) and audits the documentation for broken links, missing images and inconsistent metadata.
### 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.
+Since the documentation is tracked with Git, after making the manual or automatic modifications (wait at least 10s after making the modification in the `edit-docs` app) 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.
+* The Trilium import/export mechanism is not perfect, so 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).
## Automation
diff --git a/docs/Release Notes/Release Notes/v0.91.1-beta.md b/docs/Release Notes/Release Notes/v0.91.1-beta.md
index 23364a531d..3eb307d761 100644
--- a/docs/Release Notes/Release Notes/v0.91.1-beta.md
+++ b/docs/Release Notes/Release Notes/v0.91.1-beta.md
@@ -19,7 +19,7 @@
* [Add label definition type for standalone time](https://github.com/TriliumNext/Notes/pull/653) by @mm21
* [Remove resizer from backend log text area](https://github.com/TriliumNext/Notes/pull/670) by @meichthys
* Use CodeMirror for backend log
-* Support for ELK layout in Mermaid diagrams (sponsored by @perfectra1n). See the relevant “ELK layout engine” in <a class="reference-link" href="#root/xKNWRXC24L5y/moBMU5tfa7Xx/Tshj61stDt8g/tPQgGfUs7ewD">Mermaid diagrams</a> for more information.
+* Support for ELK layout in Mermaid diagrams (sponsored by @perfectra1n). See the relevant “ELK layout engine” in <a class="reference-link" href="#root/s1aBHPd79XYj">Mermaid Diagrams</a> for more information.
* [Make exact matches rise higher up in search](https://github.com/TriliumNext/Notes/pull/678) by @perfectra1n
* [Change layout of promoted attributes](https://github.com/TriliumNext/Notes/pull/538)
* [Add full text search in autocomplete](https://github.com/TriliumNext/Notes/pull/659) by @SiriusXT
diff --git a/docs/User Guide/User Guide/Basic Concepts and Features/UI Elements/New Layout.md b/docs/User Guide/User Guide/Basic Concepts and Features/UI Elements/New Layout.md
index e5de7cea3c..45cd78a2cd 100644
--- a/docs/User Guide/User Guide/Basic Concepts and Features/UI Elements/New Layout.md
+++ b/docs/User Guide/User Guide/Basic Concepts and Features/UI Elements/New Layout.md
@@ -55,7 +55,7 @@ The following sections have been made collapsible:
* _Promoted Attributes_
* For full-height notes such as <a class="reference-link" href="../../Note%20Types/Canvas.md">Canvas</a>, the promoted attributes are collapsed by default to make room.
* The keyboard shortcut previously used to trigger the promoted attributes ribbon tab (which was no longer working) has been repurposed to toggle the promoted attributes instead.
-* _Edited Notes_, which appears for <a class="reference-link" href="../../Advanced%20Usage/Advanced%20Showcases/Day%20Notes.md">[missing note]</a> is now shown underneath the title.
+* _Edited Notes_, which appears for <a class="reference-link" href="../../Advanced%20Usage/Advanced%20Showcases/Day%20Notes.md">Day Notes</a> is now shown underneath the title.
* Whether the section is collapsed or not depends on the choice in <a class="reference-link" href="Options.md">Options</a> → Appearance.
* _Search Properties_, which appears for the full <a class="reference-link" href="../Navigation/Search.md">Search</a> and <a class="reference-link" href="../../Note%20Types/Saved%20Search.md">Saved Search</a>.
@@ -125,9 +125,9 @@ The sidebar (also known as the right pane) also received some important changes.
Most importantly, v0.105.0 splits the sidebar into multiple tabs with additional functionality:
-* <a class="reference-link" href="Right%20Sidebar/Outline%20tab.md">[missing note]</a>, which gathers the table of contents and highlights lists.
-* <a class="reference-link" href="Right%20Sidebar/Attributes%20tab.md">[missing note]</a>, which provides a graphical method of editing labels, relations and (promoted) attribute definitions.
-* A dedicated <a class="reference-link" href="Right%20Sidebar/AI%20chat%20tab.md">[missing note]</a>.
+* <a class="reference-link" href="Right%20Sidebar/Outline%20tab.md">Outline tab</a>, which gathers the table of contents and highlights lists.
+* <a class="reference-link" href="Right%20Sidebar/Attributes%20tab.md">Attributes tab</a>, which provides a graphical method of editing labels, relations and (promoted) attribute definitions.
+* A dedicated <a class="reference-link" href="Right%20Sidebar/AI%20chat%20tab.md">AI chat tab</a>.
* <a class="reference-link" href="Right%20Sidebar/Connections%20tab.md">Connections tab</a>, which groups together the note map, note paths, backlinks and similar notes.
The previous iteration of the sidebar would appear contextually, depending on whether there are any items to be displayed. This caused occasional content shifts when moving between two panes in a split view. In the new layout, the sidebar acts more like the <a class="reference-link" href="Note%20Tree.md">Note Tree</a> pane, remaining visible even if there is nothing to display.
diff --git a/docs/User Guide/User Guide/Note Types/Text/Formatting toolbar.md b/docs/User Guide/User Guide/Note Types/Text/Formatting toolbar.md
index 641f0bd99c..db316b8889 100644
--- a/docs/User Guide/User Guide/Note Types/Text/Formatting toolbar.md
+++ b/docs/User Guide/User Guide/Note Types/Text/Formatting toolbar.md
@@ -1,7 +1,7 @@
# Formatting toolbar
Trilium allows two different editing experiences for text notes, based on your preference.
-The type of formatting toolbar can be changed by going to <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Options.md">Options</a> and then looking for the <a class="reference-link" href="#root/_options/_optionsTextNotes">Text Notes</a> section. In it, look for the _Formatting toolbar_ category.
+The type of formatting toolbar can be changed by going to <a class="reference-link" href="../../Basic%20Concepts%20and%20Features/UI%20Elements/Options.md">Options</a> and then looking for the <a class="reference-link" href="#root/_hidden/_options/_optionsTextNotes">Text Notes</a> section. In it, look for the _Formatting toolbar_ category.
## Floating