docs(user): mention structure difference

This commit is contained in:
Elian Doran
2025-11-04 23:13:34 +02:00
parent 3359ff5470
commit c2ce36d963
6 changed files with 33 additions and 16 deletions

File diff suppressed because one or more lines are too long

View File

@@ -24,23 +24,34 @@
<p>Apart from normal&nbsp;<a class="reference-link" href="#root/_help_R9pX4DGra2Vt">Sharing</a>, <p>Apart from normal&nbsp;<a class="reference-link" href="#root/_help_R9pX4DGra2Vt">Sharing</a>,
exporting to static HTML files comes with a few subtle differences:</p> exporting to static HTML files comes with a few subtle differences:</p>
<ul> <ul>
<li>The URL structure is different. Where in normal sharing it's something <li data-list-item-id="e757e614020a02864a52b3b8f9f2b792f">The URL structure is different. Where in normal sharing it's something
along the way of <code>example.com/share/noteid</code>, the notes follow along the way of <code>example.com/share/noteid</code>, the notes follow
an hierarchical structure, such as <code>docs.triliumnotes.org/user-guide/concepts/navigation/tree-concepts</code>.</li> an hierarchical structure, such as <code>docs.triliumnotes.org/user-guide/concepts/navigation/tree-concepts</code>.</li>
<li>The <code>favicon.ico</code> is not handled automatically, it needs to be <li
data-list-item-id="e04429f1cf40760df3c0cd932d1107bfd">The <code>favicon.ico</code> is not handled automatically, it needs to be
manually added on the server after the export is generated.</li> manually added on the server after the export is generated.</li>
<li>The “Last updated” for notes is not available.</li> <li data-list-item-id="e5d86e8060c41292df46d0adcfffd5113">The “Last updated” for notes is not available.</li>
<li>The search functionality works slightly different since the normal one <li data-list-item-id="eb09fc171d1adcf6923bef3aaebb316d0">The search functionality works slightly different since the normal one
requires an active API to work. In the static export, search still works requires an active API to work. In the static export, search still works
but uses a different mechanism so results might be different.</li> but uses a different mechanism so results might be different.</li>
</ul> </ul>
<h2>Differences from normal .zip export</h2> <h2>Differences from normal .zip export</h2>
<ul> <ul>
<li>The name of the files/URLs will prefer <code>shareAlias</code> to allow <li data-list-item-id="e105d2557437171cb7ce15f84fe7bc405">The name of the files/URLs will prefer <code>shareAlias</code> to allow
for clean URLs.</li> for clean URLs.</li>
<li>The export requires a functional web server as the pages will not render <li data-list-item-id="ed984cadd9496205a76341b206776d5c7">The export requires a functional web server as the pages will not render
properly if accessed locally via a web browser due to the use of module properly if accessed locally via a web browser due to the use of module
scripts.</li> scripts.</li>
<li data-list-item-id="ed0a279aec254358dcff1769e08fc548b">The directory structure is also slightly different:
<ul>
<li data-list-item-id="ed8b6890f4850eaa869269cb03b812924">A normal HTML export results in an index file and a single directory.</li>
<li
data-list-item-id="e94e121f725d76c6bb10596f72bb44fd3">Instead, for static exporting the top-root level becomes the index file
and the child directories are on the root instead.</li>
<li data-list-item-id="eee85ca77bfc3f3f78042272fbe072610">This makes it possible to easily publish to a website, without forcing
everything but the root note to be in a sub-directory.</li>
</ul>
</li>
</ul> </ul>
<h2>Testing locally</h2> <h2>Testing locally</h2>
<p>As mentioned previously, the exported static pages require a website to <p>As mentioned previously, the exported static pages require a website to
@@ -49,9 +60,9 @@
can be installed via:</p><pre><code class="language-text-x-trilium-auto">npm i -g http-server</code></pre> can be installed via:</p><pre><code class="language-text-x-trilium-auto">npm i -g http-server</code></pre>
<p>Once installed simply:</p> <p>Once installed simply:</p>
<ol> <ol>
<li>Extract the exported .zip file.</li> <li data-list-item-id="ef3a455a98e83613ee8cb2fdd55327951">Extract the exported .zip file.</li>
<li>Inside the extracted directory, run <code>http-server</code>.</li> <li data-list-item-id="e0a88b24efdc8f247105086ada68cf617">Inside the extracted directory, run <code>http-server</code>.</li>
<li>Access the indicated address (e.g. <a href="http://localhost:8080">http://localhost:8080</a>).</li> <li data-list-item-id="e533233e9ad5f4a52cddb6e141f26b444">Access the indicated address (e.g. <a href="http://localhost:8080">http://localhost:8080</a>).</li>
</ol> </ol>
<h2>Automation</h2> <h2>Automation</h2>
<p><a class="reference-link" href="#root/_help_pgxEVkzLl1OP">ETAPI (REST API)</a>&nbsp;could <p><a class="reference-link" href="#root/_help_pgxEVkzLl1OP">ETAPI (REST API)</a>&nbsp;could

View File

@@ -0,0 +1,2 @@
# Note Revisions
The revision API on the server side is managed by `apps/server/src/routes/api/revisions.ts`

View File

@@ -12093,7 +12093,7 @@
"R9pX4DGra2Vt", "R9pX4DGra2Vt",
"ycBFjKrrwE9p" "ycBFjKrrwE9p"
], ],
"title": "Exporting HTML for web publishing", "title": "Exporting static HTML for web publishing",
"notePosition": 20, "notePosition": 20,
"prefix": null, "prefix": null,
"isExpanded": false, "isExpanded": false,
@@ -12130,7 +12130,7 @@
} }
], ],
"format": "markdown", "format": "markdown",
"dataFileName": "Exporting HTML for web publish.md", "dataFileName": "Exporting static HTML for web .md",
"attachments": [] "attachments": []
}, },
{ {

View File

@@ -50,7 +50,7 @@ You can view a list of all shared notes by clicking on "Show Shared Notes Subtre
* Shared notes are published on the open internet and can be accessed by anyone with the URL unless the notes are password-protected. * Shared notes are published on the open internet and can be accessed by anyone with the URL unless the notes are password-protected.
* The URL's randomness does not provide security, so it is crucial not to share sensitive information through this feature. * The URL's randomness does not provide security, so it is crucial not to share sensitive information through this feature.
* Trilium takes precautions to protect your publicly shared instance from leaking information for non-shared notes, including opening a separate read-only connection to the <a class="reference-link" href="Database.md">Database</a>. Depending on your threat model, it might make more sense to use <a class="reference-link" href="Sharing/Exporting%20HTML%20for%20web%20publish.md">Exporting HTML for web publishing</a> and use battle-tested web servers such as Nginx or Apache to serve static content. * Trilium takes precautions to protect your publicly shared instance from leaking information for non-shared notes, including opening a separate read-only connection to the <a class="reference-link" href="Database.md">Database</a>. Depending on your threat model, it might make more sense to use <a class="reference-link" href="Sharing/Exporting%20static%20HTML%20for%20web%20.md">Exporting HTML for web publishing</a> and use battle-tested web servers such as Nginx or Apache to serve static content.
### Password protection ### Password protection

View File

@@ -1,4 +1,4 @@
# Exporting HTML for web publishing # Exporting static HTML for web publishing
As described in <a class="reference-link" href="../Sharing.md">Sharing</a>, Trilium can act as a public server in which the shared notes are displayed in read-only mode. While this can work in most cases, it's generally not meant for high-traffic websites and since it's running on a Node.js server it can be potentially exploited. As described in <a class="reference-link" href="../Sharing.md">Sharing</a>, Trilium can act as a public server in which the shared notes are displayed in read-only mode. While this can work in most cases, it's generally not meant for high-traffic websites and since it's running on a Node.js server it can be potentially exploited.
Another alternative is to generate static HTML files (just like other static site generators such as [MkDocs](https://www.mkdocs.org/)). Since the normal HTML ZIP export does not contain any styling or additional functionality, Trilium provides a way to export the same layout and style as the <a class="reference-link" href="../Sharing.md">Sharing</a> function into static HTML files. Another alternative is to generate static HTML files (just like other static site generators such as [MkDocs](https://www.mkdocs.org/)). Since the normal HTML ZIP export does not contain any styling or additional functionality, Trilium provides a way to export the same layout and style as the <a class="reference-link" href="../Sharing.md">Sharing</a> function into static HTML files.
@@ -23,6 +23,10 @@ Apart from normal <a class="reference-link" href="../Sharing.md">Sharing</a>, e
* The name of the files/URLs will prefer `shareAlias` to allow for clean URLs. * The name of the files/URLs will prefer `shareAlias` to allow for clean URLs.
* The export requires a functional web server as the pages will not render properly if accessed locally via a web browser due to the use of module scripts. * The export requires a functional web server as the pages will not render properly if accessed locally via a web browser due to the use of module scripts.
* The directory structure is also slightly different:
* A normal HTML export results in an index file and a single directory.
* Instead, for static exporting the top-root level becomes the index file and the child directories are on the root instead.
* This makes it possible to easily publish to a website, without forcing everything but the root note to be in a sub-directory.
## Testing locally ## Testing locally