Decouple several core functionality as plugins

.github/workflows/publish.yaml

@@ -19,11 +19,11 @@ jobs:
       - name: Build neuron site 🔧
         run: |
           neuron --version
-          neuron -d guide/ gen
+          neuron -d doc/ gen
       - name: Deploy to GitHub Pages 🚀
         uses: JamesIves/[email protected]
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           BRANCH: gh-pages
-          FOLDER: guide/.neuron/output
+          FOLDER: doc/.neuron/output
           CLEAN: true

CHANGELOG.md

@@ -2,12 +2,16 @@
 
 ## Unreleased (v2)
 
-- Introducing *impulse* -- foundation for upcoming advanced search, replacing both z-index and legacy JS search (#108)
+- Web interface
+  - Introducing *impulse* -- foundation for upcoming advanced search, replacing both z-index and legacy JS search (#108)
+  - Remove autoscroll behaviour (which had questionable value to begin with)
 - Remove (experimental) support for org-mode in v2 (use `v1` branch if you need org-mode)
 - Plugin support
   - dirtree: Treat directories as zettels, forming automatic folgezettel connections to their children. (#497)
   - neuronignore: Exclude directories and markdown files via `.neuronignore`. (#499)
     - By default, recursively read Markdown files in notes directory. This behaviour can be disabled via the neuronignore plugin.
+  - link queries & tags are now plugins
+- Change default slug to use all lower-case (#527)
 - Reduce error verbosity (CLI & web) in the scenario of there being innumerous broken wiki-links.
 - CLI
   - `neuron rib` is renamed to `neuron gen` (neuron has migrated from rib/shake to reflex)

CONTRIBUTING.md

@@ -16,7 +16,7 @@ Note that if you are developing on project *impulse*, you must open the `./impul
 When modifying the source code, use `bin/run` (which uses ghcid) to test your changes in real-time:
 
 ```bash
-bin/run -d $(pwd)/guide gen -wS
+bin/run -d $(pwd)/doc gen -wS
 ```
 
 This command automatically recompiles and restarts when you change any of the Haskell source files. Furthermore, this command runs site generation on the given Zettelkasten. You can pass the same neuron arguments to `bin/run`. This is essentially equivalent to running a development version of neuron with instant reload.

README.md

@@ -17,14 +17,7 @@ neuron is a **future-proof** command-line app for managing your plain-text [Zett
 
 ## Getting started
 
-See [neuron.zettel.page](https://neuron.zettel.page/) for the full guide to installing and using neuron.
-
-## Discussion
-
-To share your thoughts and ask questions on neuron, you may join one of the following:
-
-- Forum: [GitHub Discussions](https://github.com/srid/neuron/discussions)
-- Chat: [Matrix room Neuron](https://app.element.io/#/room/#neuron:matrix.org)
+See [neuron.zettel.page](https://neuron.zettel.page/) for the full guide to installing and using neuron, as well as for other resources.
 
 ## Developing
 

bin/repl

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+set -xe
+nix-shell  --run 'cabal new-repl neuron:lib:neuron'

dep/commonmark/github.json

@@ -0,0 +1,8 @@
+{
+  "owner": "jgm",
+  "repo": "commonmark-hs",
+  "branch": "master",
+  "private": false,
+  "rev": "87a3ab30c141b4233ba30752b716d6d5ddf99603",
+  "sha256": "0bfslxn1dhsbac2dinlrvkgrdqj4q3cc6r1clkpxv6d0pnmz24d6"
+}

dep/pandoc-link-context/github.json

@@ -3,6 +3,6 @@
   "repo": "pandoc-link-context",
   "branch": "master",
   "private": false,
-  "rev": "789d3fe2692722da7e0337f76fe5c3376710154b",
-  "sha256": "0ds8dkp23blv4jqwhgkgdzpchsq6q6mg8qsdy8v2xm423dimr3vq"
+  "rev": "f832096662f60e9e4c344547e94217b821ea9dfb",
+  "sha256": "06ii1w302dbiv2ssmbqrjvc29qnq0x79xqra4cdl36hmkdhiaw8k"
 }

doc/.vscode/extensions.json

@@ -0,0 +1,28 @@
+{
+	// See https://go.microsoft.com/fwlink/?LinkId=827846
+	// for the documentation about the extensions.json format
+	"recommendations": [
+		// Main markdown support
+		"yzhang.markdown-all-in-one",
+
+		// Zettelkasten wiki-links, backlinks, etc.
+		"svsool.markdown-memo",
+
+		// Graph view 
+		// Disabled until https://github.com/tchayen/markdown-links/issues/28 is done
+		// "tchayen.markdown-links",
+
+		// For expanding title in daily note
+		"gruntfuggly.auto-snippet",
+
+		// Commands for bold, italic, etc.
+		"mdickin.markdown-shortcuts",
+
+		// Goodies:
+		// - Checkboxes
+		"bierner.markdown-checkbox",
+		// - Footnote
+		"houkanshan.vscode-markdown-footnote"
+"
+	]
+}

doc/.vscode/settings.json

@@ -0,0 +1,23 @@
+{
+    // Avoid having to explicitly save notes
+    "files.autoSave": "afterDelay",
+
+    // Minimap is not useful for Markdown notes
+    "editor.minimap.enabled": false,
+
+    // Generally note files are not opened in duplicate tabs.
+    // This also enables you to navigate to already open note in other split pane
+    "workbench.editor.revealIfOpen": true,
+
+    // For those that use daily notes, via vscode-memo extension
+    "autoSnippet.snippets": [
+        {
+            "pattern": "**/\\d{4}-\\d{2}-\\d{2}.md",
+            "snippet": "daily"
+        }
+    ]
+
+    // If use Git, these might be interesting:
+    // "git.autofetch": true,
+    // "git.postCommitCommand": "push"
+}

guide/examples.md → doc/Examples.md

@@ -1,8 +1,10 @@
-# Examples
+---
+slug: examples
+---
 
 Here are some public Zettelkastens managed by neuron:
 
-- [neuron.zettel.page](https://neuron.zettel.page/) ([source](https://github.com/srid/neuron/tree/master/guide)): This very site you are viewing.
+- [neuron.zettel.page](https://neuron.zettel.page/) ([source](https://github.com/srid/neuron/tree/master/doc)): This very site you are viewing.
 - [inariksit.github.io/cclaw-zettelkasten](https://inariksit.github.io/cclaw-zettelkasten/) ([source](https://github.com/inariksit/cclaw-zettelkasten)): Zettelkasten for the reading list of CCLAW@SMU
 - [zk.zettel.page](https://zk.zettel.page/) ([source](https://github.com/Kuratoro/zk.zettel.page)): Public Zettelkasten for the r/Zettelkasten subreddit
 - [Le note di azazel](http://azazel.it/): Personal Zettelkasten in Italian.

doc/Guide.md

@@ -0,0 +1,11 @@
+---
+slug: guide
+---
+
+**Basics**: A neuron notebook is just a directory of [[Zettel Markdown]] files, which are identified by [[id]]. Neuron transforms it into a [[Web interface]], that is generated statically (self-contained HTML files). Advanced functionality are added via [[Plugins]].
+
+**Managing**: See [[Creating and Editing zettels]], [[searching]] and [[query]]
+
+**Publishing**: [[Automatic Publishing]]
+
+**Extras**: [[extras]]

guide/create.md → doc/Guide/Creating and Editing zettels.md

@@ -1,4 +1,5 @@
 ---
+slug: create
 tags:
   - walkthrough
 ---
@@ -17,7 +18,13 @@ This command will print the path to the file created. Use `-e` to also open the
 neuron new -e
 ```
 
-Do not forget to link your new zettel to the rest of your Zettelkasten. See [[linking]].
+Of course, you can also start with an empty file and begin writing:
+
+```bash
+echo "Hello world ..." > "My new note.md"
+```
+
+Do not forget to link your new zettel to the rest of your Zettelkasten. See [[Linking]].
 
 ## Opening a Zettel by title
 

guide/editor.md → doc/Guide/Creating and Editing zettels/editor.md

@@ -2,30 +2,38 @@
 
 While you may use any text editor with neuron, the following extensions enable certain neuron-specific features on top of basic text editing.
 
-## Emacs 
+## VSCode
 
-Emacs support is available via [neuron-mode](https://github.com/felko/neuron-mode), which supports nifty editor features like opening a zettel by title, linking to other zettels by title, as well as displaying the title of the zettel next to the link (see screenshot below).
+:::{.ui .message}
+VSCode is recommended for new users of neuron.
+:::
 
-![screenshot](https://user-images.githubusercontent.com/3998/80873287-6fa75e00-8c85-11ea-9cf7-6e03db001d00.png){.ui .centered .large .image}
+These two extensions are useful when editing your Neuron notes in [Visual Studio Code](https://code.visualstudio.com/).
 
-## Vim
+* [vscode-memo](https://github.com/svsool/vscode-memo#memo) - supports both kinds of wikilinks
+* [markdown-links](https://github.com/tchayen/markdown-links) - supports only `[[..]]` style links, [but not folgezettel](https://github.com/tchayen/markdown-links/issues/59) (`[[[...]]]`).
 
-See [this fork of neuron.vim](https://github.com/fiatjaf/neuron.vim).
+Note that advanced features of neuron like [[Tag Queries]] will not be supported by either of these extensions. [LSP support](https://github.com/srid/neuron/issues/213) is ideal, but it has not been implemented by anyone yet.
 
-![screenshot](https://github.com/fiatjaf/neuron.vim/raw/master/screenshot.png){.ui .centered .large .image}
+![demo](./static/vscode-title-id.gif){.ui .centered .large .image}
 
-## VSCode
+## Editors known to work with v1
 
-These two extensions are useful when editing your Neuron notes in [Visual Studio Code](https://code.visualstudio.com/).
+These editors are known to work with version 1 of neuron. Your mileage may vary with the latest development version (version 2) of neuron.
 
-* [vscode-memo](https://github.com/svsool/vscode-memo#memo) - supports both kinds of wikilinks
-* [markdown-links](https://github.com/tchayen/markdown-links) - supports only `[[..]]` style link, [but not folgezettel](https://github.com/tchayen/markdown-links/issues/59) (`[[[...]]]`).
+### Emacs 
 
-Note that advanced features of neuron like [[link-query]] will not be supported by either of these extensions. [LSP support](https://github.com/srid/neuron/issues/213) is ideal, but it has not been implemented by anyone yet.
+Emacs support is available via [neuron-mode](https://github.com/felko/neuron-mode), which supports nifty editor features like opening a zettel by title, linking to other zettels by title, as well as displaying the title of the zettel next to the link (see screenshot below).
 
-![demo](./static/vscode-title-id.gif){.ui .centered .large .image}
+![screenshot](https://user-images.githubusercontent.com/3998/80873287-6fa75e00-8c85-11ea-9cf7-6e03db001d00.png){.ui .centered .large .image}
+
+### Vim
+
+See [this fork of neuron.vim](https://github.com/fiatjaf/neuron.vim).
+
+![screenshot](https://github.com/fiatjaf/neuron.vim/raw/master/screenshot.png){.ui .centered .large .image}
 
-## Online
+### Online
 
 [[cerveau]] can be used to edit your neuron v1 notes online using a web browser. Here's a small demo of the Cerveau editor in action, demonstrating the link autocomplete feature.
 

guide/Plugins/Directory Tree.md → doc/Guide/Plugins/Directory Tree.md

@@ -2,17 +2,23 @@
 slug: dirtree
 ---
 
+:::{.ui .message}
+This plugin must be manually enabled in [[configuration]]
+:::
+
 The *Directory Tree* plugin automatically creates a [[folgezettel-heterarchy]] reflecting the dirtectory tree of your notes. In effect, it does the following:
 
-1. Create a "directory zettel" on the fly for each sub-directory containing zettels
-2. Tag every zettel with a hierarchical [[tags]] (`root/**`) corresponding to its path
-3. Create folgezettel links (see [[linking]]) automatically reflecting the directory tree
+1. Create a "directory zettel" *on the fly* for each sub-directory containing zettels
+2. Create *folgezettel* links (see [[Linking]]) automatically reflecting the directory tree
+3. Display the directory contents below the zettel note.
+
+The intention is to allow the user to define the bulk of their [[folgezettel-heterarchy]] using filesystem layout.
 
-## Using and creating Directory Zettels
+## Working with Directory Zettels
 
-Given a file `./Home/Projects/HouseWarming.md` this plugin will create three zettels with [[id]]s `Home`, `Projects`, and `HouseWarming`. In the [[web]], neuron will display the "contents" of a directory beneath the zettel content.
+Given a file `./Home/Projects/HouseWarming.md` this plugin will create three zettels with [[id]]s `Home`, `Projects`, and `HouseWarming`. In the [[Web interface]], neuron will display the "contents" of a directory beneath the zettel content.
 
-Directory names must be **globally** unique across the entire zettelkasten, inasmuch they directly reflect [[id]] which must also be unique. This means that two directories or zettels with the same name but in different paths will not work: having both `./Home/Projects/HouseWarming` and `./Work/Projects/FireZeMissiles` will cause Neuron to attempt to generate two zettels with the ID `Projects`, which will cause an error. In order to resolve this error, and to keep the zettel IDs [[atomic]], it would be better to rename **both** notes to `./Home/HomeProjects/` and `./Work/WorkProjects/`.
+Directory names must be **globally** unique across the entire zettelkasten, inasmuch they directly reflect [[id]] which must also be unique. This means that two directories or zettels with the same name but in different paths will not work: having both `./Home/Projects/HouseWarming` and `./Work/Projects/FireZeMissiles` will cause Neuron to attempt to generate two zettels with the ID `Projects`, which will cause an error. In order to resolve this error, and to keep the zettel IDs [[Atomic and autonomous]], it would be better to rename **both** notes to `./Home/HomeProjects/` and `./Work/WorkProjects/`.
 
 ### Adding content to a Directory Zettel
 
@@ -35,20 +41,17 @@ The zettel content for directory zettels are by default empty, only showing a li
 - HouseWarming.html
 ```
 
-No addtional zettels are generated, but any content in the `HomeProjects.md` file will be shown in the generated `HomeProjects.html` file in the [[web]].
+No addtional zettels are generated, but any content in the `HomeProjects.md` file will be shown in the generated `HomeProjects.html` file in the [[Web interface]].
 
 ## Directory Zettels are normal zettels
 
-When Neuron is configured to use the **Directory Tree** plugin, it looks for all the markdown files in your repository, regardless of how many folders deep they are (unless you are using the [[Ignoring files]] plugin).
-
-The directory structure you have on disk is used to do 2 things:
+When Neuron is configured to use the **Directory Tree** plugin, it looks for all the markdown files in your repository, regardless of how many folders deep they are (but filtered out if the [[Ignoring files]] plugin is in use).
 
-- automatically create a [[folgezettel-heterarchy]] from a directory zettel with the zettels for its contents
-- automatically tag the zettels created with their on-disk path
+The directory structure you have on disk is used to automatically create a [[folgezettel-heterarchy]].
 
-Once Neuron generates the [[zettelkasten]], the directory structure is discarded from memory and not used in the [[web]]. All of the generated notes are made accessible at the 'top' level of the generated site--you don't need to navigate down the on-disk directory structure in the [[web]].
+Once Neuron generates the [[Zettelkasten]], the directory structure is discarded from memory and not used in the [[Web interface]]. All of the generated notes are made accessible at the 'top' level of the generated site--you don't need to navigate down the on-disk directory structure in the [[Web interface]].
 
-This is one reason why it's good practice to give your directories an [[atomic]] [[id]]--once you've generated your zettelkasten, you no longer have the parent directories around to provide context. The example from before, `./Home/Projects`, would create a note for your home projects with the ID `Projects`--we can no longer tell that it is specifically **home** projects. (The other reason it is good to have unique IDs is to avoid ID clash, as covered above.)
+This is one reason why it's good practice to give your directories an [[Atomic and autonomous]] [[id]]--once you've generated your zettelkasten, you no longer have the parent directories around to provide context, because the context is provided by the zettel's location in the [[folgezettel-heterarchy]] (as can be visually seen in [[Uplink Tree]]). The example from before, `./Home/Projects`, would create a note for your home projects with the ID `Projects`--we can no longer tell that it is specifically **home** projects. (The other reason it is good to have unique IDs is to avoid ID clash, as covered above.)
 
 ### Automatically created folgezettel heterarchies
 
@@ -88,11 +91,9 @@ date: 2020-12-31
 - paint the bathroom
 ```
 
-
-
 #### The **Directory Tree** plugin only triggers on folders inside the Neuron zettelksaten
 
-When enabled, the plugin will only work on the subfolders it finds **inside** the Neuron zettelkasten. This means that it will **not** automatically create a [[folgezettel-heterarchy]] from the `index` of your project to every zettel in the project (whether you have an explicit `index.md` zettel or just rely on Neuron's [[impulse-feature]] as your home)[^man].
+The [[folgezettel-heterarchy]] is created from the level 1 subfolders. The `index` zettel will display its contents, but they will be non-folgezettel. 
 
 ### Creating links and heterarchies outside the directory
 
@@ -127,33 +128,13 @@ my focus and energy, and not leaving much time to focus
 on my [[[HomeProjects]]].
 ```
 
-### Automatically created tags
+## Disabling directory listing
 
-In addition to creating automatic a [[folgezettel-heterarchy]] for each directory, the plugin also [[tags]] the notes with their on-disk path, up to, but **not including** their own ID. So the note at `./Home/HomeProjects/HouseWarming.md` would get the **hierarchical** tag `#root/Home/HomeProjects`. These tags always start at the `#root` tag.
+To disable showing the branching zettels in a directory zettel, you can add the following to the YAML frontmatter ([[metadata]]):
 
-Given our work-and-home project:
-
-```
-├── Work/
-│   └── WorkProjects/
-│      └── FireZeMissiles.md
-└─ Home/
-   ├── HomeProjects/
-   │   └── HouseWarming.md
-   └── HomeProjects.md
+```yaml
+---
+dirtree:
+  display: False
+---
 ```
-
-notes would be generated with these hierarchical tags that match their folder
-path:
-
-| Note                  | Tag                       |
-| --------------------- | ------------------------- |
-| `Work.html`           | `#root`                   |
-| `WorkProjects.html`   | `#root/Work`              |
-| `FireZeMissiles.html` | `#root/Work/WorkProjects` |
-| `Home.html`           | `#root`                   |
-| `HomeProjects.html`   | `#root/Home`              |
-| `HouseWarming.html`   | `#root/Home/HomeProjects` |
-
-[^man]: You may manually form these relationships by adding `[[[z:zettels?tag=root]]]` to the top-level `index.md`, since all the generated Directory Zettels are tagged with `#root`
-

guide/linking.md → doc/Guide/Plugins/Linking.md

@@ -13,7 +13,7 @@ You can also use regular Markdown links:
 * [My zettel](ef3dke98.md)
 ```
 
-In [[web]], neuron will automatically display the title of the
+In [[Web interface]], neuron will automatically display the title of the
 linked zettel when using the wiki-link syntax.
 
 ## Branching links
@@ -31,9 +31,9 @@ specified zettel. When a zettel has a folgezettel relationship to another
 zettel, it is said to "branch of" to the other zettel. Folgezetel relationships
 define the [[folgezettel-heterarchy]] of your zettel graph. 
 
-Branching links affect the linked zettel's [[5e41fd32]] where the linking
+Branching links affect the linked zettel's [[Uplink Tree]] where the linking
 zettel is displayed.
 
 ## Advanced linking
 
-* [[[link-query]]]
+If you use the [[Tags]] plugin, you can link automatically based on the tag (see [[[Tag Queries]]]).

guide/tags.md → doc/Guide/Plugins/Tags.md

@@ -19,7 +19,7 @@ tags:
 
 ## Hierarchical tags
 
-Tags can be nested using a "tag/subtag" syntax, to allow a more fine-grained organization of your Zettelkasten, especially when using advanced queries as shown in [[link-query]].
+Tags can be nested using a "tag/subtag" syntax, to allow a more fine-grained organization of your Zettelkasten, especially when using advanced queries as shown in [[Tag Queries]].
 
 For example, the following zettel is tagged "math/calculus/definition"
 
@@ -39,8 +39,4 @@ It will be included in the following tag queries:
 - `math/calculus/definition`
 - `**/definition`
 
-See [[link-query]] to understand how to link zettels automatically based on tag patterns as above.
-
-## Tag trees
-
-Use `[[z:tags?filter=**]]` to render your entire tags set as a tree. Note that this only *renders* the tags; whereas `[[z:zettels?tag=...]]` of [[link-query]] exists to *link* to the zettels tagged with matching tags.
+See [[Tag Queries]] to understand how to link zettels automatically based on tag patterns as above.