From bbfdfd93d2851d3a59dbf7f4fe1d5e98e5dc9901 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 17:05:57 -0400 Subject: [PATCH 01/13] docs: reorganise docs site around reader concern MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `docs/` is restructured into six top-level sections — `start`, `authoring`, `config`, `theme`, `extend`, `reference` — each driven by a single reader concern instead of mixed under one big `guide/` umbrella with overlapping `tips/` and nested `start/resources/`. URLs are unchanged. Every docs page already declared a flat `slug:` so the URL is decoupled from the folder path; reshuffling folders changes only the sidebar tree. Legacy paths (`/guide/*`, `/tips/*`, `/start/resources/*`) continue to redirect via `docs/_redirects`. Touched outside docs/ are pointer updates: source-tree references to `docs/guide/...` in `.agency/`, `.apm/`, a Haddock comment in `Emanote.Model.Note.Filter`, and a stale path comment in the default `index.yaml`. CHANGELOG entry added under Unreleased. --- .agency/code-police.md | 6 ++--- .agency/do.md | 2 +- .../instructions/emanote-docs.instructions.md | 17 +++++++++++-- docs/AGENTS.md | 19 ++++++++++++--- docs/_redirects | 23 ++++++++++++++---- docs/authoring.md | 23 ++++++++++++++++++ docs/{tips => authoring}/adding-images.md | 0 docs/{guide => authoring}/daily-notes.md | 0 .../daily-notes/2025-03-14.md | 0 .../daily-notes/2025-03-15.md | 0 docs/{guide => authoring}/export.md | 0 docs/{guide => authoring}/feed.md | 0 docs/{guide => authoring}/markdown.md | 0 docs/{guide => authoring}/markdown/Sample.txt | 0 docs/{guide => authoring}/markdown/callout.md | 0 docs/{guide => authoring}/markdown/cat.ogg | Bin .../markdown/code-samples/c-code.c | 0 .../markdown/code-samples/config-demo.toml | 0 .../markdown/code-samples/data-demo.json | 0 .../markdown/code-samples/haskell-code.hs | 0 .../markdown/code-samples/styles-demo.css | 0 .../markdown/custom-style.md | 0 .../markdown/cyclic-embed-demo.md | 0 .../markdown/death-note.mp4 | Bin .../markdown/disaster-girl.jpg | Bin docs/{guide => authoring}/markdown/embed.md | 0 .../markdown/external-link-icon.svg | 0 .../markdown/file-links.md | 0 .../markdown/git-cheat-sheet-education.pdf | Bin .../markdown/hello-badge.svg | 0 docs/{guide => authoring}/markdown/pIqaD.svg | 0 docs/{tips => authoring}/math.md | 0 docs/{tips => authoring}/mermaid.md | 0 docs/{guide => authoring}/orgmode.org | 6 ++--- docs/{guide => authoring}/orgmode.yaml | 0 docs/{guide => authoring}/query.md | 0 .../syntax-highlighting.md | 0 docs/{guide => authoring}/wikilinks.md | 2 +- docs/config.md | 19 +++++++++++++++ docs/{guide => config}/emanoteignore.md | 0 docs/{guide => config}/folder-note.md | 0 docs/{guide => config}/folgezettel.md | 0 docs/{guide => config}/i18n.md | 0 docs/{guide => config}/i18n/i18n.fr.md | 2 +- docs/{guide => config}/i18n/i18n.zh.md | 2 +- docs/{guide => config}/layer.md | 0 docs/{guide => config}/yaml-config.md | 2 +- docs/extend.md | 15 ++++++++++++ docs/{guide => extend}/lua-filters.md | 0 .../{guide => extend}/lua-filters/diagrams.md | 0 .../lua-filters/writing-filters.md | 0 .../lua-filters/writing-filters/slides.md | 0 docs/{guide => extend}/mcp.md | 2 +- docs/guide.md | 21 ---------------- docs/reference.md | 17 +++++++++++++ docs/{ => reference}/examples.md | 0 docs/{start => reference}/known-issues.md | 0 docs/{start => reference}/neuron.md | 0 docs/{start/resources => reference}/zk.md | 0 docs/start.md | 2 +- docs/start/{resources => }/editors.md | 0 docs/start/{resources => }/editors/nota.md | 0 docs/start/{resources => }/editors/obsmd.md | 0 docs/start/{resources => }/editors/vim.md | 0 docs/start/{resources => }/editors/vscode.md | 0 .../start/{resources => }/emanote-template.md | 0 docs/start/resources.md | 12 --------- docs/{tips => start}/sync.md | 2 -- docs/theme.md | 14 +++++++++++ docs/{guide => theme}/html-template.md | 0 .../html-template/backlinks.md | 0 .../html-template/breadcrumbs.md | 0 .../html-template/dark-mode.md | 0 .../html-template/external-links.md | 0 .../html-template/focus-mode.md | 0 docs/{guide => theme}/html-template/fonts.md | 0 .../html-template/neuron-layout.md | 0 docs/{guide => theme}/html-template/ogp.md | 0 .../html-template/right-panel.md | 0 docs/{guide => theme}/html-template/search.md | 0 .../{guide => theme}/html-template/sidebar.md | 0 docs/{guide => theme}/html-template/toc.md | 0 docs/{guide => theme}/html-template/uptree.md | 0 docs/tips.md | 12 --------- emanote/CHANGELOG.md | 1 + emanote/default/index.yaml | 2 +- emanote/src/Emanote/Model/Note/Filter.hs | 2 +- 87 files changed, 153 insertions(+), 72 deletions(-) create mode 100644 docs/authoring.md rename docs/{tips => authoring}/adding-images.md (100%) rename docs/{guide => authoring}/daily-notes.md (100%) rename docs/{guide => authoring}/daily-notes/2025-03-14.md (100%) rename docs/{guide => authoring}/daily-notes/2025-03-15.md (100%) rename docs/{guide => authoring}/export.md (100%) rename docs/{guide => authoring}/feed.md (100%) rename docs/{guide => authoring}/markdown.md (100%) rename docs/{guide => authoring}/markdown/Sample.txt (100%) rename docs/{guide => authoring}/markdown/callout.md (100%) rename docs/{guide => authoring}/markdown/cat.ogg (100%) rename docs/{guide => authoring}/markdown/code-samples/c-code.c (100%) rename docs/{guide => authoring}/markdown/code-samples/config-demo.toml (100%) rename docs/{guide => authoring}/markdown/code-samples/data-demo.json (100%) rename docs/{guide => authoring}/markdown/code-samples/haskell-code.hs (100%) rename docs/{guide => authoring}/markdown/code-samples/styles-demo.css (100%) rename docs/{guide => authoring}/markdown/custom-style.md (100%) rename docs/{guide => authoring}/markdown/cyclic-embed-demo.md (100%) rename docs/{guide => authoring}/markdown/death-note.mp4 (100%) rename docs/{guide => authoring}/markdown/disaster-girl.jpg (100%) rename docs/{guide => authoring}/markdown/embed.md (100%) rename docs/{guide => authoring}/markdown/external-link-icon.svg (100%) rename docs/{guide => authoring}/markdown/file-links.md (100%) rename docs/{guide => authoring}/markdown/git-cheat-sheet-education.pdf (100%) rename docs/{guide => authoring}/markdown/hello-badge.svg (100%) rename docs/{guide => authoring}/markdown/pIqaD.svg (100%) rename docs/{tips => authoring}/math.md (100%) rename docs/{tips => authoring}/mermaid.md (100%) rename docs/{guide => authoring}/orgmode.org (74%) rename docs/{guide => authoring}/orgmode.yaml (100%) rename docs/{guide => authoring}/query.md (100%) rename docs/{tips => authoring}/syntax-highlighting.md (100%) rename docs/{guide => authoring}/wikilinks.md (91%) create mode 100644 docs/config.md rename docs/{guide => config}/emanoteignore.md (100%) rename docs/{guide => config}/folder-note.md (100%) rename docs/{guide => config}/folgezettel.md (100%) rename docs/{guide => config}/i18n.md (100%) rename docs/{guide => config}/i18n/i18n.fr.md (97%) rename docs/{guide => config}/i18n/i18n.zh.md (97%) rename docs/{guide => config}/layer.md (100%) rename docs/{guide => config}/yaml-config.md (96%) create mode 100644 docs/extend.md rename docs/{guide => extend}/lua-filters.md (100%) rename docs/{guide => extend}/lua-filters/diagrams.md (100%) rename docs/{guide => extend}/lua-filters/writing-filters.md (100%) rename docs/{guide => extend}/lua-filters/writing-filters/slides.md (100%) rename docs/{guide => extend}/mcp.md (98%) delete mode 100644 docs/guide.md create mode 100644 docs/reference.md rename docs/{ => reference}/examples.md (100%) rename docs/{start => reference}/known-issues.md (100%) rename docs/{start => reference}/neuron.md (100%) rename docs/{start/resources => reference}/zk.md (100%) rename docs/start/{resources => }/editors.md (100%) rename docs/start/{resources => }/editors/nota.md (100%) rename docs/start/{resources => }/editors/obsmd.md (100%) rename docs/start/{resources => }/editors/vim.md (100%) rename docs/start/{resources => }/editors/vscode.md (100%) rename docs/start/{resources => }/emanote-template.md (100%) delete mode 100644 docs/start/resources.md rename docs/{tips => start}/sync.md (98%) create mode 100644 docs/theme.md rename docs/{guide => theme}/html-template.md (100%) rename docs/{guide => theme}/html-template/backlinks.md (100%) rename docs/{guide => theme}/html-template/breadcrumbs.md (100%) rename docs/{guide => theme}/html-template/dark-mode.md (100%) rename docs/{guide => theme}/html-template/external-links.md (100%) rename docs/{guide => theme}/html-template/focus-mode.md (100%) rename docs/{guide => theme}/html-template/fonts.md (100%) rename docs/{guide => theme}/html-template/neuron-layout.md (100%) rename docs/{guide => theme}/html-template/ogp.md (100%) rename docs/{guide => theme}/html-template/right-panel.md (100%) rename docs/{guide => theme}/html-template/search.md (100%) rename docs/{guide => theme}/html-template/sidebar.md (100%) rename docs/{guide => theme}/html-template/toc.md (100%) rename docs/{guide => theme}/html-template/uptree.md (100%) delete mode 100644 docs/tips.md diff --git a/.agency/code-police.md b/.agency/code-police.md index 8a6ead248..4b9ec237f 100644 --- a/.agency/code-police.md +++ b/.agency/code-police.md @@ -8,7 +8,7 @@ The patterns here came out of [#672](https://github.com/srid/emanote/pull/672) ( A docs-page `slug:` must be a **single path segment**, not a multi-segment slash-path. Two reasons: -- The page's directory location already encodes hierarchy. A slug that re-encodes that hierarchy is duplicated state that drifts the moment one of the two moves (a page at `docs/guide/lua-filters/diagrams.md` with `slug: lua-filters/diagrams` carries the same path in two places — a rename of the parent or the page silently breaks the mirror). +- The page's directory location already encodes hierarchy. A slug that re-encodes that hierarchy is duplicated state that drifts the moment one of the two moves (a page at `docs/extend/lua-filters/diagrams.md` with `slug: lua-filters/diagrams` carries the same path in two places — a rename of the parent or the page silently breaks the mirror). - Public URLs stay short and rename-stable. `[[diagrams]]` survives a future reshuffle of where the page sits in the docs tree; `[[lua-filters/diagrams]]` does not. Acceptable: `slug: diagrams`, `slug: yaml-config`, `slug: html-template`, `slug: i18n.fr` (single segment; dot-namespaced for locale or close variants). @@ -17,7 +17,7 @@ Unacceptable: `slug: lua-filters/diagrams`, `slug: guide/whatever` — anything Wikilinks that reference the page use the single-segment form too: `[[diagrams]]`, not `[[lua-filters/diagrams]]`. -> _New rule from this PR_: an early draft of [[diagrams]] used `slug: lua-filters/diagrams` to mirror its directory placement under `docs/guide/lua-filters/`. The slug was reduced to `diagrams` so a future move of the file doesn't invalidate every inbound wikilink. +> _New rule from this PR_: an early draft of [[diagrams]] used `slug: lua-filters/diagrams` to mirror its directory placement under `docs/extend/lua-filters/`. The slug was reduced to `diagrams` so a future move of the file doesn't invalidate every inbound wikilink. ## docs-internal-wikilinks @@ -26,7 +26,7 @@ When reviewing documentation changes under `docs/`, check internal documentation - Use wikilinks for references to existing docs pages, such as `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, `[[markdown]]`, `[[query]]`, `[[search]]`, and related guide pages. - Prefer wikilinks over raw relative Markdown links for internal docs references. - Replace bare mentions of concepts covered by existing docs pages with wikilinks, unless doing so would make the sentence noisy or misleading. -- New or newly promoted guide pages should be linked from the nearest relevant index page, usually `docs/guide.md`. +- New or newly promoted pages should be linked from the relevant section folder-note (`docs/authoring/authoring.md`, `docs/config/config.md`, `docs/theme/theme.md`, `docs/extend/extend.md`, `docs/reference/reference.md`, or `docs/start/start.md`). This rule is meant to catch isolated docs pages that repeat or mention existing Emanote concepts without connecting to the surrounding guide. diff --git a/.agency/do.md b/.agency/do.md index e03ffc9d7..6157d048c 100644 --- a/.agency/do.md +++ b/.agency/do.md @@ -21,7 +21,7 @@ Keep `README.md`, `docs/` (user documentation), and `CHANGELOG.md` (under the `U **CHANGELOG style: one concise line per PR.** Each user-facing change gets a single bullet — issue/PR number, the headline, and a one-line link to where the detail lives (a docs page, a deep-dive `[[wikilink]]`, the issue, …). The detail belongs on the docs page or in the PR description, not in the CHANGELOG. Multi-paragraph entries that re-explain the design are clutter; if a reviewer needs more than the link, the docs page wasn't pulling its weight. -New or fixed **Markdown-syntax features** should be demonstrated in [`docs/guide/markdown.md`](../docs/guide/markdown.md) so the live example serves as both reference and regression check. A working `
` block, a new callout type, a new wiki-link form — each goes there as a real rendered sample, not just a CHANGELOG note. +New or fixed **Markdown-syntax features** should be demonstrated in [`docs/authoring/markdown.md`](../docs/authoring/markdown.md) so the live example serves as both reference and regression check. A working `
` block, a new callout type, a new wiki-link form — each goes there as a real rendered sample, not just a CHANGELOG note. ## HACK comments diff --git a/.apm/instructions/emanote-docs.instructions.md b/.apm/instructions/emanote-docs.instructions.md index 9ac9244f3..2a62c6272 100644 --- a/.apm/instructions/emanote-docs.instructions.md +++ b/.apm/instructions/emanote-docs.instructions.md @@ -9,7 +9,7 @@ When adding a new documentation page under `docs/`, give it an explicit simple ` ## Wikilink internal references -Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant guide page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference. +Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant docs page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference. When you add prose that mentions another concept covered by an existing page, replace the bare phrase with a wikilink — e.g. write `… see [[html-template]] for the override mechanism …` rather than restating it. If no page covers the concept yet, this is a signal to consider promoting it to a dedicated page (see below) rather than burying the explanation inside an unrelated guide. @@ -21,4 +21,17 @@ A section under one guide page should be **promoted to its own page** once any o - It carries reference material — splice tables, override protocols, configuration surfaces — that other pages need to wikilink to. - It documents a feature with its own slug-worthy concept name (`wikilinks`, `callout`, `folgezettel`, etc.). -Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to `docs/guide.md`'s top-level list. Inbound links from other docs pages should point at the dedicated page. +Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to the relevant section folder-note (`docs/authoring/authoring.md`, `docs/config/config.md`, `docs/theme/theme.md`, `docs/extend/extend.md`, `docs/reference/reference.md`, or `docs/start/start.md`). Inbound links from other docs pages should point at the dedicated page. + +## Section layout + +`docs/` is organised into six top-level sections, each driven by a reader concern: + +- `start/` — install, editor setup, deploying. +- `authoring/` — input formats, link syntax, graph structures, render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export). +- `config/` — notebook model: `yaml-config`, `layer`, `emanoteignore`, `folder-note`, `folgezettel`, `i18n`. +- `theme/` — HTML/Heist template customisation (`html-template` and its sub-pages only). +- `extend/` — code-level extension: Pandoc Lua filters, MCP server. +- `reference/` — migration (`neuron`), ecosystem (`zk`, `examples`), edge cases (`known-issues`). + +Place new pages in the section whose reader concern they match; cross-link via wikilinks rather than reorganising. The folder structure drives the sidebar tree; the page slug determines the public URL (see the slug rule above). diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 6ae0d3c49..050e017fe 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md - + @@ -13,7 +13,7 @@ When adding a new documentation page under `docs/`, give it an explicit simple ` ## Wikilink internal references -Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant guide page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference. +Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant docs page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference. When you add prose that mentions another concept covered by an existing page, replace the bare phrase with a wikilink — e.g. write `… see [[html-template]] for the override mechanism …` rather than restating it. If no page covers the concept yet, this is a signal to consider promoting it to a dedicated page (see below) rather than burying the explanation inside an unrelated guide. @@ -25,7 +25,20 @@ A section under one guide page should be **promoted to its own page** once any o - It carries reference material — splice tables, override protocols, configuration surfaces — that other pages need to wikilink to. - It documents a feature with its own slug-worthy concept name (`wikilinks`, `callout`, `folgezettel`, etc.). -Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to `docs/guide.md`'s top-level list. Inbound links from other docs pages should point at the dedicated page. +Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to the relevant section folder-note (`docs/authoring/authoring.md`, `docs/config/config.md`, `docs/theme/theme.md`, `docs/extend/extend.md`, `docs/reference/reference.md`, or `docs/start/start.md`). Inbound links from other docs pages should point at the dedicated page. + +## Section layout + +`docs/` is organised into six top-level sections, each driven by a reader concern: + +- `start/` — install, editor setup, deploying. +- `authoring/` — input formats, link syntax, graph structures, render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export). +- `config/` — notebook model: `yaml-config`, `layer`, `emanoteignore`, `folder-note`, `folgezettel`, `i18n`. +- `theme/` — HTML/Heist template customisation (`html-template` and its sub-pages only). +- `extend/` — code-level extension: Pandoc Lua filters, MCP server. +- `reference/` — migration (`neuron`), ecosystem (`zk`, `examples`), edge cases (`known-issues`). + +Place new pages in the section whose reader concern they match; cross-link via wikilinks rather than reorganising. The folder structure drives the sidebar tree; the page slug determines the public URL (see the slug rule above). --- *This file was generated by APM CLI. Do not edit manually.* diff --git a/docs/_redirects b/docs/_redirects index 90acfdee2..c00fd3987 100644 --- a/docs/_redirects +++ b/docs/_redirects @@ -37,9 +37,10 @@ /start/install/wsl /wsl 301 /start/neuron /neuron 301 /start/known-issues /known-issues 301 -/start/resources /resources 301 -# Resources +# Resources (folder retired; pages flattened into /start and /reference) +/resources /start 301 +/start/resources /start 301 /start/resources/editors /editors 301 /start/resources/emanote-template /emanote-template 301 /start/resources/zk /zk 301 @@ -48,10 +49,22 @@ /start/resources/editors/vim /vim 301 /start/resources/editors/vscode /vscode 301 -# Tips +# Tips (folder retired; pages absorbed into /authoring and /start) +/tips /authoring 301 /tips/adding-images /adding-images 301 /tips/js /js 301 -/tips/js/math /tips/math 301 -/tips/js/mermaid /tips/mermaid 301 +/tips/js/math /math 301 +/tips/js/mermaid /mermaid 301 /tips/js/syntax-highlighting /syntax-highlighting 301 +/tips/math /math 301 +/tips/mermaid /mermaid 301 +/tips/syntax-highlighting /syntax-highlighting 301 /tips/sync /sync 301 + +# Guide (umbrella retired; section split into authoring/config/theme/extend) +/guide /authoring 301 +/guide/i18n /i18n 301 +/guide/wikilinks /wikilinks 301 +/guide/emanoteignore /emanoteignore 301 +/guide/mcp /mcp 301 +/guide/orgmode /orgmode 301 diff --git a/docs/authoring.md b/docs/authoring.md new file mode 100644 index 000000000..776ac5b81 --- /dev/null +++ b/docs/authoring.md @@ -0,0 +1,23 @@ +--- +slug: authoring +order: 2 +--- + +# Authoring + +What you type into a note — input formats, link syntax, graph structures, render features that an author reaches for from a Markdown buffer. + +- **[[markdown]]** — extensions on top of CommonMark: callouts, task lists, emojis, footnotes, footers +- **[[wikilinks]]** — `[[…]]` syntax, structural links, broken / ambiguous link rendering +- **[[query]]** — Obsidian-style embed queries for dynamic listings +- **[[folgezettel]]** — structural wikilinks that drive [[sidebar]] hierarchy +- **[[daily-notes]]** — date-stamped notes +- **[[orgmode]]** — Org-mode notes alongside Markdown +- **[[math]]**, **[[mermaid]]**, **[[syntax-highlighting]]**, **[[adding-images]]** — built-in render features the author types directly +- **[[feed]]**, **[[export]]** — frontmatter-declared outputs + +Cross-cutting: configuration that affects what you can type lives under [[config]] ([[yaml-config]], [[layer]]); output customisation lives under [[theme]]; code-level extension lives under [[extend]]. + +```query +path:./* +``` diff --git a/docs/tips/adding-images.md b/docs/authoring/adding-images.md similarity index 100% rename from docs/tips/adding-images.md rename to docs/authoring/adding-images.md diff --git a/docs/guide/daily-notes.md b/docs/authoring/daily-notes.md similarity index 100% rename from docs/guide/daily-notes.md rename to docs/authoring/daily-notes.md diff --git a/docs/guide/daily-notes/2025-03-14.md b/docs/authoring/daily-notes/2025-03-14.md similarity index 100% rename from docs/guide/daily-notes/2025-03-14.md rename to docs/authoring/daily-notes/2025-03-14.md diff --git a/docs/guide/daily-notes/2025-03-15.md b/docs/authoring/daily-notes/2025-03-15.md similarity index 100% rename from docs/guide/daily-notes/2025-03-15.md rename to docs/authoring/daily-notes/2025-03-15.md diff --git a/docs/guide/export.md b/docs/authoring/export.md similarity index 100% rename from docs/guide/export.md rename to docs/authoring/export.md diff --git a/docs/guide/feed.md b/docs/authoring/feed.md similarity index 100% rename from docs/guide/feed.md rename to docs/authoring/feed.md diff --git a/docs/guide/markdown.md b/docs/authoring/markdown.md similarity index 100% rename from docs/guide/markdown.md rename to docs/authoring/markdown.md diff --git a/docs/guide/markdown/Sample.txt b/docs/authoring/markdown/Sample.txt similarity index 100% rename from docs/guide/markdown/Sample.txt rename to docs/authoring/markdown/Sample.txt diff --git a/docs/guide/markdown/callout.md b/docs/authoring/markdown/callout.md similarity index 100% rename from docs/guide/markdown/callout.md rename to docs/authoring/markdown/callout.md diff --git a/docs/guide/markdown/cat.ogg b/docs/authoring/markdown/cat.ogg similarity index 100% rename from docs/guide/markdown/cat.ogg rename to docs/authoring/markdown/cat.ogg diff --git a/docs/guide/markdown/code-samples/c-code.c b/docs/authoring/markdown/code-samples/c-code.c similarity index 100% rename from docs/guide/markdown/code-samples/c-code.c rename to docs/authoring/markdown/code-samples/c-code.c diff --git a/docs/guide/markdown/code-samples/config-demo.toml b/docs/authoring/markdown/code-samples/config-demo.toml similarity index 100% rename from docs/guide/markdown/code-samples/config-demo.toml rename to docs/authoring/markdown/code-samples/config-demo.toml diff --git a/docs/guide/markdown/code-samples/data-demo.json b/docs/authoring/markdown/code-samples/data-demo.json similarity index 100% rename from docs/guide/markdown/code-samples/data-demo.json rename to docs/authoring/markdown/code-samples/data-demo.json diff --git a/docs/guide/markdown/code-samples/haskell-code.hs b/docs/authoring/markdown/code-samples/haskell-code.hs similarity index 100% rename from docs/guide/markdown/code-samples/haskell-code.hs rename to docs/authoring/markdown/code-samples/haskell-code.hs diff --git a/docs/guide/markdown/code-samples/styles-demo.css b/docs/authoring/markdown/code-samples/styles-demo.css similarity index 100% rename from docs/guide/markdown/code-samples/styles-demo.css rename to docs/authoring/markdown/code-samples/styles-demo.css diff --git a/docs/guide/markdown/custom-style.md b/docs/authoring/markdown/custom-style.md similarity index 100% rename from docs/guide/markdown/custom-style.md rename to docs/authoring/markdown/custom-style.md diff --git a/docs/guide/markdown/cyclic-embed-demo.md b/docs/authoring/markdown/cyclic-embed-demo.md similarity index 100% rename from docs/guide/markdown/cyclic-embed-demo.md rename to docs/authoring/markdown/cyclic-embed-demo.md diff --git a/docs/guide/markdown/death-note.mp4 b/docs/authoring/markdown/death-note.mp4 similarity index 100% rename from docs/guide/markdown/death-note.mp4 rename to docs/authoring/markdown/death-note.mp4 diff --git a/docs/guide/markdown/disaster-girl.jpg b/docs/authoring/markdown/disaster-girl.jpg similarity index 100% rename from docs/guide/markdown/disaster-girl.jpg rename to docs/authoring/markdown/disaster-girl.jpg diff --git a/docs/guide/markdown/embed.md b/docs/authoring/markdown/embed.md similarity index 100% rename from docs/guide/markdown/embed.md rename to docs/authoring/markdown/embed.md diff --git a/docs/guide/markdown/external-link-icon.svg b/docs/authoring/markdown/external-link-icon.svg similarity index 100% rename from docs/guide/markdown/external-link-icon.svg rename to docs/authoring/markdown/external-link-icon.svg diff --git a/docs/guide/markdown/file-links.md b/docs/authoring/markdown/file-links.md similarity index 100% rename from docs/guide/markdown/file-links.md rename to docs/authoring/markdown/file-links.md diff --git a/docs/guide/markdown/git-cheat-sheet-education.pdf b/docs/authoring/markdown/git-cheat-sheet-education.pdf similarity index 100% rename from docs/guide/markdown/git-cheat-sheet-education.pdf rename to docs/authoring/markdown/git-cheat-sheet-education.pdf diff --git a/docs/guide/markdown/hello-badge.svg b/docs/authoring/markdown/hello-badge.svg similarity index 100% rename from docs/guide/markdown/hello-badge.svg rename to docs/authoring/markdown/hello-badge.svg diff --git a/docs/guide/markdown/pIqaD.svg b/docs/authoring/markdown/pIqaD.svg similarity index 100% rename from docs/guide/markdown/pIqaD.svg rename to docs/authoring/markdown/pIqaD.svg diff --git a/docs/tips/math.md b/docs/authoring/math.md similarity index 100% rename from docs/tips/math.md rename to docs/authoring/math.md diff --git a/docs/tips/mermaid.md b/docs/authoring/mermaid.md similarity index 100% rename from docs/tips/mermaid.md rename to docs/authoring/mermaid.md diff --git a/docs/guide/orgmode.org b/docs/authoring/orgmode.org similarity index 74% rename from docs/guide/orgmode.org rename to docs/authoring/orgmode.org index 4e303e2ea..177de5705 100644 --- a/docs/guide/orgmode.org +++ b/docs/authoring/orgmode.org @@ -15,7 +15,7 @@ Here is a handpicked selection of syntatic features of Org Mode as particularly *** Code blocks -See [[file:../tips/syntax-highlighting.md][Syntax Highlighting]] for general information. +See [[file:syntax-highlighting.md][Syntax Highlighting]] for general information. #+NAME: factorial #+BEGIN_SRC haskell :results silent :exports code :var n=0 @@ -25,7 +25,7 @@ See [[file:../tips/syntax-highlighting.md][Syntax Highlighting]] for general inf *** LaTeX -See [[file:../tips/math.md][Math]] for general information. +See [[file:math.md][Math]] for general information. The radius of the sun is R_sun = 6.96 x 10^8 m. On the other hand, the radius of Alpha Centauri is R_{Alpha Centauri} = 1.28 x R_{sun}. @@ -38,4 +38,4 @@ If $a^2=b$ and \( b=2 \), then the solution must be either $$ a=+\sqrt{2} $$ or \[ a=-\sqrt{2} \] ** Limitations -- While =#+TITLE= is recognized, most other metadata are not recognized yet. [[file:lua-filters.md][Pandoc Lua filters]] are the exception: use one =#+PANDOC_FILTERS_PARSE: path/to/filter.lua= keyword per parse-time filter, or =#+PANDOC_FILTERS_RENDER_HTML: path/to/filter.lua= per render-time HTML filter. Store other file-associated metadata in a separate [[file:yaml-config.md][YAML file]]. +- While =#+TITLE= is recognized, most other metadata are not recognized yet. [[file:../extend/lua-filters.md][Pandoc Lua filters]] are the exception: use one =#+PANDOC_FILTERS_PARSE: path/to/filter.lua= keyword per parse-time filter, or =#+PANDOC_FILTERS_RENDER_HTML: path/to/filter.lua= per render-time HTML filter. Store other file-associated metadata in a separate [[file:../config/yaml-config.md][YAML file]]. diff --git a/docs/guide/orgmode.yaml b/docs/authoring/orgmode.yaml similarity index 100% rename from docs/guide/orgmode.yaml rename to docs/authoring/orgmode.yaml diff --git a/docs/guide/query.md b/docs/authoring/query.md similarity index 100% rename from docs/guide/query.md rename to docs/authoring/query.md diff --git a/docs/tips/syntax-highlighting.md b/docs/authoring/syntax-highlighting.md similarity index 100% rename from docs/tips/syntax-highlighting.md rename to docs/authoring/syntax-highlighting.md diff --git a/docs/guide/wikilinks.md b/docs/authoring/wikilinks.md similarity index 91% rename from docs/guide/wikilinks.md rename to docs/authoring/wikilinks.md index f0381d38f..d43df547b 100644 --- a/docs/guide/wikilinks.md +++ b/docs/authoring/wikilinks.md @@ -16,7 +16,7 @@ Wiki-links [do not yet](https://github.com/srid/emanote/discussions/105) support ## Regular Markdown note links -Regular Markdown links to notes can include their `.md` or `.org` extension, but they don't have to. `[Neuron](../start/neuron)` and `[Neuron](../start/neuron.md)` both render as [Neuron](../start/neuron). Folder-note links such as `[Guide](../guide)` resolve the same way before Emanote falls back to looking for a static file at that path. +Regular Markdown links to notes can include their `.md` or `.org` extension, but they don't have to. `[Neuron](../reference/neuron)` and `[Neuron](../reference/neuron.md)` both render as [Neuron](../reference/neuron). Folder-note links such as `[Reference](../reference)` resolve the same way before Emanote falls back to looking for a static file at that path. ## Broken links diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 000000000..53ff9104a --- /dev/null +++ b/docs/config.md @@ -0,0 +1,19 @@ +--- +slug: config +order: 3 +--- + +# Configuration + +The notebook model — how notes, folders, and YAML compose. Read this section before [[theme|theming]] or writing [[extend|extensions]]; both consume the surfaces defined here. + +- **[[yaml-config]]** — site and per-note metadata, cascade rules +- **[[layer]]** — merging multiple notebook directories +- **[[emanoteignore]]** — excluding files from the notebook model +- **[[folder-note]]** — `foo.md`/`foo/index.md` semantics +- **[[folgezettel]]** — structural-link hierarchy (consumed by [[sidebar]]) +- **[[i18n]]** — internationalisation via `page.lang` + +```query +path:./* +``` diff --git a/docs/guide/emanoteignore.md b/docs/config/emanoteignore.md similarity index 100% rename from docs/guide/emanoteignore.md rename to docs/config/emanoteignore.md diff --git a/docs/guide/folder-note.md b/docs/config/folder-note.md similarity index 100% rename from docs/guide/folder-note.md rename to docs/config/folder-note.md diff --git a/docs/guide/folgezettel.md b/docs/config/folgezettel.md similarity index 100% rename from docs/guide/folgezettel.md rename to docs/config/folgezettel.md diff --git a/docs/guide/i18n.md b/docs/config/i18n.md similarity index 100% rename from docs/guide/i18n.md rename to docs/config/i18n.md diff --git a/docs/guide/i18n/i18n.fr.md b/docs/config/i18n/i18n.fr.md similarity index 97% rename from docs/guide/i18n/i18n.fr.md rename to docs/config/i18n/i18n.fr.md index 952e2649c..41d9c8cdb 100644 --- a/docs/guide/i18n/i18n.fr.md +++ b/docs/config/i18n/i18n.fr.md @@ -16,7 +16,7 @@ Cette page définit explicitement `page.lang: fr` dans sa Autres langues : -- [[guide/i18n|English]] +- [[i18n|English]] - [[i18n/i18n.zh|中文]] ## Ce qui change diff --git a/docs/guide/i18n/i18n.zh.md b/docs/config/i18n/i18n.zh.md similarity index 97% rename from docs/guide/i18n/i18n.zh.md rename to docs/config/i18n/i18n.zh.md index 1328f1a55..6e5680b94 100644 --- a/docs/guide/i18n/i18n.zh.md +++ b/docs/config/i18n/i18n.zh.md @@ -13,7 +13,7 @@ page: 其他语言： -- [[guide/i18n|English]] +- [[i18n|English]] - [[i18n/i18n.fr|Français]] ## 哪些内容会变化 diff --git a/docs/guide/layer.md b/docs/config/layer.md similarity index 100% rename from docs/guide/layer.md rename to docs/config/layer.md diff --git a/docs/guide/yaml-config.md b/docs/config/yaml-config.md similarity index 96% rename from docs/guide/yaml-config.md rename to docs/config/yaml-config.md index f8041cdb8..5dfceb9cb 100644 --- a/docs/guide/yaml-config.md +++ b/docs/config/yaml-config.md @@ -13,7 +13,7 @@ tags: [emanote/yaml/demo] Configure your site metadata, rendering configuration and such using YAML configuration. Create a `foo.yaml` alongside `foo.md` (see [[folder-note]]) or `foo/` folder, and those settings apply only to that route. The YAML structure is the same as your Markdown frontmatter, and vice-versa. Settings in the YAML frontmatter apply onto that Markdown route only; whereas settings in an individual .yaml file apply to that entire sub-route tree. Emanote does a deep-merge of the parent YAML configurations, so you can have children override only what's necessary. This is sometimes known as ["data cascade"](https://www.11ty.dev/docs/data-cascade/). The final merged YAML structure is passed to the HTML templates, of which you have full rendering control over. -Notice how this page's sidebar colorscheme has [changed to green]{.greenery}? View [the source of this page](https://github.com/srid/emanote/blob/master/docs/guide/yaml-config.md) to see the magic involved. That CSS greenery you just saw too comes from YAML. +Notice how this page's sidebar colorscheme has [changed to green]{.greenery}? View [the source of this page](https://github.com/srid/emanote/blob/master/docs/config/yaml-config.md) to see the magic involved. That CSS greenery you just saw too comes from YAML. >[!tip] Using in HTML templates > You can reference the YAML frontmatter config from [[html-template]]. See [here](https://github.com/srid/emanote/discussions/131#discussioncomment-1382189) for details. diff --git a/docs/extend.md b/docs/extend.md new file mode 100644 index 000000000..d1f5844be --- /dev/null +++ b/docs/extend.md @@ -0,0 +1,15 @@ +--- +slug: extend +order: 5 +--- + +# Extend + +Add code that hooks into Emanote's pipeline or exposes it to external clients. + +- **[[lua-filters]]** — Pandoc Lua filters at parse-time and render-time (including bundled [[diagrams]] for d2/cetz) +- **[[mcp]]** — Model Context Protocol server alongside the live server + +```query +path:./* +``` diff --git a/docs/guide/lua-filters.md b/docs/extend/lua-filters.md similarity index 100% rename from docs/guide/lua-filters.md rename to docs/extend/lua-filters.md diff --git a/docs/guide/lua-filters/diagrams.md b/docs/extend/lua-filters/diagrams.md similarity index 100% rename from docs/guide/lua-filters/diagrams.md rename to docs/extend/lua-filters/diagrams.md diff --git a/docs/guide/lua-filters/writing-filters.md b/docs/extend/lua-filters/writing-filters.md similarity index 100% rename from docs/guide/lua-filters/writing-filters.md rename to docs/extend/lua-filters/writing-filters.md diff --git a/docs/guide/lua-filters/writing-filters/slides.md b/docs/extend/lua-filters/writing-filters/slides.md similarity index 100% rename from docs/guide/lua-filters/writing-filters/slides.md rename to docs/extend/lua-filters/writing-filters/slides.md diff --git a/docs/guide/mcp.md b/docs/extend/mcp.md similarity index 98% rename from docs/guide/mcp.md rename to docs/extend/mcp.md index 04dc1ad0e..d1e7baad4 100644 --- a/docs/guide/mcp.md +++ b/docs/extend/mcp.md @@ -69,7 +69,7 @@ Emanote advertises the notebook under the `emanote://` scheme as a single static | URI | MIME | What it returns | |---|---|---| -| `emanote://export/metadata` | `application/json` | Metadata for every note — titles, source paths, parent routes, resolved links. Same shape as [`emanote export --format=metadata`](export.md). Use this to discover paths. | +| `emanote://export/metadata` | `application/json` | Metadata for every note — titles, source paths, parent routes, resolved links. Same shape as [`emanote export --format=metadata`](../authoring/export.md). Use this to discover paths. | `resources/list` returns only the metadata export. Emanote intentionally does **not** enumerate one entry per note: that scales linearly with notebook size and inflates context on every poll. Clients discover note paths from `emanote://export/metadata` (every note's `filePath`) and the query tools below; the underlying files are read through the client's own filesystem tools (e.g. Claude Code's `Read`, Codex's local file access), not through MCP. diff --git a/docs/guide.md b/docs/guide.md deleted file mode 100644 index a5eb20531..000000000 --- a/docs/guide.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -slug: guide -order: 2 ---- - -# Guide - -This guide covers Emanote's core features: - -- **[[markdown]]** — Markdown extensions: callouts, task lists, emojis, footnotes -- **[[wikilinks]]** — `[[…]]` syntax, structural links, broken / ambiguous link rendering -- **[[query]]** — Obsidian-style embed queries for dynamic content -- **[[yaml-config]]** — Site metadata and per-page configuration -- **[[lua-filters]]** — Pandoc Lua filter phases, bundled filters, and demos (including [[diagrams|inline-SVG diagrams]] from d2 and cetz) -- **[[i18n|Internationalisation]]** — English and French pages using `page.lang` -- **[[html-template]]** — Full HTML customization with Heist templates -- **[[layer]]** — Merging multiple notebook directories - -```query -path:./* -``` diff --git a/docs/reference.md b/docs/reference.md new file mode 100644 index 000000000..6262e4286 --- /dev/null +++ b/docs/reference.md @@ -0,0 +1,17 @@ +--- +slug: reference +order: 9 +--- + +# Reference + +Back-matter: migration paths, the ecosystem around Emanote, and known edge cases. + +- **[[examples]]** — Emanote sites in the wild +- **[[neuron]]** — migrating from neuron +- **[[zk]]** — running Emanote on a [zk](https://github.com/mickael-menu/zk) notebook +- **[[known-issues]]** — edge cases and workarounds + +```query +path:./* +``` diff --git a/docs/examples.md b/docs/reference/examples.md similarity index 100% rename from docs/examples.md rename to docs/reference/examples.md diff --git a/docs/start/known-issues.md b/docs/reference/known-issues.md similarity index 100% rename from docs/start/known-issues.md rename to docs/reference/known-issues.md diff --git a/docs/start/neuron.md b/docs/reference/neuron.md similarity index 100% rename from docs/start/neuron.md rename to docs/reference/neuron.md diff --git a/docs/start/resources/zk.md b/docs/reference/zk.md similarity index 100% rename from docs/start/resources/zk.md rename to docs/reference/zk.md diff --git a/docs/start.md b/docs/start.md index 87bda3784..733679b3f 100644 --- a/docs/start.md +++ b/docs/start.md @@ -11,7 +11,7 @@ Follow these steps to get started with Emanote. 1. Use your existing notebook, or create one from [[emanote-template]][^gh]. 1. Run `emanote run --port=8080` (or just `emanote`) in terminal after `cd`'ing to that notebook folder; this will launch the live server. - Or, if you only want to generate the HTML files (for deployment), run `mkdir /tmp/output; emanote gen /tmp/output`. -2. Visit [[guide]] to learn more about Emanote, or [[examples]] to get inspired first.[^h] +2. Visit [[authoring]] to learn what you can type, or [[examples]] to get inspired first.[^h] [^gh]: [[emanote-template]] also includes the GitHub Pages workflow for static site deployment. diff --git a/docs/start/resources/editors.md b/docs/start/editors.md similarity index 100% rename from docs/start/resources/editors.md rename to docs/start/editors.md diff --git a/docs/start/resources/editors/nota.md b/docs/start/editors/nota.md similarity index 100% rename from docs/start/resources/editors/nota.md rename to docs/start/editors/nota.md diff --git a/docs/start/resources/editors/obsmd.md b/docs/start/editors/obsmd.md similarity index 100% rename from docs/start/resources/editors/obsmd.md rename to docs/start/editors/obsmd.md diff --git a/docs/start/resources/editors/vim.md b/docs/start/editors/vim.md similarity index 100% rename from docs/start/resources/editors/vim.md rename to docs/start/editors/vim.md diff --git a/docs/start/resources/editors/vscode.md b/docs/start/editors/vscode.md similarity index 100% rename from docs/start/resources/editors/vscode.md rename to docs/start/editors/vscode.md diff --git a/docs/start/resources/emanote-template.md b/docs/start/emanote-template.md similarity index 100% rename from docs/start/resources/emanote-template.md rename to docs/start/emanote-template.md diff --git a/docs/start/resources.md b/docs/start/resources.md deleted file mode 100644 index 55578fa79..000000000 --- a/docs/start/resources.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -order: 15 -slug: resources ---- - -# Resources - -Applications and resources relevant to Emanote. - -```query -children:. -``` \ No newline at end of file diff --git a/docs/tips/sync.md b/docs/start/sync.md similarity index 98% rename from docs/tips/sync.md rename to docs/start/sync.md index d77a9f8fa..237dc4dbe 100644 --- a/docs/tips/sync.md +++ b/docs/start/sync.md @@ -23,5 +23,3 @@ Git also acts as backup if you push your repository to a remote location (GitHub [^sup]: "superior" ... because when using Dropbox, Android phones (unlike desktop computers) cannot have automatic full-sync of files on disk. [^ios]: Obsidian can also synchronize notes between iOS and macOS [via iCloud](https://help.obsidian.md/Getting+started/Sync+your+notes+across+devices). - -#[[resources]] diff --git a/docs/theme.md b/docs/theme.md new file mode 100644 index 000000000..087b0ea23 --- /dev/null +++ b/docs/theme.md @@ -0,0 +1,14 @@ +--- +slug: theme +order: 4 +--- + +# Theme + +Customise the generated HTML via Heist templates. This is presentation only — model behaviour belongs under [[config]], and code-level rendering hooks belong under [[extend]] ([[lua-filters]]). + +- **[[html-template]]** — overriding the default Heist templates wholesale or per-fragment + +```query +path:./* +``` diff --git a/docs/guide/html-template.md b/docs/theme/html-template.md similarity index 100% rename from docs/guide/html-template.md rename to docs/theme/html-template.md diff --git a/docs/guide/html-template/backlinks.md b/docs/theme/html-template/backlinks.md similarity index 100% rename from docs/guide/html-template/backlinks.md rename to docs/theme/html-template/backlinks.md diff --git a/docs/guide/html-template/breadcrumbs.md b/docs/theme/html-template/breadcrumbs.md similarity index 100% rename from docs/guide/html-template/breadcrumbs.md rename to docs/theme/html-template/breadcrumbs.md diff --git a/docs/guide/html-template/dark-mode.md b/docs/theme/html-template/dark-mode.md similarity index 100% rename from docs/guide/html-template/dark-mode.md rename to docs/theme/html-template/dark-mode.md diff --git a/docs/guide/html-template/external-links.md b/docs/theme/html-template/external-links.md similarity index 100% rename from docs/guide/html-template/external-links.md rename to docs/theme/html-template/external-links.md diff --git a/docs/guide/html-template/focus-mode.md b/docs/theme/html-template/focus-mode.md similarity index 100% rename from docs/guide/html-template/focus-mode.md rename to docs/theme/html-template/focus-mode.md diff --git a/docs/guide/html-template/fonts.md b/docs/theme/html-template/fonts.md similarity index 100% rename from docs/guide/html-template/fonts.md rename to docs/theme/html-template/fonts.md diff --git a/docs/guide/html-template/neuron-layout.md b/docs/theme/html-template/neuron-layout.md similarity index 100% rename from docs/guide/html-template/neuron-layout.md rename to docs/theme/html-template/neuron-layout.md diff --git a/docs/guide/html-template/ogp.md b/docs/theme/html-template/ogp.md similarity index 100% rename from docs/guide/html-template/ogp.md rename to docs/theme/html-template/ogp.md diff --git a/docs/guide/html-template/right-panel.md b/docs/theme/html-template/right-panel.md similarity index 100% rename from docs/guide/html-template/right-panel.md rename to docs/theme/html-template/right-panel.md diff --git a/docs/guide/html-template/search.md b/docs/theme/html-template/search.md similarity index 100% rename from docs/guide/html-template/search.md rename to docs/theme/html-template/search.md diff --git a/docs/guide/html-template/sidebar.md b/docs/theme/html-template/sidebar.md similarity index 100% rename from docs/guide/html-template/sidebar.md rename to docs/theme/html-template/sidebar.md diff --git a/docs/guide/html-template/toc.md b/docs/theme/html-template/toc.md similarity index 100% rename from docs/guide/html-template/toc.md rename to docs/theme/html-template/toc.md diff --git a/docs/guide/html-template/uptree.md b/docs/theme/html-template/uptree.md similarity index 100% rename from docs/guide/html-template/uptree.md rename to docs/theme/html-template/uptree.md diff --git a/docs/tips.md b/docs/tips.md deleted file mode 100644 index 9b9196b4d..000000000 --- a/docs/tips.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -order: 9 -slug: tips ---- - -# Tips - -Practical tips and recipes for common Emanote workflows. - -```query -path:./* -``` diff --git a/emanote/CHANGELOG.md b/emanote/CHANGELOG.md index 2234aac53..7ab7233da 100644 --- a/emanote/CHANGELOG.md +++ b/emanote/CHANGELOG.md @@ -25,6 +25,7 @@ - The default template now has a note focus button in the note area when collapsible side chrome is present. It expands the central note column inside the browser window by hiding the sidebar, right-panel, and bottom strip while leaving the uptree visible; the control is hidden on narrow screens and the state survives Ema live hot reloads until the user explicitly restores the layout. - Mermaid: add `elk` layout ([#618](https://github.com/srid/emanote/pull/618)) - Home Manager module: macOS support via launchd ([#623](https://github.com/srid/emanote/pull/623)) +- Docs site reorganised around reader concern: `start`, `authoring`, `config`, `theme`, `extend`, `reference`. URLs are unchanged (every page already has a slug); legacy `/guide/*`, `/tips/*`, and `/start/resources/*` paths continue to redirect. **Bug fixes** diff --git a/emanote/default/index.yaml b/emanote/default/index.yaml index c265aa5c3..acf745e6b 100644 --- a/emanote/default/index.yaml +++ b/emanote/default/index.yaml @@ -345,5 +345,5 @@ emanote: # Render `$...$` / `$$...$$` to MathML at build time via texmath (default: true). # Modern browsers render MathML natively (Firefox, Safari, Chrome >=109), so # no runtime JS is needed. Set to false to fall back to client-side JS - # (MathJax snippet, or a custom KaTeX snippet — see docs/tips/js/math). + # (MathJax snippet, or a custom KaTeX snippet — see docs/authoring/math.md). staticMath: true diff --git a/emanote/src/Emanote/Model/Note/Filter.hs b/emanote/src/Emanote/Model/Note/Filter.hs index 1ba42c07e..ddd98566d 100644 --- a/emanote/src/Emanote/Model/Note/Filter.hs +++ b/emanote/src/Emanote/Model/Note/Filter.hs @@ -305,7 +305,7 @@ parse-time sandbox lets it through. Emitted on a single physical line so a runtime/syntax error in the user's filter still reports the right line number (see the comment on 'parseTimeNoIOPrelude'). For the protocol the @error_block@ builder -implements, see @docs/guide/lua-filters/writing-filters.md@. +implements, see @docs/extend/lua-filters/writing-filters.md@. -} emanoteLuaHelpers :: Text emanoteLuaHelpers = From 2147222e75bd49e43310b0fea761b4d7499ec185 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 17:28:20 -0400 Subject: [PATCH 02/13] refactor(hickey): drop redundant path:./* queries from section folder-notes The hand-written bullet lists carry editorial one-line descriptions per child page that a query cannot; the sidebar tree already surfaces the full child set. Matches the start.md convention (bullets-only). --- docs/authoring.md | 4 ---- docs/config.md | 4 ---- docs/extend.md | 4 ---- docs/reference.md | 4 ---- docs/theme.md | 4 ---- 5 files changed, 20 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index 776ac5b81..a33eae62b 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -17,7 +17,3 @@ What you type into a note — input formats, link syntax, graph structures, rend - **[[feed]]**, **[[export]]** — frontmatter-declared outputs Cross-cutting: configuration that affects what you can type lives under [[config]] ([[yaml-config]], [[layer]]); output customisation lives under [[theme]]; code-level extension lives under [[extend]]. - -```query -path:./* -``` diff --git a/docs/config.md b/docs/config.md index 53ff9104a..6d71cfa9f 100644 --- a/docs/config.md +++ b/docs/config.md @@ -13,7 +13,3 @@ The notebook model — how notes, folders, and YAML compose. Read this section b - **[[folder-note]]** — `foo.md`/`foo/index.md` semantics - **[[folgezettel]]** — structural-link hierarchy (consumed by [[sidebar]]) - **[[i18n]]** — internationalisation via `page.lang` - -```query -path:./* -``` diff --git a/docs/extend.md b/docs/extend.md index d1f5844be..2f2caaede 100644 --- a/docs/extend.md +++ b/docs/extend.md @@ -9,7 +9,3 @@ Add code that hooks into Emanote's pipeline or exposes it to external clients. - **[[lua-filters]]** — Pandoc Lua filters at parse-time and render-time (including bundled [[diagrams]] for d2/cetz) - **[[mcp]]** — Model Context Protocol server alongside the live server - -```query -path:./* -``` diff --git a/docs/reference.md b/docs/reference.md index 6262e4286..0f5d50a06 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -11,7 +11,3 @@ Back-matter: migration paths, the ecosystem around Emanote, and known edge cases - **[[neuron]]** — migrating from neuron - **[[zk]]** — running Emanote on a [zk](https://github.com/mickael-menu/zk) notebook - **[[known-issues]]** — edge cases and workarounds - -```query -path:./* -``` diff --git a/docs/theme.md b/docs/theme.md index 087b0ea23..9a6eeec76 100644 --- a/docs/theme.md +++ b/docs/theme.md @@ -8,7 +8,3 @@ order: 4 Customise the generated HTML via Heist templates. This is presentation only — model behaviour belongs under [[config]], and code-level rendering hooks belong under [[extend]] ([[lua-filters]]). - **[[html-template]]** — overriding the default Heist templates wholesale or per-fragment - -```query -path:./* -``` From 0f0164dac5a42d43e69b65b9e7e8518db745ec90 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 17:28:31 -0400 Subject: [PATCH 03/13] refactor(hickey): differentiate folgezettel description across the two hubs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The folgezettel page legitimately spans two concerns — the wikilink syntax authors type, and the YAML toggle that builds the tree. Listing it from both hubs is correct, but the descriptions were near-identical; they now each name the facet that belongs to their hub. --- docs/authoring.md | 2 +- docs/config.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/authoring.md b/docs/authoring.md index a33eae62b..acd1243ad 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -10,7 +10,7 @@ What you type into a note — input formats, link syntax, graph structures, rend - **[[markdown]]** — extensions on top of CommonMark: callouts, task lists, emojis, footnotes, footers - **[[wikilinks]]** — `[[…]]` syntax, structural links, broken / ambiguous link rendering - **[[query]]** — Obsidian-style embed queries for dynamic listings -- **[[folgezettel]]** — structural wikilinks that drive [[sidebar]] hierarchy +- **[[folgezettel]]** — the `#[[…]]` wikilink form that declares parent/child structure - **[[daily-notes]]** — date-stamped notes - **[[orgmode]]** — Org-mode notes alongside Markdown - **[[math]]**, **[[mermaid]]**, **[[syntax-highlighting]]**, **[[adding-images]]** — built-in render features the author types directly diff --git a/docs/config.md b/docs/config.md index 6d71cfa9f..ae63588e9 100644 --- a/docs/config.md +++ b/docs/config.md @@ -11,5 +11,5 @@ The notebook model — how notes, folders, and YAML compose. Read this section b - **[[layer]]** — merging multiple notebook directories - **[[emanoteignore]]** — excluding files from the notebook model - **[[folder-note]]** — `foo.md`/`foo/index.md` semantics -- **[[folgezettel]]** — structural-link hierarchy (consumed by [[sidebar]]) +- **[[folgezettel]]** — `folder-folgezettel:` YAML toggle and the parent/child tree it builds for [[sidebar]] and [[uptree]] - **[[i18n]]** — internationalisation via `page.lang` From b1c2998853424c7153b3cceef9fabd70f77261fe Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 17:29:13 -0400 Subject: [PATCH 04/13] refactor(lowy): regenerate .claude/rules/emanote-docs.md to drop stale guide.md reference apm install was not re-run after the .apm/ source edit, leaving the generated .claude/ copy pointing at docs/guide.md (deleted in this PR). Future /do sessions read the generated rule, not the source. --- .claude/rules/emanote-docs.md | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/.claude/rules/emanote-docs.md b/.claude/rules/emanote-docs.md index 69234def1..91f0681dc 100644 --- a/.claude/rules/emanote-docs.md +++ b/.claude/rules/emanote-docs.md @@ -9,7 +9,7 @@ When adding a new documentation page under `docs/`, give it an explicit simple ` ## Wikilink internal references -Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant guide page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference. +Connect docs pages to surrounding documentation with **wikilinks**, both when creating a new page and when editing existing ones. Link to the nearest relevant docs page — `[[yaml-config]]`, `[[html-template]]`, `[[wikilinks]]`, `[[layer]]`, etc. — instead of repeating concepts inline or leaving the page as an isolated note. Prefer wikilinks over raw relative Markdown links for any internal docs reference. When you add prose that mentions another concept covered by an existing page, replace the bare phrase with a wikilink — e.g. write `… see [[html-template]] for the override mechanism …` rather than restating it. If no page covers the concept yet, this is a signal to consider promoting it to a dedicated page (see below) rather than burying the explanation inside an unrelated guide. @@ -21,4 +21,17 @@ A section under one guide page should be **promoted to its own page** once any o - It carries reference material — splice tables, override protocols, configuration surfaces — that other pages need to wikilink to. - It documents a feature with its own slug-worthy concept name (`wikilinks`, `callout`, `folgezettel`, etc.). -Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to `docs/guide.md`'s top-level list. Inbound links from other docs pages should point at the dedicated page. +Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to the relevant section folder-note (`docs/authoring/authoring.md`, `docs/config/config.md`, `docs/theme/theme.md`, `docs/extend/extend.md`, `docs/reference/reference.md`, or `docs/start/start.md`). Inbound links from other docs pages should point at the dedicated page. + +## Section layout + +`docs/` is organised into six top-level sections, each driven by a reader concern: + +- `start/` — install, editor setup, deploying. +- `authoring/` — input formats, link syntax, graph structures, render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export). +- `config/` — notebook model: `yaml-config`, `layer`, `emanoteignore`, `folder-note`, `folgezettel`, `i18n`. +- `theme/` — HTML/Heist template customisation (`html-template` and its sub-pages only). +- `extend/` — code-level extension: Pandoc Lua filters, MCP server. +- `reference/` — migration (`neuron`), ecosystem (`zk`, `examples`), edge cases (`known-issues`). + +Place new pages in the section whose reader concern they match; cross-link via wikilinks rather than reorganising. The folder structure drives the sidebar tree; the page slug determines the public URL (see the slug rule above). From 887ad7451fa4f88ae579e4d29c0532d71550b801 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 17:29:26 -0400 Subject: [PATCH 05/13] refactor(lowy): add missing _redirects for four guide/html-template/ sub-pages backlinks, dark-mode, focus-mode, and right-panel were absent from the prior _redirects coverage of /guide/html-template/*. Slug-based URLs were fine, but the legacy nested paths 404'd; symmetry restored. --- docs/_redirects | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/_redirects b/docs/_redirects index c00fd3987..a8bfea965 100644 --- a/docs/_redirects +++ b/docs/_redirects @@ -24,6 +24,10 @@ /guide/html-template/breadcrumbs /breadcrumbs 301 /guide/html-template/toc /toc 301 /guide/html-template/ogp /ogp 301 +/guide/html-template/backlinks /backlinks 301 +/guide/html-template/dark-mode /dark-mode 301 +/guide/html-template/focus-mode /focus-mode 301 +/guide/html-template/right-panel /right-panel 301 # Markdown features /guide/markdown/custom-style /custom-style 301 From 839d9198c19af1ab7cfc8b2b8a858f04359dbb59 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 17:29:43 -0400 Subject: [PATCH 06/13] refactor(lowy): update stale docs path in hello.lua comment This bundled filter ships in the default layer; the docstring referenced the retired docs/guide/lua-filters/ path. The Haddock comment in Filter.hs was updated in the primary commit; this one was missed. --- emanote/default/lua-filters/hello.lua | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/emanote/default/lua-filters/hello.lua b/emanote/default/lua-filters/hello.lua index ea474bc2e..6d3837b10 100644 --- a/emanote/default/lua-filters/hello.lua +++ b/emanote/default/lua-filters/hello.lua @@ -2,7 +2,7 @@ -- -- Handles `hello` fenced code blocks and demonstrates Emanote's -- in-place error protocol via the injected `emanote.error_block` --- helper (see `docs/guide/lua-filters/writing-filters.md`). +-- helper (see `docs/extend/lua-filters/writing-filters.md`). -- -- Happy path -> a greeting; sad path -> a protocol-shaped error block -- that (a) shows inline as a red banner on the live server, and From eefac31d1cf1d92d0187220539b4e1b263f8b1bc Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 18:55:37 -0400 Subject: [PATCH 07/13] docs: cross-list folder-note in authoring (mirroring folgezettel pattern) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The author decides to place foo.md alongside foo/ — that's authoring surface. The notebook-model semantics (how Emanote treats the pair) remain documented in config. Same dual-hub shape as folgezettel. --- docs/authoring.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/authoring.md b/docs/authoring.md index acd1243ad..f7bd91991 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -10,6 +10,7 @@ What you type into a note — input formats, link syntax, graph structures, rend - **[[markdown]]** — extensions on top of CommonMark: callouts, task lists, emojis, footnotes, footers - **[[wikilinks]]** — `[[…]]` syntax, structural links, broken / ambiguous link rendering - **[[query]]** — Obsidian-style embed queries for dynamic listings +- **[[folder-note]]** — placing `foo.md` next to `foo/` (or `foo/index.md`) to give a folder its own page - **[[folgezettel]]** — the `#[[…]]` wikilink form that declares parent/child structure - **[[daily-notes]]** — date-stamped notes - **[[orgmode]]** — Org-mode notes alongside Markdown From 43bf6aa0f253cf319f61ca84734341ed53725e0a Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 20:00:53 -0400 Subject: [PATCH 08/13] docs: move sync (Syncthing) from start/ to reference/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Syncthing sync isn't onboarding — it's a third-party-tool recipe, same shape as zk. The slug 'sync' is unchanged, so the URL /sync and the _redirects entries continue to work. --- docs/reference.md | 1 + docs/{start => reference}/sync.md | 0 2 files changed, 1 insertion(+) rename docs/{start => reference}/sync.md (100%) diff --git a/docs/reference.md b/docs/reference.md index 0f5d50a06..b4a5e82ba 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -10,4 +10,5 @@ Back-matter: migration paths, the ecosystem around Emanote, and known edge cases - **[[examples]]** — Emanote sites in the wild - **[[neuron]]** — migrating from neuron - **[[zk]]** — running Emanote on a [zk](https://github.com/mickael-menu/zk) notebook +- **[[sync]]** — syncing your notebook across devices with Syncthing - **[[known-issues]]** — edge cases and workarounds diff --git a/docs/start/sync.md b/docs/reference/sync.md similarity index 100% rename from docs/start/sync.md rename to docs/reference/sync.md From a06ea40c1032e1191a2719858a32377056ca860b Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 20:01:26 -0400 Subject: [PATCH 09/13] docs: order start/ siblings as install -> template -> editors editors lands at the bottom (order: 3); emanote-template gets an explicit order: 2 so the three sidebar siblings have a stable progression. --- docs/start/editors.md | 2 +- docs/start/emanote-template.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/start/editors.md b/docs/start/editors.md index 2b0db3e12..6b71fe1f7 100644 --- a/docs/start/editors.md +++ b/docs/start/editors.md @@ -1,5 +1,5 @@ --- -order: 0 +order: 3 slug: editors --- diff --git a/docs/start/emanote-template.md b/docs/start/emanote-template.md index d681f5958..46b97f2d1 100644 --- a/docs/start/emanote-template.md +++ b/docs/start/emanote-template.md @@ -1,5 +1,6 @@ --- slug: emanote-template +order: 2 --- # emanote-template From c401b59e2dfc42e030257b744b79fcc190a54aad Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 20:04:38 -0400 Subject: [PATCH 10/13] docs: add external-tools section; move folder-note + folgezettel into authoring MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The user-facing structure is now seven sections, not six: - start/ — install + emanote-template - authoring/ — gains folder-note and folgezettel (notebook-model semantics that flow from authoring choices); keeps markdown, wikilinks, query, daily-notes, orgmode, math/mermaid/syntax-highlighting/adding-images, feed, export - config/ — narrowed to the YAML/layer/ignore/i18n surface - theme/ — unchanged (html-template + sub-pages) - extend/ — unchanged (lua-filters, mcp) - external-tools/ — NEW: editors, sync (Syncthing), zk (third-party tools that integrate with Emanote) - reference/ — examples, neuron migration, known-issues (no longer carries sync/zk; those moved to external-tools) URLs unchanged; all moved pages keep their flat slug, so /editors, /sync, /zk, /folder-note, /folgezettel still resolve. APM source and generated AGENTS.md updated; the .claude/ rules now describe the seven-section layout. --- .apm/instructions/emanote-docs.instructions.md | 13 +++++++------ .claude/rules/emanote-docs.md | 13 +++++++------ docs/AGENTS.md | 15 ++++++++------- docs/authoring.md | 2 +- docs/{config => authoring}/folder-note.md | 0 docs/{config => authoring}/folgezettel.md | 0 docs/config.md | 6 +++--- docs/external-tools.md | 12 ++++++++++++ docs/{start => external-tools}/editors.md | 0 docs/{start => external-tools}/editors/nota.md | 0 docs/{start => external-tools}/editors/obsmd.md | 0 docs/{start => external-tools}/editors/vim.md | 0 docs/{start => external-tools}/editors/vscode.md | 0 docs/{reference => external-tools}/sync.md | 0 docs/{reference => external-tools}/zk.md | 0 docs/reference.md | 4 ++-- 16 files changed, 40 insertions(+), 25 deletions(-) rename docs/{config => authoring}/folder-note.md (100%) rename docs/{config => authoring}/folgezettel.md (100%) create mode 100644 docs/external-tools.md rename docs/{start => external-tools}/editors.md (100%) rename docs/{start => external-tools}/editors/nota.md (100%) rename docs/{start => external-tools}/editors/obsmd.md (100%) rename docs/{start => external-tools}/editors/vim.md (100%) rename docs/{start => external-tools}/editors/vscode.md (100%) rename docs/{reference => external-tools}/sync.md (100%) rename docs/{reference => external-tools}/zk.md (100%) diff --git a/.apm/instructions/emanote-docs.instructions.md b/.apm/instructions/emanote-docs.instructions.md index 2a62c6272..f9c6c3352 100644 --- a/.apm/instructions/emanote-docs.instructions.md +++ b/.apm/instructions/emanote-docs.instructions.md @@ -21,17 +21,18 @@ A section under one guide page should be **promoted to its own page** once any o - It carries reference material — splice tables, override protocols, configuration surfaces — that other pages need to wikilink to. - It documents a feature with its own slug-worthy concept name (`wikilinks`, `callout`, `folgezettel`, etc.). -Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to the relevant section folder-note (`docs/authoring/authoring.md`, `docs/config/config.md`, `docs/theme/theme.md`, `docs/extend/extend.md`, `docs/reference/reference.md`, or `docs/start/start.md`). Inbound links from other docs pages should point at the dedicated page. +Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to the relevant section folder-note (`docs/start.md`, `docs/authoring.md`, `docs/config.md`, `docs/theme.md`, `docs/extend.md`, `docs/external-tools.md`, or `docs/reference.md`). Inbound links from other docs pages should point at the dedicated page. ## Section layout -`docs/` is organised into six top-level sections, each driven by a reader concern: +`docs/` is organised into seven top-level sections, each driven by a reader concern: -- `start/` — install, editor setup, deploying. -- `authoring/` — input formats, link syntax, graph structures, render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export). -- `config/` — notebook model: `yaml-config`, `layer`, `emanoteignore`, `folder-note`, `folgezettel`, `i18n`. +- `start/` — install + emanote-template. +- `authoring/` — input formats, link syntax, graph structures (folder notes, folgezettel), render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export). +- `config/` — configuration surface: `yaml-config`, `layer`, `emanoteignore`, `i18n`. - `theme/` — HTML/Heist template customisation (`html-template` and its sub-pages only). - `extend/` — code-level extension: Pandoc Lua filters, MCP server. -- `reference/` — migration (`neuron`), ecosystem (`zk`, `examples`), edge cases (`known-issues`). +- `external-tools/` — third-party tools that integrate with Emanote: editors (vim, vscode, obsidian, nota), Syncthing sync, zk. +- `reference/` — migration (`neuron`), examples, edge cases (`known-issues`). Place new pages in the section whose reader concern they match; cross-link via wikilinks rather than reorganising. The folder structure drives the sidebar tree; the page slug determines the public URL (see the slug rule above). diff --git a/.claude/rules/emanote-docs.md b/.claude/rules/emanote-docs.md index 91f0681dc..019b7d8d5 100644 --- a/.claude/rules/emanote-docs.md +++ b/.claude/rules/emanote-docs.md @@ -21,17 +21,18 @@ A section under one guide page should be **promoted to its own page** once any o - It carries reference material — splice tables, override protocols, configuration surfaces — that other pages need to wikilink to. - It documents a feature with its own slug-worthy concept name (`wikilinks`, `callout`, `folgezettel`, etc.). -Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to the relevant section folder-note (`docs/authoring/authoring.md`, `docs/config/config.md`, `docs/theme/theme.md`, `docs/extend/extend.md`, `docs/reference/reference.md`, or `docs/start/start.md`). Inbound links from other docs pages should point at the dedicated page. +Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to the relevant section folder-note (`docs/start.md`, `docs/authoring.md`, `docs/config.md`, `docs/theme.md`, `docs/extend.md`, `docs/external-tools.md`, or `docs/reference.md`). Inbound links from other docs pages should point at the dedicated page. ## Section layout -`docs/` is organised into six top-level sections, each driven by a reader concern: +`docs/` is organised into seven top-level sections, each driven by a reader concern: -- `start/` — install, editor setup, deploying. -- `authoring/` — input formats, link syntax, graph structures, render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export). -- `config/` — notebook model: `yaml-config`, `layer`, `emanoteignore`, `folder-note`, `folgezettel`, `i18n`. +- `start/` — install + emanote-template. +- `authoring/` — input formats, link syntax, graph structures (folder notes, folgezettel), render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export). +- `config/` — configuration surface: `yaml-config`, `layer`, `emanoteignore`, `i18n`. - `theme/` — HTML/Heist template customisation (`html-template` and its sub-pages only). - `extend/` — code-level extension: Pandoc Lua filters, MCP server. -- `reference/` — migration (`neuron`), ecosystem (`zk`, `examples`), edge cases (`known-issues`). +- `external-tools/` — third-party tools that integrate with Emanote: editors (vim, vscode, obsidian, nota), Syncthing sync, zk. +- `reference/` — migration (`neuron`), examples, edge cases (`known-issues`). Place new pages in the section whose reader concern they match; cross-link via wikilinks rather than reorganising. The folder structure drives the sidebar tree; the page slug determines the public URL (see the slug rule above). diff --git a/docs/AGENTS.md b/docs/AGENTS.md index 050e017fe..d34b4aec4 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md - + @@ -25,18 +25,19 @@ A section under one guide page should be **promoted to its own page** once any o - It carries reference material — splice tables, override protocols, configuration surfaces — that other pages need to wikilink to. - It documents a feature with its own slug-worthy concept name (`wikilinks`, `callout`, `folgezettel`, etc.). -Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to the relevant section folder-note (`docs/authoring/authoring.md`, `docs/config/config.md`, `docs/theme/theme.md`, `docs/extend/extend.md`, `docs/reference/reference.md`, or `docs/start/start.md`). Inbound links from other docs pages should point at the dedicated page. +Move the content to a new file with a stable slug, replace the original section with a one-paragraph pointer plus a `[[]]` wikilink, and add the new page to the relevant section folder-note (`docs/start.md`, `docs/authoring.md`, `docs/config.md`, `docs/theme.md`, `docs/extend.md`, `docs/external-tools.md`, or `docs/reference.md`). Inbound links from other docs pages should point at the dedicated page. ## Section layout -`docs/` is organised into six top-level sections, each driven by a reader concern: +`docs/` is organised into seven top-level sections, each driven by a reader concern: -- `start/` — install, editor setup, deploying. -- `authoring/` — input formats, link syntax, graph structures, render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export). -- `config/` — notebook model: `yaml-config`, `layer`, `emanoteignore`, `folder-note`, `folgezettel`, `i18n`. +- `start/` — install + emanote-template. +- `authoring/` — input formats, link syntax, graph structures (folder notes, folgezettel), render features the author types (math, mermaid, syntax-highlighting, images), frontmatter-declared outputs (feed, export). +- `config/` — configuration surface: `yaml-config`, `layer`, `emanoteignore`, `i18n`. - `theme/` — HTML/Heist template customisation (`html-template` and its sub-pages only). - `extend/` — code-level extension: Pandoc Lua filters, MCP server. -- `reference/` — migration (`neuron`), ecosystem (`zk`, `examples`), edge cases (`known-issues`). +- `external-tools/` — third-party tools that integrate with Emanote: editors (vim, vscode, obsidian, nota), Syncthing sync, zk. +- `reference/` — migration (`neuron`), examples, edge cases (`known-issues`). Place new pages in the section whose reader concern they match; cross-link via wikilinks rather than reorganising. The folder structure drives the sidebar tree; the page slug determines the public URL (see the slug rule above). diff --git a/docs/authoring.md b/docs/authoring.md index f7bd91991..a3e49b027 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -11,7 +11,7 @@ What you type into a note — input formats, link syntax, graph structures, rend - **[[wikilinks]]** — `[[…]]` syntax, structural links, broken / ambiguous link rendering - **[[query]]** — Obsidian-style embed queries for dynamic listings - **[[folder-note]]** — placing `foo.md` next to `foo/` (or `foo/index.md`) to give a folder its own page -- **[[folgezettel]]** — the `#[[…]]` wikilink form that declares parent/child structure +- **[[folgezettel]]** — `#[[…]]` wikilinks (and the `folder-folgezettel:` flag) that declare parent/child structure - **[[daily-notes]]** — date-stamped notes - **[[orgmode]]** — Org-mode notes alongside Markdown - **[[math]]**, **[[mermaid]]**, **[[syntax-highlighting]]**, **[[adding-images]]** — built-in render features the author types directly diff --git a/docs/config/folder-note.md b/docs/authoring/folder-note.md similarity index 100% rename from docs/config/folder-note.md rename to docs/authoring/folder-note.md diff --git a/docs/config/folgezettel.md b/docs/authoring/folgezettel.md similarity index 100% rename from docs/config/folgezettel.md rename to docs/authoring/folgezettel.md diff --git a/docs/config.md b/docs/config.md index ae63588e9..13655580e 100644 --- a/docs/config.md +++ b/docs/config.md @@ -5,11 +5,11 @@ order: 3 # Configuration -The notebook model — how notes, folders, and YAML compose. Read this section before [[theme|theming]] or writing [[extend|extensions]]; both consume the surfaces defined here. +The configuration surface — YAML files, layer mounts, ignore patterns, language toggles. Read this section before [[theme|theming]] or writing [[extend|extensions]]; both consume the surfaces defined here. - **[[yaml-config]]** — site and per-note metadata, cascade rules - **[[layer]]** — merging multiple notebook directories - **[[emanoteignore]]** — excluding files from the notebook model -- **[[folder-note]]** — `foo.md`/`foo/index.md` semantics -- **[[folgezettel]]** — `folder-folgezettel:` YAML toggle and the parent/child tree it builds for [[sidebar]] and [[uptree]] - **[[i18n]]** — internationalisation via `page.lang` + +Notebook-model semantics that flow from authoring choices (folder notes, structural wikilinks) live under [[authoring]]. diff --git a/docs/external-tools.md b/docs/external-tools.md new file mode 100644 index 000000000..df5466b05 --- /dev/null +++ b/docs/external-tools.md @@ -0,0 +1,12 @@ +--- +slug: external-tools +order: 8 +--- + +# External tools + +Third-party tools that talk to your Emanote notebook — editors that author it, sync engines that replicate it, alternative notebook formats Emanote can read. + +- **[[editors]]** — Vim, VS Code, Obsidian, Nota integrations +- **[[sync]]** — syncing notes across devices with Syncthing +- **[[zk]]** — running Emanote on a [zk](https://github.com/mickael-menu/zk) notebook diff --git a/docs/start/editors.md b/docs/external-tools/editors.md similarity index 100% rename from docs/start/editors.md rename to docs/external-tools/editors.md diff --git a/docs/start/editors/nota.md b/docs/external-tools/editors/nota.md similarity index 100% rename from docs/start/editors/nota.md rename to docs/external-tools/editors/nota.md diff --git a/docs/start/editors/obsmd.md b/docs/external-tools/editors/obsmd.md similarity index 100% rename from docs/start/editors/obsmd.md rename to docs/external-tools/editors/obsmd.md diff --git a/docs/start/editors/vim.md b/docs/external-tools/editors/vim.md similarity index 100% rename from docs/start/editors/vim.md rename to docs/external-tools/editors/vim.md diff --git a/docs/start/editors/vscode.md b/docs/external-tools/editors/vscode.md similarity index 100% rename from docs/start/editors/vscode.md rename to docs/external-tools/editors/vscode.md diff --git a/docs/reference/sync.md b/docs/external-tools/sync.md similarity index 100% rename from docs/reference/sync.md rename to docs/external-tools/sync.md diff --git a/docs/reference/zk.md b/docs/external-tools/zk.md similarity index 100% rename from docs/reference/zk.md rename to docs/external-tools/zk.md diff --git a/docs/reference.md b/docs/reference.md index b4a5e82ba..8f4d02888 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -9,6 +9,6 @@ Back-matter: migration paths, the ecosystem around Emanote, and known edge cases - **[[examples]]** — Emanote sites in the wild - **[[neuron]]** — migrating from neuron -- **[[zk]]** — running Emanote on a [zk](https://github.com/mickael-menu/zk) notebook -- **[[sync]]** — syncing your notebook across devices with Syncthing - **[[known-issues]]** — edge cases and workarounds + +For third-party tools that integrate with Emanote (editors, sync, alternative formats), see [[external-tools]]. From a39512d38b6698c0d47bdc1299977e82a8b28217 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 20:07:19 -0400 Subject: [PATCH 11/13] docs: group folgezettel and folder-note under wikilinks/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Both pages are wikilink-shaped concerns: - folgezettel is the #[[…]] wikilink form - folder notes are wikilink resolution targets (foo.md + foo/) Nesting them under wikilinks/ in the sidebar reflects the conceptual hierarchy. Slugs unchanged so /folgezettel and /folder-note still resolve. wikilinks.md gains a 'Folder notes' section paragraph to mirror the existing 'Structural links' (folgezettel) reference. --- docs/authoring.md | 6 +++--- docs/authoring/wikilinks.md | 4 ++++ docs/authoring/{ => wikilinks}/folder-note.md | 0 docs/authoring/{ => wikilinks}/folgezettel.md | 0 4 files changed, 7 insertions(+), 3 deletions(-) rename docs/authoring/{ => wikilinks}/folder-note.md (100%) rename docs/authoring/{ => wikilinks}/folgezettel.md (100%) diff --git a/docs/authoring.md b/docs/authoring.md index a3e49b027..dc2397674 100644 --- a/docs/authoring.md +++ b/docs/authoring.md @@ -8,10 +8,10 @@ order: 2 What you type into a note — input formats, link syntax, graph structures, render features that an author reaches for from a Markdown buffer. - **[[markdown]]** — extensions on top of CommonMark: callouts, task lists, emojis, footnotes, footers -- **[[wikilinks]]** — `[[…]]` syntax, structural links, broken / ambiguous link rendering +- **[[wikilinks]]** — `[[…]]` syntax, broken / ambiguous link rendering, plus the structural variants that build the sidebar tree + - **[[folgezettel]]** — `#[[…]]` wikilinks (and the `folder-folgezettel:` flag) that declare parent/child structure + - **[[folder-note]]** — placing `foo.md` next to `foo/` (or `foo/index.md`) so a folder is itself a wikilink target - **[[query]]** — Obsidian-style embed queries for dynamic listings -- **[[folder-note]]** — placing `foo.md` next to `foo/` (or `foo/index.md`) to give a folder its own page -- **[[folgezettel]]** — `#[[…]]` wikilinks (and the `folder-folgezettel:` flag) that declare parent/child structure - **[[daily-notes]]** — date-stamped notes - **[[orgmode]]** — Org-mode notes alongside Markdown - **[[math]]**, **[[mermaid]]**, **[[syntax-highlighting]]**, **[[adding-images]]** — built-in render features the author types directly diff --git a/docs/authoring/wikilinks.md b/docs/authoring/wikilinks.md index d43df547b..b12200b53 100644 --- a/docs/authoring/wikilinks.md +++ b/docs/authoring/wikilinks.md @@ -10,6 +10,10 @@ You can link to a note by placing the filename (without extension) inside double See [[folgezettel]] for the special wiki-link form used to declare the [[sidebar]] (and [[uptree]]) hierarchy. +## Folder notes + +A wiki-link can resolve to a [[folder-note|folder note]] — a `foo.md` placed next to a `foo/` directory (or `foo/index.md` inside it) — so `[[guide]]` links to the page that represents the whole folder. + ## Anchors Wiki-links [do not yet](https://github.com/srid/emanote/discussions/105) support anchor links. Regular Markdown links do — for example, [example link](./markdown.md#lists). diff --git a/docs/authoring/folder-note.md b/docs/authoring/wikilinks/folder-note.md similarity index 100% rename from docs/authoring/folder-note.md rename to docs/authoring/wikilinks/folder-note.md diff --git a/docs/authoring/folgezettel.md b/docs/authoring/wikilinks/folgezettel.md similarity index 100% rename from docs/authoring/folgezettel.md rename to docs/authoring/wikilinks/folgezettel.md From b9f244bd160f57c2508ca12370fa34593b23b784 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 20:08:15 -0400 Subject: [PATCH 12/13] docs: surface neuron-layout in the theme folder-note MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit neuron-layout is a built-in theme preset (toggles sidebar/uptree/ breadcrumbs/toc) — a concrete entry point for the 'I want the Neuron look' question that the theme section ought to answer up front rather than burying inside html-template. --- docs/theme.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/theme.md b/docs/theme.md index 9a6eeec76..870f80888 100644 --- a/docs/theme.md +++ b/docs/theme.md @@ -8,3 +8,4 @@ order: 4 Customise the generated HTML via Heist templates. This is presentation only — model behaviour belongs under [[config]], and code-level rendering hooks belong under [[extend]] ([[lua-filters]]). - **[[html-template]]** — overriding the default Heist templates wholesale or per-fragment +- **[[neuron-layout]]** — built-in preset that toggles [[sidebar]] / [[uptree]] / [[breadcrumbs]] / [[toc]] to mimic the Neuron look From 41a22017dde9ef044171c9901e2b6210ea226097 Mon Sep 17 00:00:00 2001 From: Sridhar Ratnakumar Date: Tue, 26 May 2026 20:09:42 -0400 Subject: [PATCH 13/13] docs: complete the post-install pointers in start.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The closing 'visit Authoring or Examples' sentence still reflected the pre-reorg two-section world. Replace with a six-bullet next-steps list covering all post-install destinations — authoring, config, theme, extend, external-tools, examples — so a reader landing on the install page can see where each concern lives. --- docs/start.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/start.md b/docs/start.md index 733679b3f..53c96fca6 100644 --- a/docs/start.md +++ b/docs/start.md @@ -11,8 +11,14 @@ Follow these steps to get started with Emanote. 1. Use your existing notebook, or create one from [[emanote-template]][^gh]. 1. Run `emanote run --port=8080` (or just `emanote`) in terminal after `cd`'ing to that notebook folder; this will launch the live server. - Or, if you only want to generate the HTML files (for deployment), run `mkdir /tmp/output; emanote gen /tmp/output`. -2. Visit [[authoring]] to learn what you can type, or [[examples]] to get inspired first.[^h] +2. From there:[^h] + - **[[authoring]]** — what you can type into a note + - **[[config]]** — `yaml-config`, layers, `.emanoteignore`, i18n + - **[[theme]]** — customise the HTML output, [[neuron-layout|Neuron-like layout]] + - **[[extend]]** — Pandoc Lua filters, the MCP server + - **[[external-tools]]** — set up your [[editors|editor]], sync with [[sync|Syncthing]] + - **[[examples]]** — Emanote sites in the wild, for inspiration [^gh]: [[emanote-template]] also includes the GitHub Pages workflow for static site deployment. -[^h]: If you are [Haskell](https://srid.ca/haskell) developer, see [[architecture]]. \ No newline at end of file +[^h]: If you are a [Haskell](https://srid.ca/haskell) developer, see [[architecture]]. \ No newline at end of file