Tutorial
Introduction
This is an introduction to the org-mode based wiki engine. I created this so that I could:
- both modify and compile org-mode source from the command-line using emacs
- allow non-emacs users to collaborate by allowing editing of org-mode source via the web
Note: While Emacs is the no-brainer choice for editing, org-mode syntax is remarkably simple, enough so that it is not too hard to edit without Emacs for simple uses. In fact, it was designed this way. Emacs just makes the tedious stuff a lot less tedious.
This wiki engine has a few advantages over other engines at this point:
- It is built around org-mode, which leverages the Emacs text editor.
- All source files are complete in themselves, meaning that the
entire org source of this wiki is contained in a directory
organd can be edited using Emacs without using the wiki. - Because of the above, you can use version control on your wiki files, and easily transfer/mirror the entire wiki.
- The wiki is only a single php file,
index.php. - By leveraging R and org-mode, you can programmatically generate complex reports
- Simplied syntax for creating executable reports, which can be passed parameters and files as input from the browser or from the command-line.
Usage
Editing
Use the edit button at the top of the page to view the source of this page in a textarea below the HTML output. Edit with your favorite editor (Note: I recommend using conkeror and C-i to edit in emacs) and save when done.
Creating
To create a page, make a org-mode styled link to it, i.e.
[[file:new_page.html][New page]]
If you to link to the .org file, it will still convert the extension to .html on export. The following creates an identical HTML link to the above, but conveniently still lets you visit the .org file at your cursor in emacs using C-c C-o.
[[file:new_page.org][New page]]
Alternatively, you can also navigate to new_page.html in the address bar and start editing.
Listing all pages
Visit index.html for any directory and an index will be displayed which displays all viewable pages. If you are currently logged in, it will display links you have edit permissions for in red.
Markup
This is only the basics. For a complete reference, please visit the org-mode manual.
Font
The basic markup is as follows:
*bold* /italic/ =code=
bold
italic
code
Sections
Create sections and subsections by using any number of asterisks (*) before the section heading.
Tables
The markup for tables is as follows:
|1|2| |3|4|
Result:
| 1 | 2 |
| 3 | 4 |
Links
Links are surrounded with braces, but any link that matches the normal URL regular expression pattern (begins with http://) will be converted to a link automatically. To name a link, surround the URL, followed by the name, both with braces and surround the entire structure with braces. Edit this page to see an example.
LaTeX
org-mode has no problem handling LaTeX in HTML (and caching the images): \(x=2\)
R
While unsafe, you can allow execution of R blocks within the wiki engine. This allows for generating Sweave-like reports. By combining optional caching1, parallel compilation2, and parallel execution3 generating pages using R in org-mode is the fastest way to generate custom reports for your data analysis needs.
#+CAPTION: Test plot
[[file:out/tutorialplot.png]]
#+HEADER: :width 600 :height 600
#+BEGIN_SRC R :session :file tutorialplot.png :results graphics :exports none
par(family="serif")
eval({
plot(rnorm(100), rnorm(100))
cat("\n#+END_HTML\n");})
#+END_SRC
Test plot
Quotes
Quote blocks, which usually contain a smaller amount of content, are styled to emphasize the content, slightly.
Something I've found useful and implemented are quote blocks.
They can even handle multiple paragraphs, with latex:
\(sum_{x=1}^{10}{x} = 55\)
The above is an example of a quote block.
Future improvements
Please follow the todo list for planned features. Note that org-mode is in active development, so expect there to be bugs in both the wiki and in org-mode. Fortunately, org-mode is an open source project, as is Emacs, so please contribute!