This is a package for working with multiple Org-based knowledge base sites inside a single Emacs session. It uses alphapapa’s helm-org-ql for searching, which makes navigation and entry creation seamless.
org-multi-wiki is an Org-based wiki system for Emacs with the following features:
- It supports working with multiple isolated directories inside a single Emacs session. It lets you define namespaces to uniquely identify content groups. You can search contents from one or more of the namespaces and create a new entry in any of them.
- It supports
org-qlfor searching contents in wikis.org-qlis an expressive query language designed for Org mode. A helm support is included. - It adds a custom
wikilink type toorg-modeto resolve locations of wiki files across namespaces. - The directory of each namespace can be either recursive or non-recursive. If it’s set to recursive,
org-multi-wikialso searches Org files in subdirectories recursively.
- Emacs 26.1 or later
- Org 9.3 or later
dash.els.elorg-ql- helm-org-ql, if you use helm-org-multi-wiki (recommended)
This package is available on MELPA as org-multi-wiki and helm-org-multi-wiki.
Below is an example configuration through use-package:
(use-package org-multi-wiki
:config
(org-multi-wiki-global-mode 1)
:custom
(org-multi-wiki-namespace-list '((personal "~/org/personal/")
(ops "~/org/ops/")
(programming "~/org/programming/")
(client1 "~/projects/client1/client1-docs/")
(client2 "~/projects/client2/client2-docs/")))
;; Namespace of a wiki
(org-multi-wiki-default-namespace 'personal))
(use-package helm-org-multi-wiki)First configure org-multi-wiki-namespace-list variable.
It is a list where each item is a list of the following items:
- A symbol to identify the wiki, called namespace
- A directory containing Org files.
You can append a plist to the list to set options on each namespace.
You also have to turn on org-multi-wiki-global-mode for activating several function advices and the custom link type.
For more options, see org-multi-wiki customization group.
org-ql to test if an entry is inside a particular namespace:
(org-ql-defpred wiki (namespace)
"It is inside a particular namespace."
:body (org-multi-wiki-in-namespace-p (intern namespace)))You can use the predicate in helm-org-multi-wiki to display entries in a particular namespace, e.g. wiki:namespace keyword.
org-multi-wiki, you may want to add the following configuration:
(with-eval-after-load 'org-recent-headings
(add-hook 'org-recent-headings-advise-functions
#'org-multi-wiki-follow-link)
(add-hook 'org-recent-headings-advise-functions
#'helm-org-ql-show-marker)
(add-hook 'org-recent-headings-advise-functions
#'helm-org-ql-show-marker-indirect))Most commands in this package work with a single namespace: the current namespace.
To open a file in the current namespace, use org-multi-wiki-visit-entry command.
To switch the namespace, use org-multi-wiki-switch.
Optionally, you can work on a specific namespace by calling functions with a namespace.
For example, org-multi-wiki-visit-entry with a universal prefix argument (C-u) lets you select a namespace.
helm-org-multi-wiki command is the main entry point in this package.
It uses helm-org-ql for search and a dummy source for entry creation.
It is included in helm-org-multi-wiki.el.
By default, it lets you select a heading or create a new entry in the current namespace.
With a universal prefix argument (C-u), you can select wikis.
You can select multiple namespaces with C-SPC.
(defun helm-org-multi-wiki-project1 ()
(interactive)
(helm-org-multi-wiki '(project1)))When multiple namespaces are given, you can select a directory in which you want to create a new file.
This is available as alternative actions (tab) in the dummy source of Helm.
The package also provides helm-org-multi-wiki-all, which performs search on all namespaces.
helm-make-helm-org-multi-wiki-dummy-source-map which lets you bind keys to create an entry in a particular namespace:
(general-def :keymap 'helm-org-multi-wiki-dummy-source-map :package 'helm-org-multi-wiki
:prefix "C-c C-c"
"p" (helm-org-multi-wiki-def-create-entry-action programming))With this configuration, you can create an entry in programming wiki from the minibuffer input by pressing C-c C-c p.
helm-org-multi-wiki-def-create-entry-action macro defines an interactive function which exits the running helm session and visits an entry.
helm-org-multi-wiki-insert-link lets you select a heading from all namespaces and inserts a link to the heading.
If there is an active region, it replaces the selected text with a link.
You can move an existing subtree to an wiki using org-multi-wiki-create-entry-from-subtree command.
wiki link type to org-link-parameters.
The link format complies to one of the following formats:
- Linking with a custom ID:
NAMESPACE:[subdir/]TITLE[::#customid] - Linking with a heading:
NAMESPACE:[subdir/]TITLE[::*heading]
NAMESPACE is the namespace of a wiki. It is omitted when linking to the same namespace.
Note: This behaviour can be altered by setting org-multi-wiki-allow-omit-namespace to nil.
TITLE can be either the base name of an escaped file name (i.e. without .org) or its original top-level heading.
:: and its following part is omitted when linking to a top-level heading in a file.
File resolution is done by attempting the following schemes, in that order:
- It tries to find a file with the base name of the exact
TITLE. - It escapes
TITLEinto a safe file name and tries to find a file with the base name. - It tries to find a file with a top-level heading matching
TITLEin the directory.
subdir is not supported now, but it will be added when this package supports recursive file search.
org-multi-wiki does some escaping of file names.
The escaping function consists of multiple steps such as:
- Split the title by whitespace, capitalize each word, and concatenate them. The result is usually upper camel cased.
- If a word contains at least one upper case alphabet, the word is not capitalized and case is retained.
- It eliminates symbols other than hyphens, dots, and underscores.
- It eliminates words such as “a”, “an”, and “the”.
- It keeps non-ascii characters such as Chinese and Japanese.
It is designed to be both filename-safe and friendly to the modern world with technical terms.
However, you can alter the logic by setting org-multi-wiki-escape-file-name-fn to another function.
You can link to a heading in a file either with a heading text or with a custom ID property.
Linking with a custom ID is generally safer, because custom IDs don’t change when you change headings.
To enforce generation of a custom ID when storing a link, set org-multi-wiki-want-custom-id variable to t.
Note that a link to a top-level heading does not contain a link fragment, i.e. a heading or a custom ID by default. See the following subsection for changing this behaviour.
It is recommended that you include at least one heading in each Org file in wiki. The following structure is not recommended:
#+title: My wiki page \* First heading
Instead, the following structure is recommended:
\* My wiki page \** First heading
I write READMEs of my open source projects in this style, and if you use helm-org-ql, you won’t be able to reach a file without a heading.
Following this principle, the default file template of this package generates a heading rather than a file header.
To change the template, set org-multi-wiki-entry-template-fn variable..
Also, links to top-level heading don’t contain a link fragment by default. This is because top-level headings are considered page titles in the structure and each file should contain only one top-level heading. However, depending on your needs, you may want to include multiple top-level headings in a single file. You can include a fragment in a link to a top-level heading using one of the following options:
- Set
org-multi-wiki-top-level-link-fragmentsto t, which is globally effective - Set
:top-level-link-fragmentsoption inorg-multi-wiki-namespace-list, which is locally effective
org-multi-wiki renames file buffers according to their respective namespaces when it opens Org files:
To turn off this behavior, set org-multi-wiki-rename-buffer to nil.
helm-org-multi-wiki is based on helm-org-ql, it allows further customizations to make it slightly different from the original package:
- It can display items when no query is given in the minibuffer. By default, it displays top-level items. You can customize this via
helm-org-multi-wiki-default-queryvariable. This should be an S-expression query accepted byorg-ql. - It allows you to customize the query parser by setting
helm-org-multi-wiki-query-parserto a different value. By default, it uses the plain query parser oforg-ql. - You can change the keymap and the action by setting
helm-org-multi-wiki-mapandhelm-org-ql-actions, respectively, By default, it uses the same values ashelm-org-ql.
There are several knowledge base systems for Emacs based on Org mode.
org-brain and org-roam are especially powerful ones. org-brain is based on the idea of concept mapping, and org-roam is a rudimentary replica of another software named Roam. org-multi-wiki is not based on such a specific framework. It focuses on search and entry creation and has built-in support for multiple namespaces. It provides an infrastructure for building your own wiki system on top of Org mode.
plain-org-wiki is the direct inspiration of this package.
org-multi-wiki supports multiple namespaces and takes advantage of helm and org-ql for providing a rich querying interface.
GPLv3