Org-wiki is a org-mode extension that provides tools to manage and build personal wiki or desktop wiki where each wiki page is a org-mode file.
It provides a custom protocol wiki:keyword
which creates like. When
clicked this links creates the wiki file in the wiki directory with
name keyword.org
.
Repository | https://github.com/caiorss/org-wiki |
Html documentation | https://caiorss.github.io/org-wiki/ |
Features:
- A wiki system for Emacs.
- Search wiki pages quickly.
- Create new wiki pages fast.
- Command to export all pages to html without block Emacs. M-x
M-x org-wiki/export-html-async
- Search wiki pages by its content. (grep)
- org-mode protocol to create and open wiki pages.
- org-mode protocol to open attachment/asset files with default system application.
- Automatic download of attachment files with:
M-x org-wiki-asset-download-insert1
M-x org-wiki-asset-download-insert2
Org-mode already has many features that makes it suitable to create a desktop wiki and store knowledge like:
- Render Latex formulas.
- Block codes (org-babel).
- Fast navigation and editing
- Support for tables
- Ability to export to html and other formats.
- Links to files, images, system commands and Elisp commands.
Note It is only possible to show the video demonstrations in html version.
Link formats
wiki:<pagename>
Example:
wiki:Linux
or
[[wiki:Linux]]
or
[[wiki:Linux][Linux]]
wiki-asset-sys:<pagename>/<asset file name>
Example:
wiki-asset-sys:Linux;LearnLinux.pdf
or
[[wiki-asset-sys:Linux;LearnLinux.pdf]]
or
[[wiki-asset-sys:Linux;LearnLinux.pdf][Book Learn Linux.pdf]]
It will open the file ~/wiki-directory/Linux/LearnLinux.pdf
with the
default system application.
What is a personal wiki/ desktop wiki?
It is a digital notebook or a note taking app integrated with desktop. Some examples are Zim Wiki, Microsoft OneNote and Tomboy (software).
What org-wiki is not
- It is not a server wiki like Mediawiki (Wikipedia Engine) or Dokuwiki. So it has no administrative panel and user account and so on. Despite it not be a server wiki, it can serve org pages (*.org files) exported html with Python3 web server help in read-only mode.
Why org-wiki?
Server wikis are hard to manage and install for a single user and requires installation of a web server like Apache, PHP and a database server like MySql or PostgresSQL.
Desktop wikis like org-wiki, Zim, OneNote and Tomboy are easier to install and manage than server wikis and has less memory requirements.
The problems of many wikis are the lack of a good text editor, extensibility and desktop integration. Org-wiki solves that by putting the Wiki inside the most awesome text editor: Emacs and everything is just one keybinding or one command away. Another advantage is the org-mode format and Emacs integration that provides fast editing, fast refactoring, headline folding, fast table manipulation, export to many formats like html, pdf and so on, Latex equations and literate programming in many languages like C, C++, Python, R and so on.
You can see Org-mode Screencasts and reviews here:
- (1) Browsing Index: M-x org-wiki/index
- (2) M-x org-wiki/helm - Select a wiki page by name.
- (3) M-x org-wiki/insert Insert a link to wiki page at cursor position.
- (4) - M-x org-wiki/asset-insert Insert a link to a asset file that when clicked opens it with default system application.
See video: M-x org-wiki/asset-insert
- (5) - Org-wiki exported to HTML
You can view a sample wiki exported to html here:
- Sample org-wiki exported to html
- This sample wiki is available at sandbox/wiki
- 1. Command
M-x org-wiki-index
Open the wiki index page (file index.org)
- 2. Command
M-x org-wiki-helm
Open a helm menu to select the wiki page to be opened.
- 3.
M-x org-wiki- [tab]
provides easy completion and discoverability to org-wiki commands.
- 4.
M-x org-wiki-dired
Open the org-wiki directory showing only the wiki pages (*.org files).
- 5.
M-x org-wiki-dired-all
Open the org-wiki directory showing all files.
- 6.
M-x org-wiki-search-pattern
Search for all wiki page that contains a pattern. (string or regex pattern).
Example: The command M-x org-wiki/search-patern - System.Windows
will search all
files that contains “System.Windows string”.
To create a page do:
- 1. M-x org-wiki-index - It goes to the Org-wiki index page (index.org).
- 2. Then run M-x org-wiki-create and a page name like ‘CNC - Computer Numerical Control’
It will insert a hyperlink at point like:
[[wiki:CNC%20-%20Computer%20Numerical%20Control][CNC - Computer Numerical Control]]
- 3. Then click at the link or enter C-x C-o at the link to open it.
The navigation can be done by running
M-x org-wiki-index
or
M-x org-wiki-helm
that will show a helm combobox menu where the user view all pages and search a page by typing its name.
or
M-x org-wiki-helm-frame
to open a page in another frame (Emacs terminology for GUI window).
Evaluate this code in the scratch buffer that will install all
dependencies and this package. The scratch buffer can be evaluated
with M-x eval-buffer
.
(let ((url "https://raw.githubusercontent.com/caiorss/org-wiki/master/org-wiki.el"))
(with-current-buffer (url-retrieve-synchronously url)
(goto-char (point-min))
(re-search-forward "^$")
(delete-region (point) (point-min))
(kill-whole-line)
(package-install-from-buffer)))
Just copy this piece of code to scratch buffer and eveluate the buffer
with M-x eval-buffer
. It is assumed that el-get is already installed.
(el-get-bundle org-wiki
:url "https://raw.githubusercontent.com/caiorss/org-wiki/master/org-wiki.el"
:description "Emacs' desktop wiki built with org-mode"
:features org-wiki
)
Copy the package to the desired location.
mkdir -p ~/.emacs.d/packages/
cd ~/.emacs.d/packages/
git clone https://github.com/caiorss/org-wiki
mkdir -p ~/org/wiki # Make wiki location.
Make org-wiki directory
M-x make-directory ~/org-wiki
Add to init file ~/.emacs.d/init.el or ~/.emacs
(require 'org-wiki)
Org-wiki can configured programatically by setting the org-wiki custom
varibles or with M-x customize-group org-wiki
.
Path where all org-wiki pages (*.org files) are stored.
(setq org-wiki-location "~/org/wiki")
or in Windows it could be:
(setq org-wiki-location "e:/projects/org-wiki-test.emacs")
If the custom variable org-wiki-default-read-only
is set to true (t)
org-wiki pages are opened in read-only mode. The default value of this
variable is nil (false). It is useful to avoid unintentionally change
an org-wiki page.
The read-only mode can be toggled with M-x toggle-read-only
or C-x C-q.
- Open org-wiki pages in read-only mode.
(setq org-wiki-default-read-only t)
- Open org-wiki pages in non read-only mode.
(setq org-wiki-default-read-only nil) ;; Default value
Org-wiki can serve the pages exported to html with python help.
The variable org-wiki-server-port (default value 8000) sets the default port that Python web server will listen to.
It can be set with:
(setq org-wiki-server-port "8000") ;; 8000 - default value
The variable org-wiki-server-host (default value 0.0.0.0 - all hosts) sets the host that the Python server will listen.
It can be set with:
(setq org-wiki-server-host "0.0.0.0") ;; Listen all hosts (default value)
(setq org-wiki-server-host "127.0.0.1") ;; Listen only localhost
In order to the html export work the path to emacs executable
directory must be in the $PATH variable. In some OS like Windows where
this path is not in $PATH variable it is necessary to set the variable
org-wiki-emacs-path
like:
(setq org-wiki-emacs-path "c:/Users/arch/opt/emacs/bin/runemacs.exe")
Optional: This package provides the command M-x org-wiki-make-menu
that installs a menu on the menu bar.
The menu can be installed permanently by adding the init file:
(org-wiki-make-menu)
The user can set the org-wiki template used to create org-wiki files by changing the custom variable with
M-x customize-variable org-wiki-template
The default template is:
#+TITLE: %n
#+DESCRIPTION:
#+KEYWORDS:
#+STARTUP: content
- [[wiki:index][Index]]
- Related:
* %n
where:
- %n is replaced by the page name
- %d is replaced by current date in the format year-month-day
This variable can also be set programatically with:
(setq org-wiki-template
(string-trim
"
#+TITLE: %n
#+DESCRIPTION:
#+KEYWORDS:
#+STARTUP: content
#+DATE: %d
- [[wiki:index][Index]]
- Related:
* %n
"))
- M-x org-wiki-index to go to index.org
- New pages can be created with
M-x org-wiki-link
that asks for wiki word and inserts at point a hyperlink to the wiki page. - References to existing pages can be inserted with
M-x org-wiki-insert
.
M-x Command | Description |
---|---|
Help | |
org-wiki-help | Show all org-wiki commands. |
org-wiki-website | Open org-wiki default website. |
Navigation | |
org-wiki-index | Go to the index page or index.org |
org-wiki-index-frame | Open org-wiki index page in a new frame. |
org-wiki-helm | Open a org-wiki page |
org-wiki-helm-frame | Open a org-wiki page in a new frame |
org-wiki-helm-read-only | Open a org-wiki page in read-only mode |
org-wiki-switch | Switch between org-wiki buffers |
Close Command | |
org-wiki-close | Close all buffers with files in org-wiki-location directory and save the editable buffers. |
org-wiki-close-images | Close all org-wiki image buffers. |
Insert Commands | |
org-wiki-create | Insert a link at point to a new org-wiki page. Click or follow the link to edit the new page. |
org-wiki-insert | Insert a link at point to an existing org-wiki page. |
org-wiki-header | Insert at the top of an org-wiki buffer an org-mode header template. |
org-wiki-asset-insert-file | Insert link to asset/attachment file that can be opened with Emacs at point such as source codes. |
org-wiki-asset-insert-image | Insert link to image file at point. |
org-wiki-asset-insert | Insert a link to asset/attachment file at point. When the user clicks, |
it opens with default system application. It is useful to open pdfs, | |
spreadsheets and so on. | |
org-wiki-asset-download-insert1 | Download a file and insert a link to it at point. Similar to org-wiki-asset-insert |
org-wiki-asset-download-insert2 | Download a file and insert a link to it at point. Similar to org-wiki-asset-insert-file |
Directory | |
org-wiki-dired | Open org-wiki-location or org-wiki storage directory in Emacs showing only *.org files. |
org-wiki-open | Open org-wiki-location with default system file manager. |
org-wiki-dired-all | OPen org-wiki-location showing all files. |
Alias Command | |
org-wiki-nav | Alias to helm-org-in-buffer-headings |
org-wiki-occur | Alias to helm-occur |
org-wiki-toggle-images | Toggle images display. Alias to org-toggle-inline-images |
org-wiki-toggle-link | Toggle link display. Alias to M-x org-toggle-link-display. |
org-wiki-latex | Display latex formulas. Alias to org-preview-latex-fragment. Requires latex installed. |
Backup Command | |
org-wiki-backup-make | Create new zip file backup of all org-wiki files. |
org-wiki-backup-dir | Open backup directory. |
Misc | |
org-wiki-panel | A panel like magit-status panel. |
org-wiki-server-toggle | Toggle Python web server. |
org-wiki-make-menu | Install an org-wiki menu. |
Not. complete.
M-x org-wiki-help
Show all org-wiki commands and its description.M-x org-wiki-website
Open org-wiki project website in the default web browser.
M-x org-wiki-index
- Open the index page. It opens the file index.org that is the first default page of the wiki. If the file doesn’t exist it will be created.
M-x org-wiki-index-frame
- Open the wiki index page in a new frame.
M-x org-wiki-helm
- Open a helm menu to switch or open a wiki page.
M-x org-wiki-switch
- Switch between org-wiki buffers (*.org files in org-wiki-location directory) already opened.
M-x org-wiki-helm-frame
- Open a wiki page in a new frame.
M-x org-wiki-helm-read-only
- Open a wiki page in read-only mode.
M-x org-wiki-make-page
- Creates a new wiki page asking the user for the page name.
M-x org-wiki-close
- Close all wiki pages, kill all *.or buffers belonging to wiki directory.
- Close all org-wiki image/picture buffers.
- M-x org-wiki-link - Asks the user for the wiki page name and
inserts the hyperlink at point. It is useful to create new pages
fast without write the full syntax like
[[wiki:page title] [page title]
Example:
- 1. User enter M-x org-wiki-link and enter “The Art of Unix Programming”
- 2. It will insert at point (current cursor position):
[[wiki:The%20Art%20of%20Unix%20Programming][The Art of Unix Programming]]
And will create the hyperlink to this page.
M-x org-wiki-insert
- Inserts a org-mode link at current point to a Wiki page selected through a helm-menu.
- =M-x org-wiki-header. It inserts at top of the wiki page the template:
#+TITLE: <PAGE TITLE>
#+DESCRIPTION:
#+KEYWORDS:
#+STARTUP: overview
Related:
[[wiki:index][Index]]\n\n
M-x org-wiki-asset-insert
- Insert a asset file at point providing a heml menu to select the file. It inserts a link of formatwiki-asset-sys:CurrentPage;AssetFilename.pdf
.
Open page’s asset directory in Emacs dired mode.
M-x org-wiki-assets-open
- Open asset directory of current page with system’s default file manager.
M-x org-wiki-assets-helm
- Select a wiki page and open its assets directory.
Prompts the user for a file name that doesn’t exist yet and insert it at point. Unlike the commands `org-wiki-asset-insert` or ` org-wiki-asset-insert-file` this command asks the user for a file that doesn’t exist yet and inserts a hyperlink to it at point.
Example: If the user enter this command and he is in the page Linux and types scriptDemoQT.py it will insert a link at point like this file:Linux/scriptDemoQT.py that doesn’t exist yet. The user can then open the link and edit the file.
M-x org-wiki-asset-insert
- Insert a link to asset file of current page at current cursor position. This link when clicked opens with default system application.
Example: Inserts a a link such as the code below. User is in the page Linux and with this command selects in the Helm menu the file Manual.pdf.
[[wiki-asset-sys:Linux;Manual.pdf][Manual.pdf]]
M-x org-wiki-asset-insert-file
- Insert a link to an asset file that can be opened with Emacs at cursor position. This is an ordinary org-mode link.
Use this file for files supposed to be opened with Emacs such as Python, bash scripts or source codes.
Note: Don’t use this command to insert images,
use M-x org-wiki-insert-image
instead of this.
Example: If the current page is Python and user selects the file pyscript.py it will insert a hyperlink at point as this.
[[file:python/pyscript.py][pyscript.py]]
It will be rendenred as this:
M-x org-wiki-asset-insert-file
- Insert a link to an image file at point.
Example: If the current page is Python and the user selects the file QTScreenshot.png it will insert a hyperlink to this file that will be rendered as an image when current page is exported to html.
[[file:python/QTScreenshot.png][file:python/QTScreenshot.png]]
Insert code block with contents of some asset file as an org-mode block:
Example:
If the current page is ‘Smalltalk programming’ it the user select the file ‘extendingClasses-number1.gst’ it will insert a code block with the file contents and a hyperlink to it at point.
- File: [[file:Smalltalk%20programming/extendingClasses-number1.gst][file:Smalltalk programming/extendingClasses-number1.gst]]
#+BEGIN_SRC text
Number extend [
inv [ 1.0 / ^self
]
neg [ - ^self
]
]
#+END_SRC
It would insert a content like this:
Number extend [
inv [ 1.0 / ^self
]
neg [ - ^self
]
]
It will open a helm menu containing the assets files of current page. It will open the selected file with Emacs.
Example: If the current page is ‘Smalltalk programming’ and the user select the file ‘extendingClasses-number1.gst’ it will open the file below with Emacs.
- Smalltalk programming/’extendingClasses-number1.gst
Open a menu to select an asset file of current page and open it with system’s app.
Example: If the current page is ‘Smalltalk programming’ and the user select the file ‘numerical-methods-in-smalltalk.pdf’ it will be opened with the default system’s application like Foxit PDF or Okular reader.
M-x org-wiki-asset-download-insert1
- Ask the user the url to download a file suggesting the url stored in the clipboard and then asks the file name. After download it inserts a hyperlink at point to open the file with systems’ default application.
Example:
- User is in the page Linux that corresponds to the file <org-wiki-location>/Linux.org
- User copy the url https://inst.eecs.berkeley.edu/~cs61b/fa13/ta-materials/unix-concise-ref.pdf
- User enter M-x org-wiki-asset-download-insert1
- Confirm the first prompt asking for the url. The suggested url is the copied url.
- Confirm the second prompt asking the file name. The suggested name is unix-concise-ref.pdf
- It will insert at current point the hyperlink bellow. That points to the file <org-wiki-location>/Linux/unix-concise-ref.pdf.
[[wiki-asset-sys:Linux;unix-concise-ref.pdf][unix-concise-ref.pdf]]
Note: This command is synchronous and it can hang Emacs, therefore downloading heavy files can freeze Emacs. If it happesn type C-g to cancel the current download.
M-x org-wiki-asset-download-insert2
- Similar toM-x org-wiki-asset-download-insert1
, however it inserts a hyperlink of typefile:<org-wiki-page>/<file-name>
.
Example:
- User is in the page Linux and copies the url:
http://i1-linux.softpedia-static.com/screenshots/htop_1.jpg
- User enter the command M-x org-wiki-asset-download-insert1 and answers all prompts.
- It will insert the hyperlink bellow at point.
file:Linux/htop_1.jpg
M-x org-wiki-dired
- Open the wiki directory in Emacs dired-mode showing only *.org files.
M-x org-wiki-dired-all
- Open the wiki directory in Emacs showing all files.
M-x org-wiki-export-html
- Exports all wiki pages to html asynchronously, it means withoyt block Emacs by starting a new Emacs process in background.
M-x org-wiki-index-html
- Open the index page exported to html in the web browser.
M-x org-wiki-search
- Search all wiki page that contains a pattern. (string or regex pattern).M-x org-wiki-find-dired
- Show all files in all org-wiki subdirectories.
M-x org-wiki-desc
- Show all org-wiki pages with description.
M-x org-wiki-keywords
- Display all org-wiki keywords and related org-wiki page files.
M-x org-wiki-copy-location
- Copy org-wiki location path to clipboard.M-x org-wiki-copy-index-html
- Copy path of index page exported to html to clipboard. Example: /<org-wiki-location>/index.htmlM-x org-wiki-copy-asset-path
- Copy current page asset/attachment directory path to clipboard. Example: If the current page is Linux, it will copy the ’<org-wiki-location>/Linux’ to clipboard.
To create a backup run M-x org-wiki-backup-make
it will create a
file org-wiki-<YEAR>-<MONTH>-<DAY>.zip
, such as
org-wiki-2017-08-10.zip
, in the directory org-wiki-backup-location.
To open the backup directory run M-x org-wiki-backup-dir.
M-x org-wiki-server-toggle
Start/stop static http server at org-wiki directory.
This command actually runs python -m http.server --bind <host> <port>
at the org-wiki directory. So it requires Python installed and
available in the $PATH variable.
Default value:
- host: 0.0.0.0
- port: 8000
To see your current local IP address type M-x ifconfig
. You can
access the static web site by entering the URL:
http://<your local ip address>:8000
- For instance: http://192.168.1.10:8000.
M-x org-wiki-panel
- This command provides a command panel that can execute actions just typing few keys like magit or dired buffer.
M-x org-wiki-make-menu
Shows a menu with org-wiki functions and command reminders.
Org-wiki can create backups of org-wiki snapshots stored in zip files that can be useful to avoid losses or revert to a previous state.
Set the org-wiki-backup directory. The variable org-wiki-backup-location is initially set to nil.
If the backup directory doesn’t exist yet, it is created whenever the user runs any backup command.
Note: It is assumed that the $ zip
command line application is the
$PATH variable.
(setq org-wiki-backup-location "~/Documents/org-wiki-backup")
This command requires the utility clip.jar and Java runtime to be available at the $PATH variable.
The custom variable org-wiki-clip-jar-path
holds the path to
clip.jar utility has the default value: ~/bin/Clip.jar
.
If you wish to install in Clip.jar in a different path set the variable org-wiki-clip-jar-path like this in the init file:
(setq org-wiki-clip-jar-path "~/bin/opt/Clip.jar")
You can download a binary release with:
mkdir ~/bin && cd ~/bin curl -O -L https://github.com/caiorss/clip.jar/blob/build/Clip.jar
M-x org-wiki-paste-image
Ask the user for the image file name and writes the image from clipboard to the file.
Example:
- User copies an image with mouse right click to clipboard.
- User type the command M-x org-wiki-paste-image and choses the name Unix.png and he is on the page Linux (Linux.org). It will write the image to the file ./Linux/Unix.png and will insert a this block at current cursor position:
#+CAPTION: file:Linux/Unix.png
M-x org-wiki-paste-image-uuid
Paste an image from clipboard with automatically generated name (uuid).
Example:
- User copies an image from clipboard and type the command
M-x org-wiki-paste-image-uuid
. It will insert at point this block containing a hyperlink to the image like:
#+CAPTION: file:Linux/fba53c12-3f23-4728-9f52-a26a3d285d7c.png
M-x org-wiki-nav
- Navigate through org-mode headings. Alias to helm-org-in-buffer-headings.
M-x org-wiki-occur
- Alias to helm-occur.
M-x org-wiki-toggle-images
- Toggle images. Alias to M-x org-toggle-inline-images.
M-x org-wiki-toggle-link
- Toggle link display. Alias to M-x org-toggle-link-display.
M-x org-wiki-latex
- Display latex formulas. Alias to M-x org-preview-latex-fragment. It requires latex installed.
You might want shortcuts for frequent commands:
- Open a wiki page quickly.
M-x w-h
(defalias 'w-h #'org-wiki-helm)
- Switch between org-wiki buffers, wiki pages already opened.
(defalias 'w-s #'org-wiki-switch)
- Open a wiki page in a new frame quickly.
(defalias 'w-hf #'org-wiki-helm-frame)
- Switch to wiki page in read-only mode.
(defalias 'w-hr #'org-wiki-helm-read-only)
- Go to the index page
(defalias 'w-i #'org-wiki-index)
- Insert a link to a wiki page at point. It provides helm
completion.
M-x w-in
(defalias 'w-in #'org-wiki-insert)
- Open the current wiki page assets directory:
M-x w-ad
(defalias 'w-ad #'org-wiki-asset-dired)
- Export current wiki page to html or any org-mode file.
M-x og2h
(defalias 'og2h #'org-html-export-to-html)
- Close all wiki pages
(defalias 'w-close #'org-wiki-close)
Some Helm commands are very handy to navigate and search org-mode files.
- M-x helm-org-in-buffer-headings - To filter the headings of org-files.
- M-x helm-occur - Occur-like command with helm interface.
Linux
Windows
Bookmarklets are small pieces of Javascript used for browser automation and as an ad-hoc browsers extensions, encoded as hyperlinks that can be stored in the web browser’s bookmark toolbar.
If you don’t kwnow what is a bookmarklet see:
Note: The hyperlink of bookmarklet is only visible on the html documentation.
This bookmarklet opens a prompt and creates an org-mode hyperlink code for the current web page.
- To test the bookmarklet just click on it and copy the generated hyperlink.
- To install the bookmarklet drag and drop the hyperlink to browser bookmark toolbar.
Bookmarklet:
Org-mode UrlJavascript code:
var md = "[[" + document.URL + "][" + document.title + "]]" ;
prompt("org-mode :", md);
Compressed JavaScript code:
javascript:(function(){var md = "[[" + document.URL + "][" + document.title + "]]" ;prompt("org-mode :", md);})()
More bookmarklets and cheat sheet available at:
and
You can change the commands or explore it using the command.
M-x find-function <command-name>
to open the file at the point where
the function is defined and edit the file org-wiki.el.
Example:
- M-x find-function
org-wiki-helm
- M-x find-library org-wiki
- [x] - Add command to copy and paste images from clipboard.
- [] - Add this package to some Emacs repository.
- [x] - Add a runnable test.
- [x] - Add org-wiki example pages and generated html files.
- [] - Update gifs