gaschz/trilium
1
0
Fork 0
mirror of https://github.com/zadam/trilium.git synced 2025-11-26 02:24:23 +01:00
Code Issues Actions 11 Packages Projects Releases Wiki Activity

docs(dev): refresh documentation on syntax highlighting

Browse Source
This commit is contained in:
Elian Doran 2025-11-24 18:39:51 +02:00
parent 84890fd5ad
commit 79a4da9db8
No known key found for this signature in database
5 changed files with 82 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.html generated vendored
View File

@ -152,6 +152,14 @@
<td>""</td> <td>""</td>
<td>CORS allowed headers</td> <td>CORS allowed headers</td>
</tr> </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> </tbody>
</table> </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_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_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_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> </ul>
<h3>Sync Variables</h3> <h3>Sync Variables</h3>
<ul> <ul>

9
apps/server/src/assets/doc_notes/en/User Guide/User Guide/Scripting/Frontend Basics/Custom Widgets/Right pane widget.html generated vendored
View File

@ -1,13 +1,12 @@
<ul> <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. to be overridden.
<ul> <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> </ul>
</li> </li>
<li data-list-item-id="e8b97337d5d8d708f5555b6f78fc1a993"><code>parentWidget()</code> must be set to <code>“rightPane”</code>.</li> <li><code>parentWidget()</code> must be set to <code>“rightPane”</code>.</li>
<li <li><code>widgetTitle()</code> getter can optionally be overriden, otherwise
data-list-item-id="eccb7323be12f3facd371512a19582705"><code>widgetTitle()</code> getter can optionally be overriden, otherwise
the widget will be displayed as “Untitled widget”.</li> 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;`; </ul><pre><code class="language-text-x-trilium-auto">const template = `&lt;div&gt;Hi&lt;/div&gt;`;

113
docs/Developer Guide/Developer Guide/Concepts/Syntax highlighting.md vendored
View File

@ -1,84 +1,93 @@
# Syntax highlighting # Syntax highlighting
## Defining the MIME type ## 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 ## 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:
### Custom language ```
"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.
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`. ### Modules integrated directly into Trilium
Make sure in the script that the language is registered: * 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.
``` Steps:
hljs.registerLanguage('terraform', hljsDefineTerraform);
```
Then in `mime_types.ts` make sure to set `highlightJsSource` to `libraries` to load it. 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:
``` ```
{ title: "Terraform (HCL)", mime: "text/x-hcl", highlightJs: "terraform", highlightJsSource: "libraries", codeMirrorSource: "libraries/codemirror/hcl.js" }, 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 ## 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:
start: [], ```
async () => (await import('@codemirror/lang-html')).html(),
```
2. Legacy modules (ported from CodeMirror 5):
echo: [] ```
"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,
```
### Integrating existing modules
* Add a comment at the beginning indicating the link to the original source code.
CodeMirror.defineMIME("application/x-bat", "batch"); * Some imports might require updating:
* Instead of
CodeMirror.modeInfo.push({ `import { StreamParser, StringStream } from "@codemirror/stream-parser";`, use  
`import { StreamParser, StringStream } from "@codemirror/language";`
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" }
```

2
docs/Developer Guide/Developer Guide/Documentation.md vendored
View File

@ -1,5 +1,5 @@
# Documentation # 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 _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. * The _Developer's Guide_ represents a set of Markdown documents that present the internals of Trilium, for developers.

3
docs/User Guide/User Guide/Advanced Usage/Configuration (config.ini or e.md vendored
View File

@ -49,7 +49,7 @@ Additionally, shorter aliases are available for common configurations (see Alter
| `TRILIUM_NETWORK_CORSALLOWORIGIN` | string | "" | CORS allowed origins | | `TRILIUM_NETWORK_CORSALLOWORIGIN` | string | "" | CORS allowed origins |
| `TRILIUM_NETWORK_CORSALLOWMETHODS` | string | "" | CORS allowed methods | | `TRILIUM_NETWORK_CORSALLOWMETHODS` | string | "" | CORS allowed methods |
| `TRILIUM_NETWORK_CORSALLOWHEADERS` | string | "" | CORS allowed headers | | `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 ### 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_METHODS` (alternative to `TRILIUM_NETWORK_CORSALLOWMETHODS`)
* `TRILIUM_NETWORK_CORS_ALLOW_HEADERS` (alternative to `TRILIUM_NETWORK_CORSALLOWHEADERS`) * `TRILIUM_NETWORK_CORS_ALLOW_HEADERS` (alternative to `TRILIUM_NETWORK_CORSALLOWHEADERS`)
* `TRILIUM_NETWORK_CORS_RESOURCE_POLICY` (alternative to `TRILIUM_NETWORK_CORSRESOURCEPOLICY`) * `TRILIUM_NETWORK_CORS_RESOURCE_POLICY` (alternative to `TRILIUM_NETWORK_CORSRESOURCEPOLICY`)
### Sync Variables ### Sync Variables
* `TRILIUM_SYNC_SERVER_HOST` (alternative to `TRILIUM_SYNC_SYNCSERVERHOST`) * `TRILIUM_SYNC_SERVER_HOST` (alternative to `TRILIUM_SYNC_SYNCSERVERHOST`)