mirror of
https://github.com/TriliumNext/Notes.git
synced 2025-07-27 18:12:29 +08:00
chore(docs): merge syntax highlight docs
This commit is contained in:
Elian Doran
parent
d1b308eced
commit
91daef863d
@ -402,29 +402,7 @@
|
||||
"attributes": [],
|
||||
"format": "markdown",
|
||||
"dataFileName": "v0.90.10-beta.md",
|
||||
"attachments": [],
|
||||
"dirFileName": "v0.90.10-beta",
|
||||
"children": [
|
||||
{
|
||||
"isClone": false,
|
||||
"noteId": "254wHQ6YdxUY",
|
||||
"notePath": [
|
||||
"hD3V4hiu2VW4",
|
||||
"sq5W9TQxRqMq",
|
||||
"254wHQ6YdxUY"
|
||||
],
|
||||
"title": "Syntax highlighting & word wrapping for code blocks",
|
||||
"notePosition": 10,
|
||||
"prefix": null,
|
||||
"isExpanded": false,
|
||||
"type": "text",
|
||||
"mime": "text/html",
|
||||
"attributes": [],
|
||||
"format": "markdown",
|
||||
"dataFileName": "Syntax highlighting & word wra.md",
|
||||
"attachments": []
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"isClone": false,
|
||||
|
||||
@ -1,52 +0,0 @@
|
||||
# Syntax highlighting & word wrapping for code blocks
|
||||
Finally, syntax highlighting was added as a feature for code blocks:
|
||||
|
||||
<figure class="image"><img src="api/images/qdaLLy7l56qD/1_Syntax highlighting & word.png"></figure>
|
||||
|
||||
## Context
|
||||
|
||||
In order to achieve the syntax highlight, the Highlight.js library is being used. Do note that support for syntax highlighting in code blocks is not a supported feature of the text editor we are using CKEditor), but rather a hack which makes use of the highlights API (used for highlighting search results for example). Nevertheless, we haven't noticed any major issues during the development of the feature, but feel free to report any issues you might have.
|
||||
|
||||
Most of the work to achieve the syntax highlight itself was already done by [antoniotejada](https://github.com/antoniotejada) in [https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget](https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget). On our side we added customization but also additional functionality.
|
||||
|
||||
## Migrating from existing syntax highlight plugins
|
||||
|
||||
If you are already using a syntax highlighting plugin such as the [Trilium-SyntaxHighlightWidget](https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget) we are basing off of, it is important to disable that plugin before upgrading in order for it not to conflict with our implementation.
|
||||
|
||||
Should you encounter any issues after the migration, try running Trilium in safe mode.
|
||||
|
||||
## New section in settings
|
||||
|
||||
In order to configure this new feature, a section has been added in Options → Appearance to control the syntax highlighting. There the color scheme can be chosen, from a builtin selection of themes from Highlight.js.
|
||||
|
||||
It is also now possible to disable the word wrapping for code blocks, which can make them easier to read for large amounts of code. Word wrapping has now been disabled by default.
|
||||
|
||||
It is also possible to disable the syntax highlighting by selecting “No syntax highlighting” in the “Color scheme” option.
|
||||
|
||||
<figure class="image"><img src="api/images/qwdqc6z3Ed7O/Syntax highlighting & word.png"></figure>
|
||||
|
||||
## Using the syntax highlight in auto mode
|
||||
|
||||
Provided the syntax highlighting is enabled in the settings, simply create a code block within a text note and it will try to automatically detect the language (using the Highlight.js library):
|
||||
|
||||
<figure class="image"><img src="api/images/dX20kVT0OyRC/2_Syntax highlighting & word.png"></figure>
|
||||
|
||||
## Adjusting the language manually
|
||||
|
||||
Should the automatic syntax highlight not work well enough, it is possible to manually adjust the language of the code block:
|
||||
|
||||
<figure class="image"><img src="api/images/gwD6zTFTQKKK/3_Syntax highlighting & word.png"></figure>
|
||||
|
||||
## Adding support for new languages
|
||||
|
||||
By going to settings → Code Notes → Available MIME types in the dropdown, it is possible to adjust the languages that are used for code blocks as well.
|
||||
|
||||
Note that not all languages that are present in this list (which is meant for code blocks, using CodeMirror as editor) are supported by our syntax highlight library. In this case you will simply see no syntax highlighting when you select the language.
|
||||
|
||||
If syntax highlighting is not supported for a given language, feel free to open an issue and we will look whether it is possible to integrate it.
|
||||
|
||||
## Automatic disable of syntax highlighting
|
||||
|
||||
Note that when editing a text note, syntax highlighting is automatically disabled if the code block is too big (somewhere around 500 lines). This value is currently not configured.
|
||||
|
||||
For read-only text notes, this limitation is not applied.
|
||||
@ -4982,13 +4982,6 @@
|
||||
"type": "text",
|
||||
"mime": "text/html",
|
||||
"attributes": [
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "QxEyIjRBizuC",
|
||||
"isInheritable": false,
|
||||
"position": 10
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
@ -4996,13 +4989,6 @@
|
||||
"isInheritable": false,
|
||||
"position": 20
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "4TIF1oA4VQRO",
|
||||
"isInheritable": false,
|
||||
"position": 30
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
@ -5023,6 +5009,20 @@
|
||||
"value": "bx bx-code",
|
||||
"isInheritable": false,
|
||||
"position": 50
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "CoFPLs3dRlXc",
|
||||
"isInheritable": false,
|
||||
"position": 60
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "4TIF1oA4VQRO",
|
||||
"isInheritable": false,
|
||||
"position": 70
|
||||
}
|
||||
],
|
||||
"format": "markdown",
|
||||
|
||||
@ -3,11 +3,11 @@
|
||||
|
||||
The code blocks feature allows entering pieces of code in text notes.
|
||||
|
||||
Note that this feature is meant for generally small snippets of code. For larger files such as an entire log, see the [Code blocks](Code%20blocks.md) note type instead.
|
||||
Note that this feature is meant for generally small snippets of code. For larger files such as an entire log, see the <a class="reference-link" href="../../Code.md">Code</a> note type instead.
|
||||
|
||||
## Inserting a code block
|
||||
|
||||
* Via the [Formatting toolbar](../Formatting%20toolbar.md), look for the  button.
|
||||
* Via the <a class="reference-link" href="../Formatting%20toolbar.md">Formatting toolbar</a>, look for the  button.
|
||||
* Pressing directly on the icon will insert a code block with the language that was selected most recently. If this is the first time a code block is inserted, the language will be “Auto-detected” by default.
|
||||
* Pressing the arrow next to the icon, which will show a popup with the available languages.
|
||||
* Type ` ``` ` (as in Markdown).
|
||||
@ -15,21 +15,42 @@ Note that this feature is meant for generally small snippets of code. For larger
|
||||
|
||||
## Syntax highlighting
|
||||
|
||||
Since TriliumNext v0.90.12, Trilium will try to offer syntax highlighting to the code block. Note that the syntax highlighting mechanism is slightly different than the one in [Code Notes](../../Code.md) notes as different technologies are involved.
|
||||
Since TriliumNext v0.90.12, Trilium will try to offer syntax highlighting to the code block. Note that the syntax highlighting mechanism is slightly different than the one in <a class="reference-link" href="../../Code.md">Code</a> notes as different technologies are involved.
|
||||
|
||||
When the language is set to _Auto-detected_, Trilium will try to identify the programming language (or similar) that corresponds to the given snippet of text and highlight it. If this is problematic, consider changing the language of the code block manually.
|
||||
Interaction:
|
||||
|
||||
When the language is set to _Plain text_, there will be no syntax highlighting.
|
||||
* When the language is set to _Auto-detected_ (by default), Trilium will try to identify the programming language (or similar) that corresponds to the given snippet of text and highlight it. If this is problematic, consider changing the language of the code block manually.
|
||||
* When the language is set to _Plain text_, there will be no syntax highlighting.
|
||||
|
||||
Note that when editing a text note, syntax highlighting is automatically disabled if the code block is too big (somewhere around 500 lines). This value is currently not configurable. For <a class="reference-link" href="../../../Basic%20Concepts%20and%20Features/Notes/Read-Only%20Notes.md">Read-Only Notes</a>, this limitation is not applied.
|
||||
|
||||
In order to configure this new feature, a section has been added in Options → Appearance to control the syntax highlighting. There the color scheme can be chosen, from a builtin selection of themes from Highlight.js.
|
||||
|
||||
* It is possible to disable the syntax highlighting for all the notes by selecting “No syntax highlighting” in the “Color scheme” option.
|
||||
* Word wrapping is disabled by default, but can be configured from the same section.
|
||||
|
||||
> [!NOTE]
|
||||
> **Context regarding syntax highlighting**
|
||||
>
|
||||
> In order to achieve the syntax highlight, the Highlight.js library is being used. Do note that support for syntax highlighting in code blocks is not a supported feature of the text editor we are using CKEditor), but rather a hack which makes use of the highlights API (used for highlighting search results for example). Nevertheless, we haven't noticed any major issues during the development of the feature, but feel free to report any issues you might have.
|
||||
>
|
||||
> Most of the work to achieve the syntax highlight itself was already done by [antoniotejada](https://github.com/antoniotejada) in [https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget](https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget). On our side we added customization but also additional functionality.
|
||||
|
||||
### Migrating from existing syntax highlight plugins
|
||||
|
||||
If you are already using a syntax highlighting plugin such as the [Trilium-SyntaxHighlightWidget](https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget) we are basing off of, it is important to disable that plugin before upgrading in order for it not to conflict with our implementation.
|
||||
|
||||
Should you encounter any issues after the migration, try running Trilium in safe mode.
|
||||
|
||||
## Changing the language of a code block
|
||||
|
||||
Simply click anywhere inside the code block and press again the code block button in the [Formatting toolbar](../Formatting%20toolbar.md):
|
||||
Simply click anywhere inside the code block and press again the code block button in the <a class="reference-link" href="../Formatting%20toolbar.md">Formatting toolbar</a>:
|
||||
|
||||
|
||||
## Adjusting the list of languages
|
||||
|
||||
The code blocks feature shares the list of languages with the [Code Notes](../../Code.md) note type.
|
||||
The code blocks feature shares the list of languages with the <a class="reference-link" href="../../Code.md">Code</a> note type.
|
||||
|
||||
The supported languages can be adjusted by going to [Options](../../../Basic%20Concepts%20and%20Features/UI%20Elements/Options.md), then _Code Notes_ and looking for the _Available MIME types in the dropdown_ section. Simply check any of the items to add them to the list, or uncheck them to remove them from the list.
|
||||
The supported languages can be adjusted by going to <a class="reference-link" href="../../../Basic%20Concepts%20and%20Features/UI%20Elements/Options.md">Options</a>, then _Code Notes_ and looking for the _Available MIME types in the dropdown_ section. Simply check any of the items to add them to the list, or uncheck them to remove them from the list.
|
||||
|
||||
Note that the list of languages is not immediately refreshed, you'd have to manually [refresh the application](../../../Troubleshooting/Refreshing%20the%20application.md).
|
||||
28
src/public/app/doc_notes/en/User Guide/!!!meta.json
generated
28
src/public/app/doc_notes/en/User Guide/!!!meta.json
generated
@ -4982,13 +4982,6 @@
|
||||
"type": "text",
|
||||
"mime": "text/html",
|
||||
"attributes": [
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "QxEyIjRBizuC",
|
||||
"isInheritable": false,
|
||||
"position": 10
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
@ -4996,13 +4989,6 @@
|
||||
"isInheritable": false,
|
||||
"position": 20
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "4TIF1oA4VQRO",
|
||||
"isInheritable": false,
|
||||
"position": 30
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
@ -5023,6 +5009,20 @@
|
||||
"value": "bx bx-code",
|
||||
"isInheritable": false,
|
||||
"position": 50
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "CoFPLs3dRlXc",
|
||||
"isInheritable": false,
|
||||
"position": 60
|
||||
},
|
||||
{
|
||||
"type": "relation",
|
||||
"name": "internalLink",
|
||||
"value": "4TIF1oA4VQRO",
|
||||
"isInheritable": false,
|
||||
"position": 70
|
||||
}
|
||||
],
|
||||
"format": "html",
|
||||
|
||||
@ -18,11 +18,12 @@
|
||||
</p>
|
||||
<p>The code blocks feature allows entering pieces of code in text notes.</p>
|
||||
<p>Note that this feature is meant for generally small snippets of code.
|
||||
For larger files such as an entire log, see the <a href="#root/_help_QxEyIjRBizuC">Code blocks</a> note
|
||||
For larger files such as an entire log, see the <a class="reference-link"
|
||||
href="#root/pOsGYCXsbNQG/KSZ04uQ2D1St/_help_6f9hih2hXXZk">Code</a> note
|
||||
type instead.</p>
|
||||
<h2>Inserting a code block</h2>
|
||||
<ul>
|
||||
<li>Via the <a href="#root/_help_nRhnJkTT8cPs">Formatting toolbar</a>,
|
||||
<li>Via the <a class="reference-link" href="#root/pOsGYCXsbNQG/KSZ04uQ2D1St/iPIMuisry3hd/_help_nRhnJkTT8cPs">Formatting toolbar</a>,
|
||||
look for the
|
||||
<img src="Code blocks_image.png">button.
|
||||
<ul>
|
||||
@ -43,25 +44,63 @@
|
||||
<h2>Syntax highlighting</h2>
|
||||
<p>Since TriliumNext v0.90.12, Trilium will try to offer syntax highlighting
|
||||
to the code block. Note that the syntax highlighting mechanism is slightly
|
||||
different than the one in <a href="#root/_help_6f9hih2hXXZk">Code Notes</a> notes
|
||||
different than the one in <a class="reference-link" href="#root/pOsGYCXsbNQG/KSZ04uQ2D1St/_help_6f9hih2hXXZk">Code</a> notes
|
||||
as different technologies are involved.</p>
|
||||
<p>When the language is set to <em>Auto-detected</em>, Trilium will try to
|
||||
identify the programming language (or similar) that corresponds to the
|
||||
given snippet of text and highlight it. If this is problematic, consider
|
||||
changing the language of the code block manually.</p>
|
||||
<p>When the language is set to <em>Plain text</em>, there will be no syntax
|
||||
highlighting.</p>
|
||||
<p>Interaction:</p>
|
||||
<ul>
|
||||
<li>When the language is set to <em>Auto-detected</em> (by default), Trilium
|
||||
will try to identify the programming language (or similar) that corresponds
|
||||
to the given snippet of text and highlight it. If this is problematic,
|
||||
consider changing the language of the code block manually.</li>
|
||||
<li>When the language is set to <em>Plain text</em>, there will be no syntax
|
||||
highlighting.</li>
|
||||
</ul>
|
||||
<p>Note that when editing a text note, syntax highlighting is automatically
|
||||
disabled if the code block is too big (somewhere around 500 lines). This
|
||||
value is currently not configurable. For <a class="reference-link"
|
||||
href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/BFs8mudNFgCS/_help_CoFPLs3dRlXc">Read-Only Notes</a>,
|
||||
this limitation is not applied.</p>
|
||||
<p>In order to configure this new feature, a section has been added in Options
|
||||
→ Appearance to control the syntax highlighting. There the color scheme
|
||||
can be chosen, from a builtin selection of themes from Highlight.js.</p>
|
||||
<ul>
|
||||
<li>It is possible to disable the syntax highlighting for all the notes by
|
||||
selecting “No syntax highlighting” in the “Color scheme” option.</li>
|
||||
<li>Word wrapping is disabled by default, but can be configured from the same
|
||||
section.</li>
|
||||
</ul>
|
||||
<aside class="admonition note">
|
||||
<p><strong>Context regarding syntax highlighting</strong>
|
||||
<br>
|
||||
<br>In order to achieve the syntax highlight, the Highlight.js library is
|
||||
being used. Do note that support for syntax highlighting in code blocks
|
||||
is not a supported feature of the text editor we are using CKEditor), but
|
||||
rather a hack which makes use of the highlights API (used for highlighting
|
||||
search results for example). Nevertheless, we haven't noticed any major
|
||||
issues during the development of the feature, but feel free to report any
|
||||
issues you might have.</p>
|
||||
<p>Most of the work to achieve the syntax highlight itself was already done
|
||||
by <a href="https://github.com/antoniotejada">antoniotejada</a> in <a href="https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget">https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget</a>.
|
||||
On our side we added customization but also additional functionality.</p>
|
||||
</aside>
|
||||
<h3>Migrating from existing syntax highlight plugins</h3>
|
||||
<p>If you are already using a syntax highlighting plugin such as the <a href="https://github.com/antoniotejada/Trilium-SyntaxHighlightWidget">Trilium-SyntaxHighlightWidget</a> we
|
||||
are basing off of, it is important to disable that plugin before upgrading
|
||||
in order for it not to conflict with our implementation.</p>
|
||||
<p>Should you encounter any issues after the migration, try running Trilium
|
||||
in safe mode.</p>
|
||||
<h2>Changing the language of a code block</h2>
|
||||
<p>Simply click anywhere inside the code block and press again the code block
|
||||
button in the <a href="#root/_help_nRhnJkTT8cPs">Formatting toolbar</a>:
|
||||
button in the <a class="reference-link" href="#root/pOsGYCXsbNQG/KSZ04uQ2D1St/iPIMuisry3hd/_help_nRhnJkTT8cPs">Formatting toolbar</a>:
|
||||
<br>
|
||||
<img src="2_Code blocks_image.png">
|
||||
</p>
|
||||
<h2>Adjusting the list of languages</h2>
|
||||
<p>The code blocks feature shares the list of languages with the
|
||||
<a
|
||||
href="#root/_help_6f9hih2hXXZk">Code Notes</a> note type.</p>
|
||||
<p>The supported languages can be adjusted by going to <a href="#root/_help_4TIF1oA4VQRO">Options</a>,
|
||||
class="reference-link" href="#root/pOsGYCXsbNQG/KSZ04uQ2D1St/_help_6f9hih2hXXZk">Code</a> note type.</p>
|
||||
<p>The supported languages can be adjusted by going to <a class="reference-link"
|
||||
href="#root/pOsGYCXsbNQG/gh7bpGYxajRS/Vc8PjrjAGuOp/_help_4TIF1oA4VQRO">Options</a>,
|
||||
then <em>Code Notes</em> and looking for the <em>Available MIME types in the dropdown</em> section.
|
||||
Simply check any of the items to add them to the list, or uncheck them
|
||||
to remove them from the list.</p>
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user