First plugins: directory tree & .neuronignore

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 - Introducing *impulse* -- foundation for upcoming advanced search, replacing both z-index and legacy JS search (#108)
 - 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.
 
 ## Unreleased (v1 + v2)
 

dep/directory-contents/default.nix

@@ -0,0 +1,2 @@
+# DO NOT HAND-EDIT THIS FILE
+import (import ./thunk.nix)

dep/directory-contents/github.json

@@ -0,0 +1,8 @@
+{
+  "owner": "srid",
+  "repo": "directory-contents",
+  "branch": "sans-tests",
+  "private": false,
+  "rev": "43025f4739590c82cbfc8dcf15d0ff17b1f37324",
+  "sha256": "1ianv9y4gzb1835bw7xbjn94wpbm6znq006hdayya0ih1iqz2csq"
+}

dep/directory-contents/thunk.nix

@@ -0,0 +1,9 @@
+# DO NOT HAND-EDIT THIS FILE
+let fetch = { private ? false, fetchSubmodules ? false, owner, repo, rev, sha256, ... }:
+  if !fetchSubmodules && !private then builtins.fetchTarball {
+    url = "https://github.com/${owner}/${repo}/archive/${rev}.tar.gz"; inherit sha256;
+  } else (import <nixpkgs> {}).fetchFromGitHub {
+    inherit owner repo rev sha256 fetchSubmodules private;
+  };
+  json = builtins.fromJSON (builtins.readFile ./github.json);
+in fetch json

guide/.neuronignore

@@ -0,0 +1,10 @@
+# Ignore top-level dotfiles and dotdirs
+.*/**
+
+# Ignore project specific files
+README.md
+CHANGELOG.md
+LICENSE.md
+
+# Ignore everything under sub directories
+#*/*/**

guide/Plugins.md

@@ -0,0 +1,21 @@
+---
+slug: plugins
+---
+
+Neuron includes several plugins, some of them are enabled by default.
+
+You can turn on or turn off these plugins in [[configuration]]. For example, the following setting in your `neuron.dhall` will enable the [[Ignoring files]] plugin, while leaving others (such as [[Directory Tree]]) disabled.
+
+```dhall
+{ plugins = [ "neuronignore" ]
+}
+```
+
+To enable *all* plugins,
+
+```dhall
+{ plugins = [ "neuronignore", "dirtree" ]
+}
+```
+
+Available plugins are listed immediately below.

guide/Plugins/Directory Tree.md

@@ -0,0 +1,20 @@
+---
+slug: dirtree
+---
+
+The *Directory Tree* plugin achieves two things:
+
+1. Create a "directory zettel" on the fly for each sub-directory
+2. Create folgezettel links (see [[linking]]) automatically reflecting the directory tree
+
+## Directory Zettel
+
+Given a folder `./Project/HouseWarming/`, this plugin will create two zettels with [[id]] `Project` and `HouseWarming`. Directory names must be unique, inasmuch they directly reflect [[id]] which must also be unique. In the [[web]], neuron will display the "contents" of a directory beneath the zettel content. 
+
+The zettel content for directory zettels are by default empty. However, you may explicitly specify them by creating zettel files using the same [[id]]; for the example above, you may create `./Project.md` and `./Project/HouseWarming.md` - and they will be "merged" to the auto-created directory zettels.
+
+## Links & tags created
+
+A [[folgezettel-heterarchy]] is formed, reflecting the directory tree on disk, with the exception of the `index` zettel[^man]. The forming of links is based on hierarchical [[[tags]]] (reflecting the relative path), that every normal zettel and directory zettel is automatically tagged with.
+
+[^man]: You may manually form these relationships by adding `[[[z:zettels?tag=index]]]` to the top-level `index.md`

guide/Plugins/Ignoring files.md

@@ -0,0 +1,21 @@
+---
+slug: neuronignore
+---
+
+The `neuronignore` plugin allows you to specify a list of patterns that will be used to ignore specific Markdown files.
+
+Add a file named `.neuronignore` to your notes directory. It should look like this:
+
+```ini
+# Ignore top-level dotfiles and dotdirs
+.*/**
+
+# Ignore project specific files
+README.md
+CHANGELOG.md
+LICENSE.md
+
+# Ignore everything under sub directories 
+# (if not using dirtree plugin)
+*/*/**
+```

guide/configuration.md

@@ -7,13 +7,11 @@ You may configure the parameters of your web interface by adding an optional con
 | Field name        | Description                                                                                                                                                                                |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **`siteTitle`**   | Your Neuron site's title                                                                                                                                                                   |
-| **`author`**      | Author name                                                                                                                                                                                |
 | **`siteBaseUrl`** | The base URL of your published Neuron site. Setting the base URL will enable [breadcrumbs](https://developers.google.com/search/docs/data-types/breadcrumb) in your site's structured data |
+| **`author`**      | Author name                                                                                                                                                                                |
 | **`theme`**       | Color scheme to use for your site. Value must be [one of the color names](https://semantic-ui.com/usage/theming.html#sitewide-defaults) supported by SemanticUI.                           |
 | **`editUrl`**     | The URL (without the zettel filename) to edit zettels. To remove the edit button from the navbar, remove this entry from your configuration.                                               |
-| **`minVersion`**  | The minimum neuron version your site must be generated with.                                                                                                                               |
-
-
+| **`plugins`**     | See [[Plugins]]                                                                                                                                                                            |
 ## Example 
 
 ```json

guide/guide.md

@@ -8,6 +8,7 @@ Core concepts:
 
 - [[[id]]]
 - [[[markdown]]]
+- [[[Plugins]]]
 
 For generating static sites:
 

impulse/project.nix

@@ -21,6 +21,7 @@ let
         impulse = pkgs.lib.cleanSource (gitignoreSource ./.);
 
         # neuron & its dependencies (not already in reflex-platform)
+        # TODO: Use hackGet for direct/no-reload development?
         neuron = pkgs.runCommand "neuron" { buildInputs = [ ]; }
           ''
           mkdir -p $out/src
@@ -30,6 +31,7 @@ let
           LINE=`grep -n LIBMARKER ${neuronSrc}/neuron.cabal | cut -f1 -d:`
           head -n $LINE ${neuronSrc}/neuron.cabal > $out/neuron.cabal
           '';
+        directory-contents = import ../dep/directory-contents/thunk.nix;
         reflex-dom-pandoc = import ../dep/reflex-dom-pandoc/thunk.nix;
         pandoc-link-context = import ../dep/pandoc-link-context/thunk.nix;
         commonmark = cm + "/commonmark";