From 79a4da9db81932d65949fe06e41ae42480f5f068 Mon Sep 17 00:00:00 2001
From: Elian Doran <contact@eliandoran.me>
Date: Mon, 24 Nov 2025 18:39:51 +0200
Subject: [PATCH] docs(dev): refresh documentation on syntax highlighting

---
 .../Configuration (config.ini or e.html       |   9 ++
 .../Custom Widgets/Right pane widget.html     |   9 +-
 .../Concepts/Syntax highlighting.md           | 123 ++++++++++--------
 .../Developer Guide/Documentation.md          |   2 +-
 .../Configuration (config.ini or e.md         |   3 +-
 5 files changed, 82 insertions(+), 64 deletions(-)

diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html
index 46523a9ce..eb13e92f2 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html	
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html	
@@ -152,6 +152,14 @@
       <td>""</td>
       <td>CORS allowed headers</td>
     </tr>
+    <tr>
+      <td><code>TRILIUM_NETWORK_CORSRESOURCEPOLICY</code>
+      </td>
+      <td>string</td>
+      <td>same-origin</td>
+      <td>CORS Resource Policy allows same-origin/same-site/cross-origin as values,
+        will error if not</td>
+    </tr>
   </tbody>
 </table>
 
@@ -296,6 +304,7 @@
   <li><code>TRILIUM_NETWORK_CORS_ALLOW_ORIGIN</code> (alternative to <code>TRILIUM_NETWORK_CORSALLOWORIGIN</code>)</li>
   <li><code>TRILIUM_NETWORK_CORS_ALLOW_METHODS</code> (alternative to <code>TRILIUM_NETWORK_CORSALLOWMETHODS</code>)</li>
   <li><code>TRILIUM_NETWORK_CORS_ALLOW_HEADERS</code> (alternative to <code>TRILIUM_NETWORK_CORSALLOWHEADERS</code>)</li>
+  <li><code>TRILIUM_NETWORK_CORS_RESOURCE_POLICY</code> (alternative to <code>TRILIUM_NETWORK_CORSRESOURCEPOLICY</code>)</li>
 </ul>
 <h3>Sync Variables</h3>
 <ul>
diff --git a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets/Right pane widget.html b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets/Right pane widget.html
index e4706e317..8a9f06df3 100644
--- a/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets/Right pane widget.html	
+++ b/apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets/Right pane widget.html	
@@ -1,13 +1,12 @@
 <ul>
-  <li data-list-item-id="ea7daf7caa74a0f97f6f17625eacc6125"><code>doRender</code> must not be overridden, instead <code>doRenderBody()</code> has
+  <li><code>doRender</code> must not be overridden, instead <code>doRenderBody()</code> has
     to be overridden.
     <ul>
-      <li data-list-item-id="ef0f078ef265c54da5ff012f12cf7adee"><code>doRenderBody</code> can optionally be <code>async</code>.</li>
+      <li><code>doRenderBody</code> can optionally be <code>async</code>.</li>
     </ul>
   </li>
-  <li data-list-item-id="e8b97337d5d8d708f5555b6f78fc1a993"><code>parentWidget()</code> must be set to <code>“rightPane”</code>.</li>
-  <li
-  data-list-item-id="eccb7323be12f3facd371512a19582705"><code>widgetTitle()</code> getter can optionally be overriden, otherwise
+  <li><code>parentWidget()</code> must be set to <code>“rightPane”</code>.</li>
+  <li><code>widgetTitle()</code> getter can optionally be overriden, otherwise
     the widget will be displayed as “Untitled widget”.</li>
 </ul><pre><code class="language-text-x-trilium-auto">const template = `&lt;div&gt;Hi&lt;/div&gt;`;
 
diff --git a/docs/Developer Guide/Developer Guide/Concepts/Syntax highlighting.md b/docs/Developer Guide/Developer Guide/Concepts/Syntax highlighting.md
index f848660bd..521114551 100644
--- a/docs/Developer Guide/Developer Guide/Concepts/Syntax highlighting.md	
+++ b/docs/Developer Guide/Developer Guide/Concepts/Syntax highlighting.md	
@@ -1,84 +1,93 @@
 # Syntax highlighting
 ## Defining the MIME type
 
-The first step to supporting a new language for either code blocks or code notes is to define the MIME type. Go to `mime_types.ts` and add a corresponding entry:
+The first step to supporting a new language for either code blocks or code notes is to define the MIME type. Go to `mime_type.ts` in `packages/commons` and add a corresponding entry:
 
 ```
-{ title: "Batch file (DOS)", mime: "application/x-bat" }
+{ title: "ABAP (SAP)", mime: "text/x-abap", mdLanguageCode: "abap" }
 ```
 
+Where `mdLanguageCode` is a Markdown-friendly name of the language.
+
 ## Syntax highlighting for Highlight.js
 
-### Built-in languages
+The Highlight.js instance in Trilium identifies the code to highlight by the mime type mappings defined in `syntax_highlighting.ts` in `packages/highlightjs`.
 
-Highlight.js supports a lot of languages out of the box, for some of them we just need to enable them by specifying one of the language aliases in the `highlightJs` field in the `mime_types` definition:
+There are three possible cases, all involving modifying the `byMimeType` record:
+
+### Highlight.js built-in languages:
+
+Simply add a corresponding entry:
 
 ```
-{ title: "Batch file (DOS)", mime: "application/x-bat", highlightJs: "dos" }
+"application/dart": () => import("highlight.js/lib/languages/dart"),
 ```
 
-For the full list of supported languages, see [Supported Languages — highlight.js 11.9.0 documentation](https://highlightjs.readthedocs.io/en/latest/supported-languages.html). Look for the “Package” column to see if another library needs to be installed to support it.
+### External modules from NPM
 
-Note that we are using the CDN build which may or may not have all the languages listed as predefined in the “Supported languages” list. To view the real list of supported files, see the `node_modules/@highlightjs/cdn-assets/languages` directory.
+1.  Install the module as a dependency in `packages/highlight.js`
+2.  Import:
+    
+    ```
+    "application/x-cypher-query": () => import("highlightjs-cypher")
+    ```
+3.  Do this if the npm module is relatively new and it has TypeScript mappings, if not see the last option.
 
-### Custom language
+### Modules integrated directly into Trilium
 
-When the source code for a language is available, one way is to simply copy it to `libraries/highlightjs/{id}.js` where `id` matches the name for `highlightJs`.
+*   Allows making small modifications if needed (especially if the module is old).
+*   Works well for modules missing type definitions, since types are added directly in code.
 
-Make sure in the script that the language is registered:
+Steps:
 
-```
-hljs.registerLanguage('terraform', hljsDefineTerraform);
-```
-
-Then in `mime_types.ts` make sure to set `highlightJsSource` to `libraries` to load it.
-
-```
-{ title: "Terraform (HCL)", mime: "text/x-hcl", highlightJs: "terraform", highlightJsSource: "libraries", codeMirrorSource: "libraries/codemirror/hcl.js" },
-```
+1.  Copy the syntax highlighting file ([example](https://github.com/highlightjs/highlightjs-sap-abap/blob/main/src/abap.js)) into `packages/highlightjs/src/languages/[code].ts`.
+2.  Add a link in a comment at the top of the file linking to the original source code.
+3.  Replace `module.exports =` by `export default`.
+4.  Add types to the method:
+    
+    ```
+    import { HLJSApi, Language } from "highlight.js";
+    
+    export default function (hljs: HLJSApi): Language {
+    	// [...]
+    }
+    ```
+5.  Remove any module loading mechanism or shims outside the main highlight function.
+6.  Modify `syntax_highlighting.js` to support the new language:
+    
+    ```
+    "text/x-abap": () => import("./languages/abap.js"),
+    ```
 
 ## Syntax highlighting for CodeMirror
 
-### Custom language
+> [!NOTE]
+> Newer versions of Trilium use CodeMirror 6, so the plugin must be compatible with this version.
 
-Generally new languages are not added in the base installation and need to be separately registered. For CodeMirror 5 it seems that (at least for simple languages), the modes are distributed as _simple modes_ and can generally be copy-pasted in `libraries/codemirror`. An example would be:
+### Adding the MIME type mapping
 
-```
-(() => {
+Similar to Highlight.js, the mappings for each MIME type are handled in `syntax_highlighting.ts` in `packages/codemirror`, by modifying the `byMimeType` record.
 
-    CodeMirror.defineSimpleMode("batch", {
+1.  Official modules:
+    
+    ```
+    async () => (await import('@codemirror/lang-html')).html(),
+    ```
+2.  Legacy modules (ported from CodeMirror 5):
+    
+    ```
+    "text/turtle": async () => (await import('@codemirror/legacy-modes/mode/turtle')).turtle, 
+    ```
+3.  Modules integrated into Trilium:
+    
+    ```
+    "application/x-bat": async () => (await import("./languages/batch.js")).batch,
+    ```
 
-        start: [],
+### Integrating existing modules
 
-        echo: []
-
-    });
-
-
-
-    CodeMirror.defineMIME("application/x-bat", "batch");
-
-    CodeMirror.modeInfo.push({
-
-        ext: [ "bat", "cmd" ],
-
-        mime: "application/x-bat",
-
-        mode: "batch",
-
-        name: "Batch file"
-
-    });
-
-})();
-
-
-```
-
-Note that changing `modeInfo` is crucial, otherwise syntax highlighting will not work. The `mime` field is mandatory, even if `mimes` is used instead.
-
-Afterwards, register it in `mime_types.ts`, specifying `codeMirrorSource` to point to the newly created file:
-
-```
-{ title: "Batch file (DOS)", mime: "application/x-bat", highlightJs: "dos", codeMirrorSource: "libraries/codemirror/batch.js" }
-```
\ No newline at end of file
+*   Add a comment at the beginning indicating the link to the original source code.
+*   Some imports might require updating:
+    *   Instead of  
+        `import { StreamParser, StringStream } from "@codemirror/stream-parser";`, use    
+        `import { StreamParser, StringStream } from "@codemirror/language";`
\ No newline at end of file
diff --git a/docs/Developer Guide/Developer Guide/Documentation.md b/docs/Developer Guide/Developer Guide/Documentation.md
index f891e39c9..401b7897b 100644
--- a/docs/Developer Guide/Developer Guide/Documentation.md	
+++ b/docs/Developer Guide/Developer Guide/Documentation.md	
@@ -1,5 +1,5 @@
 # Documentation
-There are multiple types of documentation for Trilium:<img class="image-style-align-right" src="api/images/gKWerx46R13O/Documentation_image.png" width="205" height="162">
+There are multiple types of documentation for Trilium:<img class="image-style-align-right" src="api/images/X0cCo0YF7qZj/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.
diff --git a/docs/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.md b/docs/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.md
index 9c27eef14..b1795ccff 100644
--- a/docs/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.md	
+++ b/docs/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.md	
@@ -49,7 +49,7 @@ Additionally, shorter aliases are available for common configurations (see Alter
 | `TRILIUM_NETWORK_CORSALLOWORIGIN` | string | ""  | CORS allowed origins |
 | `TRILIUM_NETWORK_CORSALLOWMETHODS` | string | ""  | CORS allowed methods |
 | `TRILIUM_NETWORK_CORSALLOWHEADERS` | string | ""  | CORS allowed headers |
-| `TRILIUM_NETWORK_CORSRESOURCEPOLICY` | string | same-origin | CORS Resource Policy allows same-origin/same-site/cross-origin as values, will error if not
+| `TRILIUM_NETWORK_CORSRESOURCEPOLICY` | string | same-origin | CORS Resource Policy allows same-origin/same-site/cross-origin as values, will error if not |
 
 ### Session Section
 
@@ -92,6 +92,7 @@ The following alternative environment variable names are also supported and work
 *   `TRILIUM_NETWORK_CORS_ALLOW_METHODS` (alternative to `TRILIUM_NETWORK_CORSALLOWMETHODS`)
 *   `TRILIUM_NETWORK_CORS_ALLOW_HEADERS` (alternative to `TRILIUM_NETWORK_CORSALLOWHEADERS`)
 *   `TRILIUM_NETWORK_CORS_RESOURCE_POLICY` (alternative to `TRILIUM_NETWORK_CORSRESOURCEPOLICY`)
+
 ### Sync Variables
 
 *   `TRILIUM_SYNC_SERVER_HOST` (alternative to `TRILIUM_SYNC_SYNCSERVERHOST`)