jemdoc – cheatsheet
Basic formatting
/italics/
*bold*
+monospace+
- is a hyphen (-)
-- is an en-dash (–)
--- is an em-dash ( — )
... is an ellipsis (…)
~ is a non-breaking space ( )
# begins a comment, for the remainder of the line
\C is ©
\R is ®
\M is ·
‘singly quoted text’ is written `singly quoted text'
“doubly quoted text” is written "doubly quoted text"
jemdoc's apostrophes are converted automatically from jemdoc's input
the sequence \n
forces a manual line breakparagraphs are separated by blank lines
$inline LaTeX equation$
\( LaTeX equation on its own line \)
#s (and only #s) must be quoted in URLs
Blocks
~~~ {Optionally empty title}{Optionally empty highlight mode} Code block with monospaced text. ~~~
Omit the second pair of braces in the first line of the block (or omit the whole first line altogether if you don't want a title) and you will get an information block. All the usual conventions apply in here.
Headings and lists
Headings are defined by starting a line with =.
= Heading level 1
== Heading level 2, etc.
Lists are defined with - for bulleted lists, . for numbered lists and : for lists of definitions. Here is some code and the resulting list:
- Bullet level one -- Bullet level two . Number level one .. Number level two .. Number level two (again) : {jemdoc} light markup : {asciidoc} a great alternative, but more complicated
Bullet level one
Bullet level two
Number level one
Number level two
Number level two (again)
- jemdoc
light markup
- asciidoc
a great alternative, but more complicated
Preventing matches
a literal backslash (\) is written \\\\
the literal characters /, *, + and ~ and # are written \/, \*, \+, \~ and \# to avoid the above formatting
\... avoids an ellipsis
-\- avoids an en-dash
-\-\- avoids an em-dash
\` gives a back-tick (`)
\' gives an ordinary single quotation mark (')
\" gives an ordinary double quotation mark (")
Other stuff
{{html text}} will insert html text directly into the output document without performing any substitutions. (This is for inline escaping; use raw blocks for larger amounts of html.)
%quoted tt% is an alias for +{{quoted tt}}+. It's not quite as robust, so use +{{plus signs with double brace blocks}}+ if you run into problems with some characters.
{\{text}\} will perform replacements and insert {{text}}.
These are some extended syntax options that may come in useful.
Left aligned image blocks
As seen here, for example, left-aligned image blocks place an image and allow ordinary jemdoc marked-up text to flow around the right-hand side.
~~~ {}{img_left}{FILENAME.IMG}{alt text}{WIDTHpx}{HEIGHTpx}{IMGLINKTARGET} Ordinary jemdoc markup goes here. ~~~
All arguments may be left blank, though you should specify an image filename, and alt text should be descriptive for reasons like those given by Wikipedia.
Raw blocks
When placing large amounts of raw html, you should use a raw block instead of {{inline html escaping}}. As well as cleaner syntax, raw blocks will avoid having <p> tags in the wrong places.
~~~ {}{raw} Any text here will be copied straight to the output file without processing. ~~~
Other character sets
Here's a quick example of how to include text in a language with a different character set.
To include Korean (한국말), use something like this:
{{<span lang="ko" xml:lang="ko">}}한국말{{</span>}}
(Let me know if you need better support for your language.)
Including other files
The line
#include{otherfile.jemdoc}
will include the contents of otherfile.jemdoc as if the contents were actually in the ordinary input file (that is, with full jemdoc substitutions). The line
#includeraw{otherfile.html}
will copy the contents of otherfile.html verbatim to the current position in the output file (that is, without any jemdoc substitutions).
jemdoc – html changes
jemdoc has a built-in default configuration. This configuration includes the particular html tags used when producing html. If you wish to adjust the html that jemdoc produces, you can provide a configuration file to override the built-in defaults.
Example html change
Suppose you wanted to add Google Analytics tracking to your website. That requires adding a short section of html before the </body> tag.
First, find out which block needs to be changed by using
jemdoc --show-config
This prints the default html configuration. From this, the relevant configuration block (the one which includes the </body> tag) has a title [bodyend], and looks like
[bodyend] </body> </html>
Create a new file mysite.conf, say, and put a new [bodyend] block inside it. The new file looks like this:
[bodyend] <script src="http://www.google-analytics.com/urchin.js" type="text/javascript"> </script> <script type="text/javascript"> _uacct = "UA-0000000-0"; urchinTracker(); </script> </body> </html>
Include your new configuration file, with the -c option (more details here):
jemdoc -c mysite.conf index.jemdoc
This will pull in the new [bodyend] block from mysite.conf, but otherwise work as before.
jemdoc – latex equations
jemdoc includes support for LaTeX equations. LaTeX source embedded in jemdoc files is processed by calling latex and dvipng (which must both be available for this feature). Resulting PNG images are then placed on the web page. Equations are typeset using pure LaTeX.
jemdoc equation support relies on several pieces, any of which may break. No guarantees! Support may be limited.
Inline equations
The conjugate function \(f^\star(y) = \sup_{x \in X}(y^Tx - f(x))\) appears here inline, and is in the variable \(y\). Dollar signs ($) surround the LaTeX equation in the jemdoc source.
The sample function $f^\star(y) = \sup_{x \in X}(y^Tx - f(x))$ appears here inline, and is in the variable $y$.
Equations on separate lines
To render an equation on its own line, use backslash-escaped round brackets (\( and \)). For example, the identity
\[ (I + XY)^{-1} = I - X(I + YX)^{-1}Y \]
is typeset on its own line. Yes, round brackets instead of square brackets — this is to avoid a conflict with ordinary square brackets that are escaped to avoid being a link. Sorry.
The identity \( (I \+ XY)^{-1} = I - X(I \+ YX)^{-1}Y \) is typeset on its own line.
Here, the line breaks (and other whitespace) are ignored. As always, the exact formatting details can be adjusted using CSS.
Notes
The baseline is carefully adjusted. The sequences m\(m\)m and y\(y\)y (m$m$m and y$y$y), for example, should be neatly aligned (modulo bad browsers).
Definition by cases will work as expected, for example, \(f(x)\), where
\[ f(x) = \left\{ \begin{array}{ll} 3, & x \leq 0 \\ 5, & x > 0. \\ \end{array}\right. \]
A random inequality might look like \(3x + 2y^{4k + 6} \geq z\).
This page takes about 0.7 seconds to process on an average machine, including making all the equations from scratch.
There are several configuration options for equations. They are detailed on the modelines page.
Link Example
You can control the behavior of a link: by default the link opens in a new web broswer tab, but by putting a slash (/) character at the beginning of the link address you can make it open in the current web broswer tab.
For example, [mathjax.html] opens in a new web broswer tab, but [/mathjax.html] opens in the current web browser tab. The link opening in a new tab is useful for linking an external website (like http://www.google.com), whereas the link opening in the current tab is useful for liking your jemdoc page (such as the page linked as a jemdoc menu item on the left panel).
Unlike the link in the main text, a jemdoc menu item link on the left panel opens in the current tab by default, because you want to stay in the same tab while navigating menu items. However, you can override this default behavior and make it open in a new tab by putting a backslash (\) character in the beginning of the link of the menu item. This is useful when putting an external website as a menu item. See this usage in “Open in New Tab” menu item on the left panel, which is defined in MENU file.
MathJax Example
In this modified version of jemdoc, a LaTeX equation block can be typed in as
\[ \nabla \cdot \mathbf{D} = \rho_f\\ \nabla \cdot \mathbf{B} = 0,\\ \nabla \times \mathbf{E} = -\frac{\partial\mathbf{B}}{\partial t}\\ \nabla \times \mathbf{H} = \mathbf{J}_f - \frac{\partial\mathbf{D}}{\partial t}. \]
You can also align equations using LaTeX's aligned block:
\[ \begin{aligned} \nabla \cdot \mathbf{D} &= \rho_f\\ \nabla \cdot \mathbf{B} &= 0\\ \nabla \times \mathbf{E} &= -\frac{\partial\mathbf{B}}{\partial t}\\ \nabla \times \mathbf{H} &= \mathbf{J}_f - \frac{\partial\mathbf{D}}{\partial t}. \end{aligned} \]
To number the equation block, wrap the equations with LaTeX's equation block:
\[ \begin{equation} \begin{aligned} \nabla \cdot \mathbf{D} &= \rho_f\\ \nabla \cdot \mathbf{B} &= 0\\ \nabla \times \mathbf{E} &= -\frac{\partial\mathbf{B}}{\partial t}\\ \nabla \times \mathbf{H} &= \mathbf{J}_f - \frac{\partial\mathbf{D}}{\partial t}. \end{aligned} \end{equation} \]
Instead, you can use LaTeX's align (not aligned) block to number the individual equations:
\[ \begin{align} \nabla \cdot \mathbf{D} &= \rho_f\label{eq:D}\\ \nabla \cdot \mathbf{B} &= 0\label{eq:B}\\ \nabla \times \mathbf{E} &= -\frac{\partial\mathbf{B}}{\partial t}\label{eq:E}\\ \nabla \times \mathbf{H} &= \mathbf{J}_f - \frac{\partial\mathbf{D}}{\partial t}\label{eq:H} \end{align} \]
You can also type inline equations as \(A x = b\). Referencing equations is done as Eqs. \(\eqref{eq:E}\) and \(\eqref{eq:H}\).
jemdoc – add a menu
jemdoc provides an easy way to add a ‘menu’ like the one you see at the left of this page. You should create a file called MENU, for example, in the current directory. This website's MENU looks something like this:
jemdoc home [index.html] download [download.html] revision history [revision.html] contact [contact.html] user's guide cheat sheet [cheatsheet.html] using [using.html] goodies add a menu [menu.html] other stuff [stuff.html]
To use the menu, start the first line of each source file with a special comment like this one:
# jemdoc: menu{MENU}{index.html}
(Replace index.html with the name of the relevant html page.) This will add a menu from the file called MENU, and underline and darken the menu entry corresponding to index.html.
Relative paths
Optionally, include a prefix which instructs jemdoc where the root of the menu is located relative to a particular page.
# jemdoc: menu{MENU}{pageinsubdir.html}{prefix}
A note on menu widths
jemdoc will create menu entries that do not wrap. If you have a particularly long title, or menu item, insert manual linebreaks using \n in your MENU file. Multi-line menu items will (by default) have their second and subsequent lines slightly indented.
jemdoc – modelines
jemdoc includes a mechanism for specifying options inside a source file. It is called a modeline, after the same concept in vim. To use a modeline, start your jemdoc source file (on the first line) with the exact string # jemdoc:. Follow this string with one or more modeline options, separated with commas (and any amount of white space).
Multiple modelines can be included if they are all at the beginning of the file, and start with the same string. The modeline can be omitted altogether.
Modeline options
General
menu{MENUFILENAME}{CURRENTFILENAME}
Place a menu at the left of the page.nodefaultcss
Clear the list of CSS stylesheets included by the page.addcss{CSSSHEET}
Explicitly include an additional custom CSS stylesheet.addjs{scriptname}
Explicitly include the javascript file scriptname.js.fwtitle
Makes the page title full width so the menu and the body lie underneath the title.title{NEW TITLE}
Manually sets the titlebar text to NEW TITLE.
Extras
analytics{ANALYTICS KEY}
Adds Google Analytics support. The key is typically in the form UA-0000000-0. Sign up for Google Analytics here.
Footers
notime
Withhold the time from the ‘Page generated’ footer.nodate
Withhold the date and the time from the ‘Page generated’ footer.showsource
Include a link, in the footer, to the jemdoc source.nofooter
Withhold the footer altogether (overrides the above options).
Equations
noeqs
Disable LaTeX equation support.eqsize{SIZE}
Adjust the size of the equations (default 130).eqdir{EQDIR}
Adjust the equation directory (default eqs).noeqcache
Disable equation caching.addpackage{LATEXPACKAGENAME}
Includes support for LATEXPACKAGENAME when compiling the equations.
Examples
# jemdoc: menu{MENU}{modelines.html}, showsource
# jemdoc: nodefaultcss, addcss{custom.css}
# jemdoc: nodefaultcss, addcss{custom.css}{another.css} # jemdoc: showsource, addcss{yetanother.css}
jemdoc – tables
jemdoc includes preliminary support for tables.
~~~ {}{table}{TABLENAME} first entry | another entry || as many rows | as you like || bottom row | last entry ~~~
TABLENAME should either be replaced with a name — which becomes the table's css id — or be omitted.
Notes
There is no need to line up the | symbols. Extra whitespace is ignored.
The last row does not need a terminating ||.
Individual tables can be customised by replacing TABLENAME with a unique name, and using custom css. For example, within a css file, #countries { background: gray; } will make the background of the countries table gray.
Rows in a table are numbered sequentially for easy formatting with css. For example, to make the entries in the first row of a table called countries bold, use #countries tr.r1 { font-weight: bold; }.
Example
country | population | people per square km |
Canada | 33 million | 3.2 |
中华人民共和国 | 1300 million | 140 |
Kingdom of Denmark | 5.5 million | 130 |
New Zealand | 4.3 million | 15 |
United States of America | 300 million | 31 |
Underscore Example
Like bold and italic, underscore can be used for emphasis in this modified version of jemdoc. Useful for highlighting different parts of a bibliography item as:
1. First Author, Second Author, and Corresponding Author, “Amazing Paper,” High-impact Journal, vol. 1, pp. 1–10 (2014).
jemdoc – running jemdoc
Make sure Python is installed, put jemdoc in your path somewhere, type in your file, and run
jemdoc index.jemdoc
This will use a default configuration for the html elements, and create an index.html.
Even simpler, you can omit the extension, and jemdoc will still process the index.jemdoc file, as in
jemdoc index
CSS
You will need to provide a CSS file on your server. By default it should be called jemdoc.css. Here is an example jemdoc.css file: download it and place it in the same directory as your html files. (Or customize it, or start from scratch!)
Change the configuration
To choose a different output file, use -o:
jemdoc -o html/index.html index
You can specify a different output directory with -o:
jemdoc -o html/ index
This will instead output to html/index.html.
To change the html configuration (details here), use -c:
jemdoc -c mysite.conf index
Command line options may be combined. For example, the following command will use mysite.conf, reading syntax from index.jemdoc and outputting to html/index.html:
jemdoc -c mysite.conf -o html/ index
Other command line options
To check which version of jemdoc you are using, run the command
jemdoc --version
To get simple command-line help, you can run jemdoc without arguments, or
jemdoc --help
To show the html configuration (details here), run
jemdoc --show-config
Visitor Stats.