caiorss / org-wiki

Wiki for Emacs org-mode built on top of Emacs org-mode.

org-wiki

Org-wiki

Overview

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.

FAQ

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:

• http://orgmode.org/worg/org-tutorials/org-screencasts/

Demos

• (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

Screenshots

• 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”.

Workflow

Switching wiki

Now org wiki supports multiple wikis or root directories, but only one wiki can be used at a time. So, to switch wiki type:

• M-x org-wiki-switch-root

Create a page - way 1

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-insert-new 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.

Create a page - way 2

Run M-x org-wiki-new and enter the page name, for instance ‘Unix System Calls’, it will create the file ‘Unix System Calls.org’ in the root directory and open it for editing.

The advantage of creating a page using ‘way 1’ is that it inserts a link to the new created page before opening it, therefore making easier to categorize and navigate the pages.

Browse a page

The navigation can be done by running

• M-x org-wiki-index It will open the index page which contains hyperlinks to other wiki pages.

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).

Install

Installation Methods

Method 1 - Bootstrap installer

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)))

Method 2 - El-get

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
  )

Method 3 - Manual installation

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. 

Configuration

Basic settings

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.

Paths to Wiki locations

This new version supports multiples org-wiki directories or multiple wikis in different directories, but only one wiki can be used at a time. The current wiki directory can be selected by using te command M-x org-wiki-switch-root.

Paths where all org-wiki pages (*.org files) are stored.

;;
;; (setq org-wiki-location "~/org/wiki")

(setq org-wiki-location-list
      '(
        "~/Documents/wiki"    ;; First wiki (root directory) is the default. 
        "~/Documents/wiki2 "
        "~/Documents/wiki3"
        ))

;; Initialize first org-wiki-directory or default org-wiki 
(setq org-wiki-location (car org-wiki-location-list))

The default value of this variable is

'("~/org/wiki")

In Windows it can be:

• Note: backward slash in path \, must be escaped as
  

;; (setq org-wiki-location "e:/projects/org-wiki-test.emacs")

(setq org-wiki-location-list
      '(
        "C:\\Users\\john\\Documents\\wiki-main"    ;; First wiki is the default. 
        "F:/storage/wiki2"
        "G:\\Documents\\wiki3"
        ))

Open org-wiki pages in read-only

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 unintended and accidental changings 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

Close all wiki pages when switching wiki

If the custom variable org-wiki-close-root-switch (default value true, t) is set to true, it will close all org-wiki pages of the current wiki (root path) before switching to another org-wiki location.

Enable:

(setq org-wiki-close-root-switch t)

Disable

(setq org-wiki-close-root-switch nil)

Server settings

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 

Export Settings

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)

Template

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
"))

Start the wiki

• 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.

Command Summary

M-x Command	Description
Help
org-wiki-help	Show all org-wiki commands.
org-wiki-website	Open org-wiki default website.
Navigation
org-wiki-switch-root	Switch between multiple org wikis listed in the variable ‘org-wiki-location-list’
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-switch	Switch between org-wiki buffers or already opened pages
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
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-insert-new	Insert a link at point to a new org-wiki page. Click or follow the link to edit the new page.
org-wiki-insert-link	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
org-wiki-insert-symbol	Insert Greek letters, math and physics symbols such as α, γ, Δ, Σ, ∞, ℉
org-wiki-insert-block	Insert quote block, source code code block, latex equation block and so on.
org-wiki-insert-latex	Insert latex templates, formulas, Greek letters and math symbols.
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 yet.

Commands

Help

• 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.

Open the index page

M-x org-wiki-index

• 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

• M-x org-wiki-index-frame - Open the wiki index page in a new frame.

Pages

M-x org-wiki-helm

• M-x org-wiki-helm - Open a helm menu to switch or open a wiki page.

M-x org-wiki-switch

• 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

• M-x org-wiki-helm-frame - Open a wiki page in a new frame.

M-x org-wiki-helm-read-only

• M-x org-wiki-helm-read-only - Open a wiki page in read-only mode.

M-x org-wiki-make-page

• M-x org-wiki-make-page - Creates a new wiki page asking the user for the page name.

M-x org-wiki-close

• M-x org-wiki-close - Close all wiki pages, kill all *.or buffers belonging to wiki directory.

M-x org-wiki-close-image

• Close all org-wiki image/picture buffers.

Insert Hyperlink to wiki pages or asset files

M-x org-wiki-insert-link

• M-x org-wiki-insert-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-header

• =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

• 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 format wiki-asset-sys:CurrentPage;AssetFilename.pdf.

Asset files / Attachments

Commands to open page’s asset directory

M-x org-wiki-assets-dired

Open page’s asset directory in Emacs dired mode.

M-x org-wiki-assets-open

• M-x org-wiki-assets-open - Open asset directory of current page with system’s default file manager.

M-x org-wiki-assets-helm

• M-x org-wiki-assets-helm - Select a wiki page and open its assets directory.

Commands to insert hyperlink to files

M-x org-wiki-asset-create

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

• 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

• 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:

• pyscript.py

M-x org-wiki-asset-insert-image

• 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]]

M-x org-wiki-asset-insert-block

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:

• File: file:Smalltalk programming/extendingClasses-number1.gst

Number extend [
        inv [ 1.0 / ^self
        ]

        neg [ - ^self
        ] 
]

Commands to open files directly

M-x org-wiki-asset-find-file

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

M-x org-wiki-asset-find-sys

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.

Commands to Download Files

M-x org-wiki-asset-download-insert1

• 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:

1. User is in the page Linux that corresponds to the file <org-wiki-location>/Linux.org
2. User copy the url https://inst.eecs.berkeley.edu/~cs61b/fa13/ta-materials/unix-concise-ref.pdf
3. User enter M-x org-wiki-asset-download-insert1
   1. Confirm the first prompt asking for the url. The suggested url is the copied url.
   2. Confirm the second prompt asking the file name. The suggested name is unix-concise-ref.pdf
4. 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

• M-x org-wiki-asset-download-insert2 - Similar to M-x org-wiki-asset-download-insert1, however it inserts a hyperlink of type file:<org-wiki-page>/<file-name>.

Example:

1. User is in the page Linux and copies the url: http://i1-linux.softpedia-static.com/screenshots/htop_1.jpg
2. User enter the command M-x org-wiki-asset-download-insert1 and answers all prompts.
3. It will insert the hyperlink bellow at point.

file:Linux/htop_1.jpg

Open wiki directory

M-x org-wiki-dired

• M-x org-wiki-dired - Open the wiki directory in Emacs dired-mode showing only *.org files.

M-x org-wiki-dired-all

• M-x org-wiki-dired-all - Open the wiki directory in Emacs showing all files.

Export all pages to html

M-x org-wiki-export-html

• 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

• M-x org-wiki-index-html - Open the index page exported to html in the web browser.

Search

• 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.

Copy Commands

• 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.html
• M-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.

M-x org-wiki-backup-make

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.

M-x org-wiki-backup-dir

To open the backup directory run M-x org-wiki-backup-dir.

Utilities

Insert greek letters, math, physics and currency symbols

The command M-x org-wiki-insert-symbol allows inserting Greek letters, math and physics symbols by providing a helm menu where the user can select or type the name of the symbol to insert it at current point. It can be used to quickly type equations and formulas and can be pasted in email, forums, source code and etc.

Examples of symbols of provided:

• α (alpha), β (beta), Σ (upper case sigma), σ (sigma)
• π = 3.1415 -> Circle Area = π.r^2
• ∂f/∂x + ∂f/∂y + ∂f/∂z = 0
• ∛27 = 3.0, √100 = 10.0
• 200.00 £ GBP, 3000.00 ¥ (Yuan, aka Reminbi)
• Fractions ¼, ⅓, ⅑

Insert org-mode code blocks, tables, quotes and etc.

This command makes easier to insert common org-mode code templates for code blocks, quote blocks, latex equations, table, example blocks and so on.

• $ M-x org-wiki-insert-block

Example:

If the user select the template equation it will insert at current point a block for latex equations:

\begin{equation} 
\end{equation}

If the user select the template table, it will insert a table with 2 rows and 3 columns.

|   |   |   |
|---+---+---|
|   |   |   |
|   |   |   |

If the user select the template Python code block, it will insert:

#+BEGIN_SRC python 

#+END_SRC

Insert math formula, latex template, equations, greek letters and etc.

The command M-x org-wiki-insert-latex allows writing Latex formulas, Greek letters and math symbolls quickly. It provides a helm menu where the user can type, search and insert Latex formulas at point.

Example:

Web Server

• 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.

Panel - org-wiki-panel

• M-x org-wiki-panel - This command provides a command panel that can execute actions just typing few keys like magit or dired buffer.

Menu

• M-x org-wiki-make-menu Shows a menu with org-wiki functions and command reminders.

Backup Commands

Backup Settings

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")

Paste Image

Overview

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

• 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

• 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

Alias Commands

• 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.

Tips and tricks

Shortcuts

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)

Screenshot tools

Linux

• Shutter - Feature-rich Screenshot Tool
• Shutter - Advanced screenshot tool for Ubuntu ! - YouTube

Windows

• How to use the Windows Snipping Tool

Bookmarklets

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:

• Creating a Simple Bookmarklet - YouTube

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 Url

Javascript 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:

• https://github.com/caiorss/bookmarklet-maker

and

• https://caiorss.github.io/bookmarklet-maker/

Equation Rendering in Web browsers

• TL;DR
  • Formulas are displayed faster in Firefox.
  • Mathml is the best Mathjax formula rendering.

MathJax Latex rendering is slow in Chrome browser and in its open-source relative Chromium browser. An alternative way to render formulas faster is set MathJax to use mathml rendering, but it is not well supported by all browsers such as Chrome e Internet Explorer. Google has also dropped mathml supoort in new versions of the browser.

So, until now, the best browser for fast displaying formulas and equations is Firefox.

Documentation related to Formulas and Latex backend:

• Math formatting in HTML export - The Org Manual

Online Equation Editors

• http://www.codecogs.com/eqneditor
• https://www.latex4technics.com/
• https://www.mathcha.io/

See also:

• CNET - Google subtracts MathML from Chrome, and anger multiplies

Use the best tool of the job

Store, organize, and index documents, citations and etc.

Those who need to store and index a large amount of any type of files and documents will be better served with Zotero.

• https://www.zotero.org/

Write very formal thesis, paper, books, manuals and etc …

For this case one of the best tool is the open source software Lyx that allows creating latex documents in a graphical way, in a similar fashion to Microsoft Word and other word processors. It also has an equation editor.

• https://www.lyx.org/

Modify it

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

TODOLIST

• [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

org-wiki's Issues

Can't search

I'm currently using Emacs Version 25.1 (9.0) installed via MacPorts.

I made a link in the index.org file at ~/org-wiki and put some content there. But whenever I try to search (with org-wiki-search or org-wiki-keywords) I get the following error:

grep-expand-template: Wrong type argument: stringp, nil

Allow to customize the file extension

Nice package.

Would be nice to be able to configure the file extension (for example, to be able to use .txt files)

Thanks

Issue with org-wiki-paste-image

First I have to say that I like your package very much! I hope to see it on MELPA soon.

I've been experiencing issues with org-wiki-paste-image . I always have to enter the whole path to the file, because in helm not the org-wiki-location but the location of my emacs-binaries is prepended to dir. For example when I try to paste an image to index.org, the helm-promt for the filename looks like this:

I do think I have a fix though. It works for me, but I am not a programmer, so I can't tell if it's a very good one: The docstring of read-file-name says, that one should provide an absolute directory name for DIR. In line 793 of org-wiki.el, dir is only passed the name of the directory, not the whole path. I have modified the line to:

   `(file (read-file-name "Image: " (concat org-wiki-location "/" dir))))`

Now read-file-name sees the full directory name and it works for me.

Would it make sense for you to make that change to org-wiki.el?

Thanks and best regards,
Stefan

Feature request: A tag code in file name based knowledge management system

I am using org files to keep notes with
https://github.com/abo-abo/plain-org-wiki/blob/master/plain-org-wiki.el
As time goes by, the file is getting bigger and bigger, which bring a lot of duplication, also makes auto save and backup files big and cause a lot more extra disk io, not good for the hard drive. :-)

So I am thinking about a purely simple tag base system:

1. a tag datafile: (tag . value), tag is a string without blank characters, value is a numeric value, eg. ((linux . 10) (debian . 2) (emacs . 3))
2. a notes folder: note file name is the joined string of tag values sort in ascending order, eg. a note with both linux and debian tag should be named 2-10, just plain org files without the .org extension

The search operation is simple too:

1. a search tag function: search tag datafile with keywords separated by space to find all the matched values, each single tag uses fuzzy matching, eg. search for "dbian linx" will retrun files match the glob pattern *2*10* , but the file name list is converted to tag names like "1. debian linux 2. debian emacs linux", you can select the file to open with number, or you can goto 2.
2. open them all in a temp buffer with all files inserted using https://github.com/whacked/transclusion-minor-mode , the nice thing is you can view all of them in one buffer, and maybe cut and paste from one file to another

The tag manipulation is very simple:

1. Delete a tag: remove the tag from the datafile, replace the tag value from all notes files names, move file name the same as tag value to trash and warn the user. save the tag value to a file named available-tag-values.
2. Add a new tag: search the tag datafile if no match, create a new tag value and associate to the tag name, the value in available-tag-values will used first.
3. Add a tag to the current note: rename it to a name include the tag value
4. rename a tag: just rename it in the tag datafile.

This will break big notes files into smaller ones and does not affect the viewing thanks to org translusion. However, I only have a very limited knowledge of emacs. I am looking forward to hear your opinion and on how to bring the feature to this repo.
Thank you!

package on MELPA?

Could you make org-wiki avaiable on MELPA?

use org-ids for linking wiki files

At the moment I use org-ids for my links so that later I can freely adjust my headlines and file locations. I have about 1 million words among 250 files and everything works as expected.

I like the features of org-wiki and have tried it out for a while but I haven't found a way to use wiki-links with org-ids. Is that possible? Did I miss something obvious?

Thanks for this useful software.

PS: Do you know these essays about personal wikis in general http://connectedtext.com/manfred.php and http://luhmann.surge.sh/communicating-with-slip-boxes ? I thought they were quite interesting.

Can I convert my org-mode wiki to org-wiki? And how can org-wiki access files in subfolder?

• MX-Linux 17
• Emacs 26.1.50 (graphical)
• init.el
• complete environment
• org-wiki configuration:

(require 'org-wiki)
(setq org-wiki-location-list
      '(
	"/~/orgwiki"  ;; First wiki (root directory) is the default.
	))
;; Initialize first org-wiki-directory or default org-wiki
(setq org-wiki-location (car org-wiki-location-list))

I have a wiki that I created using orgmode. I tried using org-wiki with it, but it cannot see the subdirectories, and only lists the files that are in the same dir as index.org. I also tried creating a new wiki, and put some files in there, and org-wiki could not see them. Does org-wiki support files in different places, or I should just put everything in the same folder?

HTML Export

Is it possible to use other export backends for org-wiki for html? I was hoping to use ox-twbs if possible. One thing I've noticed though is that the links don't export well. A file named 'file.org' will export to 'file.html' but the link will only be to 'file' without the 'html' suffix.

How can I go back in a hierarchy of wiki pages?

Say my index page links to page A and page A links to page B and I follow the links in this order, is there a easy shortcut to get to the previous wiki page, like from B back to A and from A back to the index?

Like pushing and popping visited links on and off a stack.

Thanks!

Is there anything like backlinks?

Backlinks known from wikis available in org-wiki?

Would you like to add meta info in the header which can use melpa recipe to install your package?

I am using Spacemacs and try to install your package through melpa recipe. But it failed because of lacking of header info in your package.

Do you have plan to add the meta info later which can make the install process work?

no syntax highlight when export html

I cannot get org-wiki-export-html to highlight code block. If I export the page individually using org built-in, then the syntax highlight shows up.

NOTE: i have htmlize installed

Automatic mutual (2-way) links between files?

Dear Caio,

I find org-wiki really intriguing and thinking about adopting it. Thank you very much!

I have a question: On your screenshots you have lines like in Linux.org "Related: Bash Script, Nix, ..."
Would it be hard to make the adding of links to be mutual between the files, i.e. whenever I link to a target file A from a file B, can the file A get a automatically a back-link to file B too?

For example: I'm in Linux.org, I create from there a new link Ubuntu.org (which maybe exists already), I'd like Ubuntu.org to automatically have a Related: Linux link in it.

What is your opinion?

Best wishes,
Robert

Is it possible having different link types, like 3, parent, child, friend?

The different link types could be represented by different colors in emacs buffer, if set somehow in .emacs

The idea has its origin in TheBrain or org-brain, but having a similar feature directly in org-wiki would open up new possibilities. Having at least those 3 new link categories helps in structuring your navigation travels within your notes, so you could always walk into more general direction, just by following parent links, only, and the opposite in child direction, friend links would be kind of like the normal links which org-wiki has now, where its hierarchical location is somewhat free to current concept.

Option to create new folder for every wiki page creation?

Great package! I am using it to write a labbook (will write a blogpost about my setup eventually).

Do you think that there is a way to create a folder containing the .org file for every new wiki page? If I was to do this, where do I start to modify the code to do so?

Thanks in advance!

Links to headers

The wiki link type allows linking to another wiki page, but often I want to link to a specific header in another page. Is this possible? Is it something that would be easy to add?

Can't intall org-wiki by Method 1: async-20181224.454.tar: Not found

I am try to install org-wiki by method 1(bootstrap installer). I got following error:
https://melpa.org/packages/async-20181224.454.tar: Not found

Error after install running org-wiki-index

I have created ~/org/wiki -- this exception is thrown. Seems to effect anything that attempts to read a file. I installed via the bootstrap method and then tried a manual install. No difference.

Debugger entered--Lisp error: (wrong-type-argument stringp nil)
file-name-as-directory(nil)
org-wiki--page->file("index")
org-wiki--open-page("index")
org-wiki-index()
funcall-interactively(org-wiki-index)
call-interactively(org-wiki-index record nil)
command-execute(org-wiki-index record)
execute-extended-command(nil "org-wiki-index" "org-wiki-index")
funcall-interactively(execute-extended-command nil "org-wiki-index" "org-wiki-index")
call-interactively(execute-extended-command nil nil)
command-execute(execute-extended-command)

Is there any way for automatically recognizing if a page exists

For example, if I am writing a page about the sun.

The Sun
The sun emits photons.

and I already have a page called "photons", is there any way for org to automatically link the word photon to the page?

Backward sync

Would it be possible to implement a feature similar to synctex for LaTeX?

The first step would be to provide a mechanism which sends you back from a wiki html site from your browser to the corresponding org file in emacs.

In a second step it would be great, if it sends it also to the line in the source file which matches the current line in the html document.

Maybe the new emacs web browsing feature from emacs 25 would be a starting point. However it would also be great to make this work with arbitrary browsers. For example by inserting a corresponding "org-file" button which is implemented a html template.

Create note with org-wiki-helm

I would love to be able to create notes, directly from org-wiki-helm. In this way, the user would first use org-wiki-helm to search for the note. Then failing that, he would hit [RET] to automatically create the file.

This would be similar to how org-velocity and deft work... except that it relies on helm, which of course makes it all that much better! :)

Github can handle Org pictures

It just needs the right syntax, for example. You must enter relative path, so Github can see it:

[[file:images/org-wiki-index.png][file:images/org-wiki-index.png]]