{"id":18083570,"url":"https://github.com/akirak/org-multi-wiki","last_synced_at":"2025-06-19T09:40:35.986Z","repository":{"id":49560040,"uuid":"239261631","full_name":"akirak/org-multi-wiki","owner":"akirak","description":"Org-based wiki system for multiple workgroups with namespace support","archived":false,"fork":false,"pushed_at":"2024-09-17T15:12:22.000Z","size":193,"stargazers_count":26,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-06-17T21:13:00.242Z","etag":null,"topics":["emacs","knowledge-base-system","note-taking","org-mode","wiki"],"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/akirak.png","metadata":{"files":{"readme":"README.org","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2020-02-09T07:03:24.000Z","updated_at":"2025-06-01T04:30:34.000Z","dependencies_parsed_at":"2025-04-13T08:15:34.616Z","dependency_job_id":null,"html_url":"https://github.com/akirak/org-multi-wiki","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/akirak/org-multi-wiki","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akirak%2Forg-multi-wiki","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akirak%2Forg-multi-wiki/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akirak%2Forg-multi-wiki/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akirak%2Forg-multi-wiki/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/akirak","download_url":"https://codeload.github.com/akirak/org-multi-wiki/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/akirak%2Forg-multi-wiki/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260726499,"owners_count":23053167,"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","knowledge-base-system","note-taking","org-mode","wiki"],"created_at":"2024-10-31T14:08:45.226Z","updated_at":"2025-06-19T09:40:30.971Z","avatar_url":"https://github.com/akirak.png","language":"Emacs Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"# -*- mode: org; mode: org-make-toc -*-\n* org-multi-wiki\nThis is a package for working with multiple Org-based knowledge base sites inside a single Emacs session.\nIt uses alphapapa's [[https://github.com/alphapapa/org-ql][helm-org-ql]] for searching, which makes navigation and entry creation seamless.\n\n#+BEGIN_HTML\n\u003ca href=\"https://github.com/akirak/org-multi-wiki/actions?query=workflow%3A%22CI%22\"\u003e\n\u003cimg alt=\"Build Status\" src=\"https://github.com/akirak/org-multi-wiki/workflows/CI/badge.svg\" /\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://melpa.org/#/org-multi-wiki\"\u003e\u003cimg alt=\"org-multi-wiki on MELPA\" src=\"https://melpa.org/packages/org-multi-wiki-badge.svg\"/\u003e\u003c/a\u003e\n\n\u003ca href=\"https://melpa.org/#/helm-org-multi-wiki\"\u003e\u003cimg alt=\"helm-org-multi-wiki on MELPA\" src=\"https://melpa.org/packages/helm-org-multi-wiki-badge.svg\"/\u003e\u003c/a\u003e\n#+END_HTML\n** Table of contents\n:PROPERTIES:\n:TOC: siblings\n:END:\n-  [[#features][Features]]\n-  [[#prerequisites][Prerequisites]]\n-  [[#installation][Installation]]\n-  [[#configuration][Configuration]]\n  -  [[#namespace-predicate-for-org-ql][Namespace predicate for org-ql]]\n  -  [[#integration-with-org-recent-headings][Integration with org-recent-headings]]\n-  [[#usage][Usage]]\n  -  [[#the-current-namespace][The current namespace]]\n  -  [[#helm-org-multi-wiki][helm-org-multi-wiki]]\n    -  [[#running-on-particular-namespaces][Running on particular namespaces]]\n    -  [[#quickly-creating-an-entry-in-a-particular-namespace][Quickly creating an entry in a particular namespace]]\n    -  [[#inserting-a-link][Inserting a link]]\n  -  [[#moving-contents][Moving contents]]\n-  [[#details][Details]]\n  -  [[#wiki-link-type][wiki link type]]\n  -  [[#file-name-escaping][File name escaping]]\n  -  [[#linking-to-a-particular-heading-in-a-file][Linking to a particular heading in a file]]\n  -  [[#entry-levels-and-entry-templates][Entry levels and entry templates]]\n  -  [[#buffer-names][Buffer names]]\n  -  [[#customizing-the-helm-source][Customizing the helm source]]\n-  [[#alternatives][Alternatives]]\n-  [[#license][License]]\n\n** Features\n=org-multi-wiki= is an Org-based wiki system for Emacs with the following features:\n\n- 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.\n- It supports =org-ql= for searching contents in wikis. =org-ql= is an expressive query language designed for Org mode. A helm support is included.\n- It adds a custom =wiki= link type to =org-mode= to resolve locations of wiki files across namespaces.\n- The directory of each namespace can be either recursive or non-recursive. If it's set to recursive, =org-multi-wiki= also searches Org files in subdirectories recursively.\n** Prerequisites\n- Emacs 26.1 or later\n- Org 9.3 or later\n- =dash.el=\n- =s.el=\n- =org-ql=\n- [[https://github.com/alphapapa/org-ql][helm-org-ql]], if you use helm-org-multi-wiki (recommended)\n** Installation\nThis package is available on MELPA as =org-multi-wiki= and =helm-org-multi-wiki=.\n** Configuration\nBelow is an example configuration through =use-package=:\n\n#+begin_src emacs-lisp\n  (use-package org-multi-wiki\n    :config\n    (org-multi-wiki-global-mode 1)\n    :custom\n    (org-multi-wiki-namespace-list '((personal \"~/org/personal/\")\n                                     (ops \"~/org/ops/\")\n                                     (programming \"~/org/programming/\")\n                                     (client1 \"~/projects/client1/client1-docs/\")\n                                     (client2 \"~/projects/client2/client2-docs/\")))\n    ;; Namespace of a wiki\n    (org-multi-wiki-default-namespace 'personal))\n\n  (use-package helm-org-multi-wiki)\n #+end_src\n\nFirst configure =org-multi-wiki-namespace-list= variable.\nIt is a list where each item is a list of the following items:\n\n- A symbol to identify the wiki, called namespace\n- A directory containing Org files.\n\nYou can append a plist to the list to set options on each namespace.\n\nYou also have to turn on =org-multi-wiki-global-mode= for activating several function advices and the custom link type.\n\nFor more options, see =org-multi-wiki= customization group.\n*** Namespace predicate for org-ql\n:PROPERTIES:\n:CREATED_TIME: [2020-12-12 Sat 23:36]\n:END:\nYou can also define a predicate for =org-ql= to test if an entry is inside a particular namespace:\n\n#+begin_src emacs-lisp\n  (org-ql-defpred wiki (namespace)\n    \"It is inside a particular namespace.\"\n    :body (org-multi-wiki-in-namespace-p (intern namespace)))\n#+end_src\n\nYou can use the predicate in =helm-org-multi-wiki= to display entries in a particular namespace, e.g. =wiki:namespace keyword=.\n*** Integration with org-recent-headings\n:PROPERTIES:\n:CREATED_TIME: [2020-12-12 Sat 23:37]\n:END:\n[[https://github.com/alphapapa/org-recent-headings/][org-recent-headings]] is a package which lets you quickly jump to a recently visited heading.\nTo track headings visited by =org-multi-wiki=, you may want to add the following configuration:\n\n#+begin_src emacs-lisp\n  (with-eval-after-load 'org-recent-headings\n    (add-hook 'org-recent-headings-advise-functions\n              #'org-multi-wiki-follow-link)\n    (add-hook 'org-recent-headings-advise-functions\n              #'helm-org-ql-show-marker)\n    (add-hook 'org-recent-headings-advise-functions\n              #'helm-org-ql-show-marker-indirect))\n#+end_src\n** Usage\n*** The current namespace\nMost commands in this package work with a single namespace: the current namespace.\n\nTo open a file in the current namespace, use =org-multi-wiki-visit-entry= command.\nTo switch the namespace, use =org-multi-wiki-switch=.\n\nOptionally, you can work on a specific namespace by calling functions with a namespace.\nFor example, =org-multi-wiki-visit-entry= with a universal prefix argument (~C-u~) lets you select a namespace.\n*** helm-org-multi-wiki\n=helm-org-multi-wiki= command is the main entry point in this package.\nIt uses [[https://github.com/alphapapa/org-ql#helm-org-ql][helm-org-ql]] for search and a dummy source for entry creation.\nIt is included in =helm-org-multi-wiki.el=.\n\nBy default, it lets you select a heading or create a new entry in the current namespace.\n\nWith a universal prefix argument (~C-u~), you can select wikis.\nYou can select multiple namespaces with ~C-SPC~.\n**** Running on particular namespaces\n:PROPERTIES:\n:CREATED_TIME: [2020-02-22 Sat 14:34]\n:END:\nYou can also use it as a function which accepts a namespace or a list of namespaces.\nYou can define your own command to search queries in a specific wiki.\n\n#+begin_src emacs-lisp\n  (defun helm-org-multi-wiki-project1 ()\n    (interactive)\n    (helm-org-multi-wiki '(project1)))\n#+end_src\n\nWhen multiple namespaces are given, you can select a directory in which you want to create a new file.\nThis is available as alternative actions (~tab~) in the dummy source of Helm.\n\nThe package also provides =helm-org-multi-wiki-all=, which performs search on all namespaces.\n**** Quickly creating an entry in a particular namespace\n:PROPERTIES:\n:CREATED_TIME: [2020-02-22 Sat 14:35]\n:END:\nThe dummy source has a dedicated keymap =helm-make-helm-org-multi-wiki-dummy-source-map= which lets you bind keys to create an entry in a particular namespace:\n\n#+begin_src emacs-lisp\n  (general-def :keymap 'helm-org-multi-wiki-dummy-source-map :package 'helm-org-multi-wiki\n    :prefix \"C-c C-c\"\n    \"p\" (helm-org-multi-wiki-def-create-entry-action programming))\n#+end_src\n\nWith this configuration, you can create an entry in =programming= wiki from the minibuffer input by pressing ~C-c C-c p~.\n\n=helm-org-multi-wiki-def-create-entry-action= macro defines an interactive function which exits the running helm session and visits an entry.\n**** Inserting a link\n:PROPERTIES:\n:CREATED_TIME: [2021-02-09 Tue 00:06]\n:END:\n=helm-org-multi-wiki-insert-link= lets you select a heading from all namespaces and inserts a link to the heading.\n\nIf there is an active region, it replaces the selected text with a link.\n*** Moving contents\nYou can move an existing subtree to an wiki using =org-multi-wiki-create-entry-from-subtree= command.\n** Details\n*** =wiki= link type\n:PROPERTIES:\n:CREATED_TIME: [2020-02-09 Sun 16:01]\n:END:\nThis package adds =wiki= link type to =org-link-parameters=.\n\nThe link format complies to one of the following formats:\n\n- Linking with a custom ID: =NAMESPACE:[subdir/]TITLE[::#customid]=\n- Linking with a heading: =NAMESPACE:[subdir/]TITLE[::*heading]=\n\n=NAMESPACE= is the namespace of a wiki. It is omitted when linking to the same namespace.\nNote: This behaviour can be altered by setting =org-multi-wiki-allow-omit-namespace= to nil.\n\n=TITLE= can be either the base name of an escaped file name (i.e. without =.org=) or its original top-level heading.\n=::= and its following part is omitted when linking to a top-level heading in a file.\n\nFile resolution is done by attempting the following schemes, in that order:\n\n1. It tries to find a file with the base name of the exact =TITLE=.\n2. It escapes =TITLE= into a safe file name and tries to find a file with the base name.\n3. It tries to find a file with a top-level heading matching =TITLE= in the directory.\n\n=subdir= is not supported now, but it will be added when this package supports recursive file search.\n*** File name escaping\n:PROPERTIES:\n:CREATED_TIME: [2020-03-14 Sat 20:04]\n:END:\n=org-multi-wiki= does some escaping of file names.\nThe escaping function consists of multiple steps such as:\n\n- Split the title by whitespace, capitalize each word, and concatenate them. The result is usually upper camel cased.\n- If a word contains at least one upper case alphabet, the word is not capitalized and case is retained.\n- It eliminates symbols other than hyphens, dots, and underscores.\n- It eliminates words such as \"a\", \"an\", and \"the\".\n- It keeps non-ascii characters such as Chinese and Japanese.\n\nIt is designed to be both filename-safe and friendly to the modern world with technical terms.\nHowever, you can alter the logic by setting =org-multi-wiki-escape-file-name-fn= to another function.\n*** Linking to a particular heading in a file\nYou can link to a heading in a file either with a heading text or with a custom ID property.\n\nLinking with a custom ID is generally safer, because custom IDs don't change when you change headings.\nTo enforce generation of a custom ID when storing a link, set =org-multi-wiki-want-custom-id= variable to t.\n\nNote that a link to a top-level heading does not contain a link fragment, i.e. a heading or a custom ID by default.\nSee the following subsection for changing this behaviour.\n*** Entry levels and entry templates\nIt is recommended that you include at least one heading in each Org file in wiki.\nThe following structure is not recommended:\n\n#+begin_example\n#+title: My wiki page\n\\* First heading\n#+end_example\n\nInstead, the following structure is recommended:\n\n#+begin_example\n\\* My wiki page\n\\** First heading\n#+end_example\n\nI 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.\n\nFollowing this principle, the default file template of this package generates a heading rather than a file header.\nTo change the template, set =org-multi-wiki-entry-template-fn= variable..\n\nAlso, links to top-level heading don't contain a link fragment by default.\nThis is because top-level headings are considered page titles in the structure and each file should contain only one top-level heading.\nHowever, depending on your needs, you may want to include multiple top-level headings in a single file.\nYou can include a fragment in a link to a top-level heading using one of the following options:\n\n- Set =org-multi-wiki-top-level-link-fragments= to t, which is globally effective\n- Set =:top-level-link-fragments= option in =org-multi-wiki-namespace-list=, which is locally effective\n*** Buffer names\n:PROPERTIES:\n:CREATED_TIME: [2020-03-24 Tue 00:53]\n:END:\nTo let the user easily distinguish between wikis, =org-multi-wiki= renames file buffers according to their respective namespaces when it opens Org files:\n\n[[file:screenshots/helm-org-multi-wiki-multi-ns-1.png]]\n\nTo turn off this behavior, set =org-multi-wiki-rename-buffer= to nil.\n*** Customizing the helm source\n:PROPERTIES:\n:CREATED_TIME: [2020-03-24 Tue 00:53]\n:END:\nAlthough =helm-org-multi-wiki= is based on =helm-org-ql=, it allows further customizations to make it slightly different from the original package:\n\n- 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-query= variable. This should be an S-expression query accepted by =org-ql=.\n- It allows you to customize the query parser by setting =helm-org-multi-wiki-query-parser= to a different value. By default, it uses the plain query parser of =org-ql=.\n- You can change the keymap and the action by setting =helm-org-multi-wiki-map= and =helm-org-ql-actions=, respectively, By default, it uses the same values as =helm-org-ql=.\n** Alternatives\nThere are several knowledge base systems for Emacs based on Org mode.\n\n[[https://github.com/Kungsgeten/org-brain][org-brain]] and [[https://github.com/jethrokuan/org-roam][org-roam]] are especially powerful ones.\norg-brain is based on the idea of concept mapping, and org-roam is a rudimentary replica of another software named Roam.\norg-multi-wiki is not based on such a specific framework.\nIt focuses on search and entry creation and has built-in support for multiple namespaces.\nIt provides an infrastructure for building your own wiki system on top of Org mode.\n\n[[https://github.com/abo-abo/plain-org-wiki][plain-org-wiki]] is the direct inspiration of this package.\norg-multi-wiki supports multiple namespaces and takes advantage of =helm= and =org-ql= for providing a rich querying interface.\n** License\nGPLv3\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakirak%2Forg-multi-wiki","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fakirak%2Forg-multi-wiki","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fakirak%2Forg-multi-wiki/lists"}