From 5807f6913f0a07a36995422079c12a236177e939 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar <3998+srid@users.noreply.github.com> Date: Wed, 27 Dec 2023 14:20:17 -0500 Subject: [PATCH] Folgezettel-aware sidebar + new configurable 'default' layout (#483) - **BACKWARDS INCOMPATIBLE** A new HTML template layout "default" (unifies and) replaces both "book" and "note" layout. - Sidebar tree is now computed from the folgezettel graph, which is a superset of the folder hierarchy. The index page's tree inherits the same. - The semantics of `folder-folgezettel` is now applied in inverse (see docs) --- docs/guide/folgezettel.md | 41 ++++++++++ docs/guide/html-template.md | 6 +- docs/guide/html-template/breadcrumbs.md | 13 +++ docs/guide/html-template/neuron-layout.md | 32 ++++++-- docs/guide/html-template/search.md | 3 +- docs/guide/html-template/sidebar.md | 12 ++- docs/guide/html-template/uptree.md | 32 ++------ docs/guide/markdown.md | 3 + emanote/CHANGELOG.md | 3 + emanote/default/index.yaml | 26 +++--- emanote/default/templates/base.tpl | 2 +- .../components/note-uptree-recurse.tpl | 8 +- .../templates/components/sidebar-tree.tpl | 46 ++++++----- .../default/templates/components/sidebar.tpl | 2 +- emanote/default/templates/layouts/book.tpl | 25 ------ emanote/default/templates/layouts/default.tpl | 71 ++++++++++++++++ emanote/default/templates/layouts/note.tpl | 31 ------- emanote/emanote.cabal | 3 +- emanote/src/Emanote.hs | 12 ++- emanote/src/Emanote/Model/Graph.hs | 81 +++++++++++++++---- emanote/src/Emanote/Model/Note.hs | 6 +- emanote/src/Emanote/Model/Type.hs | 15 ++-- emanote/src/Emanote/View/Template.hs | 36 ++++++--- 23 files changed, 336 insertions(+), 173 deletions(-) create mode 100644 docs/guide/folgezettel.md create mode 100644 docs/guide/html-template/breadcrumbs.md delete mode 100644 emanote/default/templates/layouts/book.tpl create mode 100644 emanote/default/templates/layouts/default.tpl delete mode 100644 emanote/default/templates/layouts/note.tpl diff --git a/docs/guide/folgezettel.md b/docs/guide/folgezettel.md new file mode 100644 index 000000000..536a3f982 --- /dev/null +++ b/docs/guide/folgezettel.md @@ -0,0 +1,41 @@ +--- +slug: folgezettel +--- + +# Folgezettel links + +Wikilinks can be of special type called a "folgezettel". They are created with a special variation of emanote link syntax. + +Conceptually, a [folgezettel](https://neuron.zettel.page/folgezettel-heterarchy) link can be thought of as an arrow from a parent note to a descendent note. + +## Syntax + +```markdown +## A folgezettel link from another page to this one: + +Here is the #[[source-note]] + +## A folgezettel link from this page to another one: + +Here is the [[target-note]]# +``` + +{#folder} +## Folder notes + +By default, Emanote includes any directories in your note's path as vertices in the folgezettel graph. This makes the folder note a folgezettel parent of the child note. The contents of a folder, likewise, become folgezetten children of the folder note. For eg., in `foo/bar/qux.md`, "foo" is a folgezettel parent of "bar", and "bar" is a folgezettel parent of "qux". + +>[!note] +> The top-level root folder is not considered a folgezettel by default, unless you specify it (as shown below). This is to support the use-case of the user having a *flat list* of notes *without* subdirectories, but connected through [[folgezettel]]. + +This behavior can be configured. To turn it off on a per-folder basis, set the corresponding flag in [[yaml-config|your configuration]] to `false` as shown here: + +```yaml +emanote: + # Whether to automatically treat the contents of this + # folder note as its folgezettel children + folder-folgezettel: false +``` + +>[!tip] +> Put this configuration in `foo.md` if you want to disable folder folgezettel for just that folder `foo/`. Put it in `foo.yaml` if you want to disable it for `foo/` and all subfolders under it recursively. Put it in top-level `index.yaml` to disable it for all folders. See [[yaml-config]] for more details. \ No newline at end of file diff --git a/docs/guide/html-template.md b/docs/guide/html-template.md index 5d8cb0022..4b1685885 100644 --- a/docs/guide/html-template.md +++ b/docs/guide/html-template.md @@ -4,12 +4,12 @@ Unlike [[neuron|Neuron]], Emanote's generated HTML can be **completely** customi The default HTML templates are stored in the [[layer|default layer]], which can you override either totally or in subset. -## Layouts +## Default Layout -Emanote includes two builtin layouts, called `book` (the default) and [[neuron-layout|`note`]], but you can also write your own HTML layout from scratch, as long as you specify that template in [[yaml-config]] for the notes in question. For eg., [`templates/home.tpl`](https://github.com/srid/srid/blob/master/content/templates/home.tpl) is how https://srid.ca homepage is generated, because its [`index.md`](https://raw.githubusercontent.com/srid/srid/master/index.md) specifies this template as `template.name` in its YAML frontmatter (which could also be `index.yaml`). +Emanote includes a default layout that includes a [[sidebar]], but can be customized to mimic [[neuron-layout]]. You may also write your own HTML layout from scratch, as long as you specify that template in [[yaml-config]] for the notes in question. For eg., [`templates/home.tpl`](https://github.com/srid/srid/blob/master/templates/home.tpl) is how https://srid.ca homepage is generated, because its [`index.md`](https://raw.githubusercontent.com/srid/srid/master/index.md) specifies this template as `template.name` in its YAML frontmatter (which could also be `index.yaml`). ## Features ```query children:. -``` \ No newline at end of file +``` diff --git a/docs/guide/html-template/breadcrumbs.md b/docs/guide/html-template/breadcrumbs.md new file mode 100644 index 000000000..074cf1845 --- /dev/null +++ b/docs/guide/html-template/breadcrumbs.md @@ -0,0 +1,13 @@ +--- +slug: breadcrumbs +--- + + +# Breadcrumbs + +On mobile view, [breadcrumbs] are displayed at the top. The path of the crumbs is determined from the filesystem path of the associated source file. Breadcrumbs can be disabled in [[yaml-config]]; see [[neuron-layout]] for an example. + +>[!warning] Folgezettel +> Breadcrumbs do not use [[folgezettel]]. + +[breadcrumbs]: https://en.wikipedia.org/wiki/Breadcrumb_navigation \ No newline at end of file diff --git a/docs/guide/html-template/neuron-layout.md b/docs/guide/html-template/neuron-layout.md index 1c836d7bb..3ca5881b4 100644 --- a/docs/guide/html-template/neuron-layout.md +++ b/docs/guide/html-template/neuron-layout.md @@ -1,18 +1,40 @@ --- template: - name: /templates/layouts/note + uptree: + enable: true + sidebar: + enable: false + breadcrumbs: + enable: false + base: + containerClass: container mx-auto max-w-prose --- # Neuron-like layout -Emanote comes with two built-in [[html-template|HTML template]] layouts. The default layout is called "book", but you may select the "note" layout (which mimics [Neuron](https://neuron.zettel.page/)) by adding the following to your [[yaml-config|index.yaml]], +Emanote's builtin [[html-template|HTML template]] layout can be configured to toggle UX features on or off. The default configuration includes [[sidebar]] and [[breadcrumbs]] but hides the [[uptree]]. To mimic the layout used by [Neuron](https://neuron.zettel.page/), turn off sidebar and breadcrumbs while enabling the uptree. Add this to your [[yaml-config]]: ```yml template: - name: /templates/layouts/note + uptree: + enable: true + sidebar: + enable: false + breadcrumbs: + enable: false + base: + containerClass: container mx-auto max-w-prose ``` -The "note" layout includes the [[uptree]] of Neuron based on folgezettel links as well as directory layout. Note that all top-level notes are automatically made a folgezettel branch of the root note (index), such that the "home" link appears on top in the uplink tree of all notes. +This includes the [[uptree]] of Neuron based on folgezettel links as well as directory layout. Note that all top-level notes are automatically made a folgezettel branch of the root note (index), such that the "home" link appears on top in the uplink tree of all notes. > [!tip] Demo -> As a demo, the very page you are viewing is rendered using the "note" layout (whilst leaving the rest of the site to use the default "book" layout.) +> As a demo, the very page you are viewing is rendered using this template configuration (whilst leaving the rest of the site to use the default configuration) + +## In lieu of sidebar + +In the absence of [[sidebar]], you may use the [[query|folgezettel children query]] to show the children of the current note. Example below: + +```query +children:. +``` \ No newline at end of file diff --git a/docs/guide/html-template/search.md b/docs/guide/html-template/search.md index f724863dd..16e4ca236 100644 --- a/docs/guide/html-template/search.md +++ b/docs/guide/html-template/search.md @@ -8,7 +8,8 @@ Emanote provides client-side full-text search using [Stork](https://stork-search You can trigger search input in one of the following ways: - Press `Ctrl+K` (or `⌘K` on macOS). -- Click the lens icon on the sidebar (if using the 'book' [[html-template|template layout]]) or top-right corner (if using [[neuron-layout]]). +- Click the lens icon on the sidebar + - If the sidebar is disabled (eg.: you are on [[neuron-layout]]), the search lens icon will be on the top-right corner. ## Including frontmatter in the search index diff --git a/docs/guide/html-template/sidebar.md b/docs/guide/html-template/sidebar.md index e95a9802d..aa90615bb 100644 --- a/docs/guide/html-template/sidebar.md +++ b/docs/guide/html-template/sidebar.md @@ -1,9 +1,19 @@ # Sidebar -In [[html-template|the `book` template]], the sidebar is rendered on the left side. The sidebar tree is determined from the directory layout of the [[markdown|Markdown]] or [[orgmode|Org]] files. +In [[html-template|the default template]], the sidebar is rendered on the left side. The sidebar tree is determined from [[folgezettel|folgezettel heterarchy]]. - The sidebar tree is collapsed by default. But this can be disabled by setting `template.sidebar.collapsed` to `false` in [[yaml-config]] - The ordering of children in the tree is determined in the following order (this is also the order in which [[query]] results are rendered by default): 1. if `template.sidebar.folders-first` is set to `true` (default `false`), directories are put before single notes, respecting the other order criteria. Otherwise, directories and notes will be interleaved. 2. If the `order` [[yaml-config|frontmatter]] metadata exists, use that as the primary sort key. 3. If the note has a H1 title, use that as the secondary sort key; otherwise, use the note filename as the secondary sort key. + +## Disabling the sidebar + +In [[yaml-config]], + +```yaml +template: + sidebar: + enable: false +``` \ No newline at end of file diff --git a/docs/guide/html-template/uptree.md b/docs/guide/html-template/uptree.md index 9105bb27e..f55a3dfba 100644 --- a/docs/guide/html-template/uptree.md +++ b/docs/guide/html-template/uptree.md @@ -1,34 +1,18 @@ # Uplink tree -The _uplink tree_ or "uptree"[^neuron] is a feature available in #[[neuron-layout|the `note` template]], which visualizes hierarchical relationships between notes as a graph at the top of the page. +The _uplink tree_ or "uptree"[^neuron] is a feature available in #[[html-template]], which visualizes hierarchical relationships between notes as a graph at the top of the page. [^neuron]: This feature was inspired by an equivalent feature [from Neuron](https://neuron.zettel.page/uplink-tree). -These relationships are called by _folgezettel links_ and created with a special variation of emanote link syntax. +These relationships are called by [[folgezettel]]. -Conceptually, a [folgezettel](https://neuron.zettel.page/folgezettel-heterarchy) link can be thought of as an arrow from a parent note to a descendent note. - -## Syntax - -```markdown -## A folgezettel link from another page to this one: - -Here is the #[[source-note]] - -## A folgezettel link from this page to another one: - -Here is the [[target-note]]# -``` - -## Folder nodes - -By default, Emanote also includes any directories in your note's path as vertices in the uptree graph. - -This behavior can be configured. To turn off the implicit folder nodes, set to `false` the corresponding flag in [[yaml-config|your configuration]] as shown here: +To enable the uptree, add the following to your [[yaml-config]]: ```yaml -emanote: - # Whether to automatically treat folder notes as a folgezettel parent of its contents - folder-folgezettel: false +template: + sidebar: + enable: false ``` +>[!tip] See also +> #[[neuron-layout]]. diff --git a/docs/guide/markdown.md b/docs/guide/markdown.md index e002dbd85..286b178e2 100644 --- a/docs/guide/markdown.md +++ b/docs/guide/markdown.md @@ -17,6 +17,9 @@ you can specify a custom title as `[[neuron|Moving off neuron]]` which renders a Broken links render differently, for example: [[Foo bar]] (if a wiki-link) or [Foo bar](foo-bar.md) (if a regular Markdown link). +>[!tip] Folgezettel +> See [[folgezettel]] for a special type of wiki-link used to define the [[sidebar]] (and [[uptree]]) heirarchy. + ### Anchors Wiki-links [do not yet](https://github.com/srid/emanote/discussions/105) support anchor links, but they work for regular links ([example link](./markdown.md#lists)). diff --git a/emanote/CHANGELOG.md b/emanote/CHANGELOG.md index 88156c023..900a4164c 100644 --- a/emanote/CHANGELOG.md +++ b/emanote/CHANGELOG.md @@ -6,6 +6,9 @@ - Obsidian-style callouts ([\#466](https://github.com/srid/emanote/pull/466)) - `emanote run --no-ws` option to disable WebSocket monitoring. This is useful for using Emanote to serve the HTML site directly on the internet, without needing to statically generate it. - Add query syntax for listing folgezetten children & parents ([\#476](https://github.com/srid/emanote/pull/476)) + - **BACKWARDS INCOMPATIBLE** A new HTML template layout "default" (unifies and) replaces both "book" and "note" layout. ([\#483](https://github.com/srid/emanote/pull/483)) + - Sidebar tree is now computed from the folgezettel graph, which is a superset of the folder hierarchy. The index page's tree inherits the same. + - The semantics of `folder-folgezettel` is now applied in inverse (see docs) ## 1.2.0.0 (2023-08-24) diff --git a/emanote/default/index.yaml b/emanote/default/index.yaml index 6585be5d4..f9f6f7b72 100644 --- a/emanote/default/index.yaml +++ b/emanote/default/index.yaml @@ -11,22 +11,18 @@ tags: [] # TODO: How to design this when generating RSS feeds? template: # Which template to use to render notes. The filepath without the .tpl extension. - name: /templates/layouts/book - # Layout specific settings - layout: - # For base.tpl - base: - # The class to apply for element when using base.tpl (used by note and book layouts) - bodyClass: bg-gray-400 overflow-y-scroll - note: - containerClass: container mx-auto max-w-prose - book: - containerClass: container mx-auto + name: /templates/layouts/default + # Base settings for our default layout. + base: + # The class to apply for element when + bodyClass: bg-gray-400 overflow-y-scroll + containerClass: container mx-auto error: containerClass: container mx-auto max-w-prose uptree: + enable: false # Class to apply for uptree's nodes - nodeClass: text-gray-900 + nodeClass: text-gray-900 hover:bg-${theme}-500 hover:text-white cursor-pointer # List of available colors: https://v2.tailwindcss.com/docs/customizing-colors#default-color-palette theme: blue # Value of the tag. @@ -35,11 +31,14 @@ template: urlStrategy: direct iconUrl: ${ema:homeUrl}favicon.svg sidebar: + enable: true # Whether this node in the sidebar tree should remain collapsed by default # (unless a route in it is active) collapsed: true # Weather this node should put folders before single notes folders-first: false + breadcrumbs: + enable: true stork: # https://stork-search.net/docs/config-ref#frontmatter_handling frontmatter-handling: omit @@ -138,4 +137,5 @@ js: emanote: # Whether to automatically treat folder notes as a folgezettel parent of its contents - folder-folgezettel: true + # By default, all but top-level folders are treated as folgezettel parents. + # folder-folgezettel: true diff --git a/emanote/default/templates/base.tpl b/emanote/default/templates/base.tpl index 829ae0b71..08da8ba1a 100644 --- a/emanote/default/templates/base.tpl +++ b/emanote/default/templates/base.tpl @@ -128,7 +128,7 @@ w-4 h-4 flex-shrink-0 - + diff --git a/emanote/default/templates/components/note-uptree-recurse.tpl b/emanote/default/templates/components/note-uptree-recurse.tpl index f9431ebbd..456190fc0 100644 --- a/emanote/default/templates/components/note-uptree-recurse.tpl +++ b/emanote/default/templates/components/note-uptree-recurse.tpl @@ -1,10 +1,10 @@
  • - +