{"id":13451213,"url":"https://github.com/felko/neuron-mode","last_synced_at":"2025-03-23T18:32:01.775Z","repository":{"id":54273510,"uuid":"251012577","full_name":"felko/neuron-mode","owner":"felko","description":"An emacs mode for editing Zettelkasten notes with neuron","archived":false,"fork":false,"pushed_at":"2022-07-18T08:27:34.000Z","size":165,"stargazers_count":119,"open_issues_count":13,"forks_count":21,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-28T18:39:47.651Z","etag":null,"topics":["emacs","emacs-lisp","emacs-mode","markdown","zettelkasten"],"latest_commit_sha":null,"homepage":"","language":"Emacs Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/felko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-29T11:09:01.000Z","updated_at":"2024-09-12T06:30:51.000Z","dependencies_parsed_at":"2022-08-13T10:40:31.419Z","dependency_job_id":null,"html_url":"https://github.com/felko/neuron-mode","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felko%2Fneuron-mode","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felko%2Fneuron-mode/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felko%2Fneuron-mode/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/felko%2Fneuron-mode/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/felko","download_url":"https://codeload.github.com/felko/neuron-mode/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245149428,"owners_count":20568906,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["emacs","emacs-lisp","emacs-mode","markdown","zettelkasten"],"created_at":"2024-07-31T07:00:49.917Z","updated_at":"2025-03-23T18:31:56.759Z","avatar_url":"https://github.com/felko.png","language":"Emacs Lisp","funding_links":[],"categories":["Emacs Lisp","Uncategorized","Software"],"sub_categories":["Uncategorized"],"readme":"[![MELPA](https://melpa.org/packages/neuron-mode-badge.svg)](https://melpa.org/#/neuron-mode)\n\n# neuron-mode\n\nneuron-mode is an Emacs major mode derived from\n[markdown-mode](https://jblevins.org/projects/markdown-mode/) to edit notes\nusing the [neuron](https://neuron.zettel.page/) Zettelkasten manager.\n\n\u003cp align=\"center\"\u003e\u003ca href=\"https://asciinema.org/a/329911\"\u003e\u003cimg src=\"https://asciinema.org/a/329911.svg\" alt=\"drawing\" width=\"600\"/\u003e\u003c/a\u003e\u003c/br\u003eneuron-mode demo in \u003ca href=\"https://github.com/hlissner/doom-emacs\"\u003edoom emacs\u003c/a\u003e\u003c/p\u003e\n\n## Installation\n\n1. Install [neuron](https://neuron.zettel.page/2011501.html) and make sure that\n   the `neuron` command is in your path.\n\n2. Install neuron-mode, either via MELPA (recommended) or manually by cloning\n   this repository.\n\nIf you are using an emacs distribution like doom emacs or spacemacs, refer to\n[this paragraph](#appendix-integration-to-emacs-distributions) to see how\nneuron-mode can be integrated into your configuration.\n\n## Features\n\nAll commands are executed in the active zettelkasten which is either detected by\ntraversing the directory hierarchy upwards until a `neuron.dhall` file is met\n(see [neuron configuration](https://neuron.zettel.page/2011701.html)), or\notherwise it uses the zettelkasten that is specified by\n`neuron-default-zettelkasten-directory` (a path). Although `neuron.dhall` files\nare not mandatory to use neuron itself, this is what enables neuron-mode\nautomatically when opening a markdown file. neuron-mode will then cache the\nzettels and regenerate it when needed (typically when creating a new zettel).\nSometimes, when the zettelkasten is modified externally to neuron-mode, you\nmight need to invalidate the cache and rebuild it manually, which is done with\nthe `neuron-refresh` command. This will also reload the titles displayed next to\nzettel links (see next paragraph).\n\n#### Reading\n\nneuron-mode allows you to browse your zettelkasten directly from Emacs. Most\nimportantly, neuron links are shown together with their titles so that you don't\nneed to read the zettel from the associated HTML file anymore.\n\n#### Navigating\n\nneuron links can also be followed using `neuron-follow-thing-at-point`. For\nqueries, it will prompt you to select a zettel that match the query under the\npoint.\n\nNavigating \"upwards\" is also possible, using the `neuron-edit-uplink` function.\n\n#### Searching\n\nThe `neuron-edit-zettel` will prompt you with the list of zettels, where you can\nsearch by title, by tag or by ID using ivy.\n\nprojectile can also be useful as a complement to neuron-mode since it allows you\nto search the zettelkasten by content.\n\n#### Editing\n\nYou can create new zettels from Emacs, neuron-mode will take care of creating\nthe file with a generated hash in the current active zettelkasten.\n\nLinks can be inserted using `neuron-insert-zettel-link` which will prompt you to\nselect an existing zettel in the active zettelkasten. Zettels can also be linked\nand created on the fly by using `neuron-insert-new-zettel`. A third way to\ninsert links, assuming that you use company, is by typing `\u003ca few keywords` and\nthen running `company-neuron`. This will show all the zettels whose titles match\nthose keywords. You can enable `company-neuron` automatically by calling\n`company-neuron-setup` which will trigger the autocompletion when you start\ntyping a link. You can enable this globally by adding a hook to neuron-mode:\n(e.g. `(add-hook 'neuron-mode-hook #'company-neuron-setup)`).\n\nTo avoid typos in tags which might mess up the organization of your\nzettelkasten, use `neuron-add-tag`/`neuron-add-tags` which will allow you to\nselect from already existing tags.\n\n#### Using rib\n\nRib commands can be executed from Emacs. Running `neuron-rib-generate` will\ncompile your zettelkasten to HTML. This can also be done automatically using\n`neuron-rib-watch` which will generate every time you save a zettel.\n\nThe resulting HTML files can then be accessed either from neuron-mode with\n`neuron-open-current-zettel` which will open the HTML that is associated with\nthe zettel being edited, or globally with `neuron-open-zettel`.\n\nAlternatively, you can use the rib server to read your zettelkasten from your\nbrowser. The server can be started using `neuron-rib-serve` and stopped using\n`neuron-rib-kill`. Similar functions are provided to open the zettels in the web\napp rather than local files (respectively `neuron-rib-open-current-zettel` and\n`neuron-rib-open-zettel`).\n\n### Function list\n\n| Command                                    | Default binding | Description                                                                        |\n| :----------------------------------------- | :-------------- | :--------------------------------------------------------------------------------- |\n| `neuron-new-zettel`                        | `C-c C-z`       | Create a new zettel and open it for edition                                        |\n| `neuron-edit-zettel`                       | `C-c C-e`       | Select an existing zettel and open it for editing                                  |\n| `neuron-edit-uplink`                       | `C-c C-,`       | Select and edit a zettel that links to the current one                             |\n| `neuron-add-tag`                           | `C-c C-t`       | Select and insert a tag in the current zettel's YAML metadata block                |\n| `neuron-add-tags`                          | `C-c C-S-t`     | Same as `neuron-add-tag` but adds multiple tags simultaneously                     |\n| `neuron-query-tags`                        | N/A             | Select a tag and then a zettel with that tag                                       |\n| `neuron-replace-tag`                       | N/A             | Replace a tag by another across the entire zettelkasten                            |\n| `neuron-open-current-zettel`               | `C-c C-r`       | Open the current zettel's generated HTML file in the browser                       |\n| `neuron-insert-zettel-link`                | `C-c C-l`       | Search a zettel by content and insert the link at point                            |\n| `neuron-insert-new-zettel`                 | `C-c C-S-l`     | Combine `neuron-new-zettel` and `neuron-insert-zettel-link`                        |\n| `neuron-create-and-insert-zettel-link`     | N/A             | Like `neuron-insert-zettel-link` but can also create new zettels                   |\n| `neuron-create-zettel-from-selected-title` | N/A             | Transform the selected text into a new zettel                                      |\n| `neuron-insert-static-link`                | `C-c C-s`       | Insert a link to a selected file in the static directory                           |\n| `neuron-toggle-connection-type`            | N/A             | Toggle the connection type under point, between cf and folgezettel                 |\n| `neuron-open-daily-notes`                  | `C-c C-o`       | Open today's notes if it exists, or create it otherwise                            |\n| `neuron-refresh`                           | `C-c C-S-r`     | Regenerate the zettel cache and title overlays in all neuron-mode buffers          |\n| `neuron-toggle-id-visibility`              | N/A             | Toggle between showing the titles next to the IDs or over them                     |\n| `neuron-follow-thing-at-point`             | N/A             | Override `markdown-follow-thing-at-point` to handle zettel URI protocol            |\n| `neuron-edit-zettelkasten-configuration`   | N/A             | Open the neuron.dhall file at the root of the current zettelkasten                 |\n| `neuron-rib-generate`                      | N/A             | Perform a one-off generation of the site                                           |\n| `neuron-rib-serve`                         | N/A             | Start the wep application on `localhost:8080`                                      |\n| `neuron-rib-open-z-index`                  | N/A             | Open the web application at `localhost:8080/z-index.html`                          |\n| `neuron-rib-open-zettel`                   | N/A             | Select and open a zettel note in the web appliation                                |\n| `neuron-rib-kill`                          | N/A             | Kill the web application process                                                   |\n| `company-neuron`                           | N/A             | Trigger a company tooltip in which you can insert links by autocompleting by title |\n\n## Configuration\n\n### Customize settings\n\n- `neuron-default-zettelkasten-directory` (default: `\"~/zettelkasten`) \\\n  Defines the fallback zettelkasten when the current directory is not located in\n  a zettelkasten.\n- `neuron-executable` (default: `neuron`) \\\n  Path or wrapper around the neuron executable. \\\n  Example: this can be useful when using Emacs from Windows, while having neuron\n  installed on WSL, in which case you can set `neuron-executable` to\n  `wsl neuron`.\n- `neuron-generate-on-save` (default: `nil`) \\\n  Generates the site when saving a note. Opens a compilation buffer (`neuron-rib-generate`)\n- `neuron-id-format` (default: `'hash`) \\\n  Controls the default ID format used when creating new notes. \\\n  It can be set to:\n  - `'hash`: generates an unique 32 bit UUID (default behavior of neuron)\n  - `'prompt`: asks for the ID when creating a new zettel\n  - a function: generate a custom ID based on the zettel title. (not recommended\n    for actual knowledge based zettelkastens but might be useful for e.g.\n    slugging the titles for documentations) The function has to generate a valid\n    neuron ID. \\\n    Example: If you want to have slug-converted title as ID, you can put the following in .emacs \\\n    ```emacs lisp\n    \n    (defun sluggify (title)\n     (s-join \"-\" (split-string (s-downcase title))))\n     \n    (setq neuron-id-format 'sluggify)\n    ```\n- `neuron-title-format` (default: `# %s`) \\\n  Format string for title of a new zettel. This format string will be run through \n  `format` (with title as argument) to populate the new zettel.\n- `neuron-default-tags` (default: `nil`) \\\n  A list of tags to add to zettels when they are created. This does not affect daily\n  notes. \\\n  Example: `stub` (to mimic\n  [Wikipedia's stubs](https://en.wikipedia.org/wiki/Wikipedia:Stub))\n- `neuron-tag-specific-title-faces` (default: `nil`) \\\n  An alist that associates tags to faces, which will appear in the title overlay\n  when a link points to a zettel that has the corresponding tag. Example: `'((\"stub\" hl-todo))`\n- `neuron-daily-note-id-format` (default: `\"%Y-%m-%d\"`) \\\n  Format that controls the filenames of newly created daily notes\n- `neuron-daily-note-title-format` (default: `\"%x\"`) \\\n  The format of titles for new daily notes\n- `neuron-daily-note-tags` (default: `(list \"journal/daily\")`) \\\n  The default tag of daily notes.\n- `neuron-rib-server-host` (default: `localhost`) \\\n- `neuron-rib-server-port` (default: `8080`) \\\n  The host and port on which the rib server will run\n- `neuron-max-completion-width` (default: `30`) \\\n   The maximum number of columns after which the company completion will\n  truncate the titles to fit the given width.\n\n### Other variables\n\n- `neuron-make-title` (default: capitalizes the first word) \\\n  A function that is called by `neuron-create-zettel-from-selection` to transform\n  the text into the actual title of the new zettel.\n- `neuron-show-ids` (default: `nil`) \\\n  Whether to show the IDs next to zettel titles, rather than having the titles completely\n  hide them. Can be toggled using `neuron-toggle-id-visibility`.\n\n## Appendix: integration to Emacs distributions\n\n### doom-emacs configuration\n\ndoom-emacs users can use this configuration to work with `neuron-mode`:\n\n\u003chttps://gist.github.com/felko/cdb3fc19b3a60db27eb3c5bd319fc479\u003e\n\n(include those files in `.doom.d/modules/tools/neuron`)\n\nThis creates a private module that can then be enabled by inserting `neuron`\nunder the `:tools` section of your `doom!` block (inside your `init.el`).\n\n### Spacemacs integration\n\nA spacemacs layer for neuron-mode along with installation instructions can be\nfound in the\n[LightAndLight/spacemacs-neuron](https://github.com/LightAndLight/spacemacs-neuron)\nrepository.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelko%2Fneuron-mode","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffelko%2Fneuron-mode","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffelko%2Fneuron-mode/lists"}