ReMarkable is a simple set of text conventions for writing article content in plain text that is translated into the corresponding HTML by the ReMarkable script.
ReMarkable is based on the design of Markdown by John Gruber.
The code is inspired by concepts from PHPMarkdown by Michel Fortin, but is all original code written by Kroc Camen of Camen Design, except for “toTitleCase”, written by David Gouch in Javascript and ported to PHP by Kroc Camen.
Use ReMarkable to write online blog / news articles using just plain text, either offline or as part of a CMS, and ReMarkable will convert it to tidy, human-readable HTML.
ReMarkable is designed for trusted authors who wish to cut down the amount of HTML they have to write so that they may concentrate on their text more. ReMarkable should never be used to provide a means of public / anonymous users to make comments, or submit any content on a website. ReMarkable is not designed to solve any trust problems. It is easy to insert Javascript and other potential security threats into the HTML ReMarkable outputs.
If you want to use ReMarkable in a public or untrusted context, it is up to you to securely filter the output of ReMarkable and to do the necessary security testing yourself. I will not take any responsibility for security breaches or damages caused by use of ReMarkable.
ReMarkable is not for sloppy coders. It outputs only clean, semantic HTML. It does not include any HTML class names or IDs of its own, and you are expected to know how to use CSS to deal with that. Any excuses that you need class names will be ignored.
ReMarkable is a PHP function. To use it, first copy the ReMarkable
folder to your
web app and include the file in your code.
Then call reMarkable, passing the desired text to be
transformed into HTML.
echo (reMarkable ('I’m _emphasising_ this point *strongly*.'));Returns:
I’m <em>emphasising</em> this point <strong>strongly</strong>.
An optional second parameter can be given, setting the number of tabs to indent the whole output by.
This would be useful where you are templating HTML and would like to indent the output to match the
template.
echo (reMarkable ("The quick brown fox¬jumps over the lazy dog.", 1));Gives:
The quick brown fox<br /> jumps over the lazy dog.
The third optional parameter specifies a character limit to word wrap the output.
This defaults to 125 (the viewport size of a Firefox window at 1024×768). Set to 0 (or false to switch
word-wrapping off).
Word-wrapping ensures clean and readable HTML. The output of ReMarkable is designed to be human-readable.
The fourth optional parameter “base_path” sets the relative or absolute path of web root, where
relative <img> src URLs
resolve from. For a demonstration of the base_path parameter, see the images section.
ReMarkable can also be called from the command line, so that you may use it from other scripting languages or as part of a batch process.
To call ReMarkable, pass PHP the location of the ‘remarkable.php’ file, the location of the ‘.rem’ file you want processed, and the optional parameters, just as with the function call above.
php /path/to/remarkable.php /path/to/file.rem 0 125 "../"
The result is written to stdout.
Every blank line is the start of a new paragraph.
The quick brown fox jumps over the lazy dog. The cat then sat on the mat.
Which would be converted into the following HTML:
<p>
The quick brown fox jumps over the lazy dog.
</p><p>
The cat then sat on the mat.
</p>
As per HTML rules, single line-breaks and other whitespace is ignored.
For example, this:
The quick brown fox jumps over the lazy dog. The cat sat on the mat.
Would actually display as a single line of text.
If you want to force a line-break in the HTML output (<br />), you may end a line
with a space and underscore.
The quick brown fox jumps over the lazy dog. _ The cat sat on the mat.
Alternatively you can insert a break using the “not” char “¬”.
The quick brown fox¬jumps over the lazy dog.
These kinds of break do not have to be at the end of a line, and you can use more than one in a row.
There are two ways to do headings.
The first is atx style:
# H1 # ## H2 ## ### H3 ### ... ###### H6 ######
Unlike atx the closing hashes are not optional. Headings cannot be indented.
Like PHPMarkdown, you can include an ID, like so:
# Title # (#title)
Becomes:
<h1 id="title">Title</h1>
The second way is using a line of equals or dashes.
For example:
Second Level Heading ==================== Third Level Heading ------------------- Paragraph…
The line can be any length and doesn’t have to match the length of the text above.
The above example produces:
<h2>Second Level Heading</h2>
<h3>Third Level Heading</h3>
<p>
Paragraph
</p>A blank line after a heading is optional, paragraphs will still be created.
IDs can be added to these headings similar to before,
Second Level Heading (#title2) ============================== Third Level Heading (#title3) -----------------------------
These styles of headings are used for H2 and H3 as these are the most common headings. H1, though important, is usually only used once per article as the title for that article, and in many cases that text is stored as a separate database field and isn’t included in the article text for processing.
All headings will be automatically Title Cased
by ReMarkable.
For example:
## the thin and thick of it ##
Is correctly title-cased as such:
<h2>The Thin and Thick of It</h2>To avoid this behaviour, write a heading using HTML instead of ReMarkable syntax.
ReMarkable can create a table of contents for you. In order to do this, you need to include an ID on each heading you want to be in the table. A special “TOC” marker in the text indicates where the table of contents will be placed. For example:
# Article # &__TOC__; ## Section 1 ## (#s1) ### Section 1.1 ### (#s1-1) ### Section 1.2 ### (#s1-2) #### Section 1.2.1 #### ## Section 2 ## (#s2)
Produces:
<h1>Article</h1>
<ol>
<li>
<a href="#s1">Section 1</a>
<ol>
<li><a href="#s1-1">Section 1.1</a></li>
<li><a href="#s1-2">Section 1.2</a></li>
</ol>
</li>
<li><a href="#s2">Section 2</a></li>
</ol>
<h2 id="s1">Section 1</h2>
<h3 id="s1-1">Section 1.1</h3>
<h3 id="s1-2">Section 1.2</h3>
<h4>Section 1.2.1</h4>
<h2 id="s2">Section 2</h2>
Note that Section 1.2.1
is not included in the table of contents because it does not have an ID.
There are two other things to note about the automatic table of contents.
An <hr /> element can be inserted using three asterisks separated by spaces, on a line.
There can be any amount of white space (or none) before the asterisks, but none after.
* * * Or * * *
Italic and bold (emphasis and strong) are rendered by simply placing an underscore or an asterisk either side of the desired span of text.
I’m _emphasising_ this point *strongly*.
Yields:
I’m <em>emphasising</em> this point <strong>strongly</strong>.Both emphasis and strong can be combined.
Small text represents either side-text or small-print (like legal information).
It can be used inline:
(for example, as an editor’s comment)
I don’t know what you’re talking about. ((well I do—ed.))
Or as a paragraph unto itself:
(( Terms and conditions: _ … ))
If you’re citing a body of work place tildes either side to denote a citation.
I’ve finished reading ~The Lion, the Witch and the Wardrobe~.
Yields:
I’ve finished reading <cite>The Lion, the Witch and the Wardrobe</cite>.A citation can be a book, a poem, a published piece of writing, a piece of art, a website, a song, a film, a TV show, a game and also software.
However this does not include the following: people’s names, the name of a ship or real products in general; such as a packet of crisps, a stereo or computer hardware.
For a guide on abbreviation best-practices, read
camendesign.com/code/using-abbr.
The basic syntax is:
(with title) Red {vs.|versus} Blue.
(without title) The {FBI} are like the British {MI5}.
Giving:
(with title) Red <abbr title="versus">vs.</abbr> Blue.
(without title) The <abbr>FBI</abbr> are like the British <abbr>MI5</abbr>.
There’s no support for <acronym> because that was removed in HTML5.
Create <ins> elements with square brackets, like so:
He [Bill Gates] was actually very charming.
And <del> elements by wrapping the span of text with triple dashes.
This statement is true. ---This statement is false.---
There may be times when you have to refer to technical information outputted from a computer that may contain symbols and characters that would clash with ReMarkable syntax (for example: log output, file / folder names and paths, emoticons or other computer output).
You can escape such text using back-ticks. ReMarkable will exclude the text within from processing.
The user’s desktop folder is located at `~/Desktop`.
You should use this for any text that generally comes from a computer, even if it’s readable.
It responded cheerfully with «`Syntax Error`».
If you wish to refer to function names, snippets of code and other text from a programming language, see the section on inline code spans.
A block quote is one or more paragraphs with a vertical bar on the left side.
The vertical bar character is followed by a tab character and then the text for each line.
| What is this life if, full of care, _ | We have no time to stand and stare?—
To include multiple paragraphs, include a quoted blank line. The tab character is optional in this case.
| No time to stand beneath the boughs, _ | And stare as long as sheep and cows: | | No time to see, when woods we pass, _ | Where squirrels hide their nuts in grass:
The same rules for paragraphs apply within a blockquote, line breaks will not be visible in the browser unless forced.
Currently there is no means to supply a cite source for the blockquote, this will be added later.
A block quote can be placed inside a blockquote.
| Quote level 1 | | | Quote level 2
Wrap inline quotations (<q> element) in either guillemets “« + »” (Alt /
Alt+Shift + ‘\’ on a Mac keyboard)
or double angle brackets “<< + >>”.
He said «turn left here», but she said <<no, it’s definitely right>>.
Hyperlinks in ReMarkable look a bit like an HTML hyperlink, with the angle brackets.
<Click here (http://google.com)>
The link description can also contain other inline ReMarkable formatting.
However, the link description cannot contain HTML tags. If you require HTML tags in your
link, either place them outside the link, or write the hyperlink manually in HTML. Tags can be included
inside a link description only if they are inside an inline code span.
<_Click here_ (http://google.com)>
http://
can be written as just “//”, and the address can be relative if desired.
<search (//google.com)> <download (download.html)> <home page (/)>
ReMarkable will automatically add rel="external" to links with absolute addresses.
<Click here (http://google.com)>
Becomes:
<a href="http://google.com" rel="external">Click here</a>If you link to a file, the mime-type is added for mime-types ReMarkable is aware of.
Download <this (/image.png)>.
Becomes:
Download <a href="/image.png" type="image/png">this</a>.A link to an email address can be provided as well.
<E-mail me (mailto:kroccamen@gmail.com)>
If you want the address to be the description, simply include only the address.
You can leave out the protocol and http:// will be assumed.
Visit <camendesign.com>. E-mail me <kroccamen@gmail.com>
The protocol (and “www”) will always be stripped in the output if it is included.
This can be done with email addresses as well, the mailto: protocol is optional when creating a link
with no description.
Visit <a href="http://camendesign.com" rel="external">camendesign.com</a>.
E-mail me <a href="mailto:kroccamen@gmail.com">kroccamen@gmail.com</a>
If you would like to mark a link as no-follow to
search engines, add a caret (“^”) before the URL.
This can be used on all kinds of links,
including relative URLs.
<Shameless plug (^http://camendesign.com)> <^camendesign.com>
Whilst you can of course use the normal HTML <img> tag to insert images,
ReMarkable provides a shorthand method of inserting images.
<"alt text goes here" path/to/image.png> or <"alt text goes here" path/to/image.png "title goes here">
For example, if you wanted to insert a smiley graphic at the end of a sentence:
And that’s that. <":)" images/smiley.png>
This syntax is very likely to change in the future as it does not allow an image to be wrapped in a hyperlink.
ReMarkable will look up the image’s width and height and add those to the HTML output. In
order to do this, the base_path parameter may have to be given so that ReMarkable can find
the images relative (or absolute) to the position of the ‘remarkable.php’ file.
For example, imagine that the ‘remarkable.php’ file was in a sub-folder called “scripts”, like so:
Webroot: - article.rem + scripts + remarkable.php - ... + images + smiley.png - ...
The relative image URLs in ‘article.rem’ assume that the “images” folder is in the same
location—“images/smiley.png”, but when ‘remarkable.php’ processes the ‘article.rem’ file,
it would try to incorrectly access ‘/scripts/images/smiley.png’. The base_path
parameter would have to be “../” to tell ‘remarkable.php’ to resolve
<img> src URLs to the
webroot—e.g.:
reMarkable "content", 0, 125, "../";A bullet list is created by starting a line with an allowed bullet symbol, then a tab character and then the text for the list item.
• A bullet character (Alt+8 on a Mac keyboard) * An asterisk - A dash + A plus
When blank lines are used between bullet items, the bullet contents will be wrapped in HTML paragraph
tags.
For example:
• One • Two And then, • One • Two
Would be converted into:
<ul>
<li>One</li>
<li>Two</li>
</ul>
<p>
And then,
</p>
<ul>
<li><p>One</p></li>
<li><p>Two</p></li>
</ul>The significance of this is that each list item is not limited to one line. You can have multiple lines and paragraphs on a list item by maintaining the indent, even blockquotes and other block elements are allowed within lists. For example:
• Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. | Duis aute irure dolor in reprehenderit in voluptate velit esse cillum | dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat Culpa qui officia deserunt mollit anim id est laborum. • Lorem ipsum.
A numbered list works the same as a bullet list, but with a different set of allowed bullets.
# A generic marker 1. A number followed by a dot. Any number can be used 1.1. A legal paragraph number, depths up to 6 are allowed i. Lower roman numerals I. Capital roman numerals a. Lower alpha A. Upper alpha
It should be noted though that all of these number styles are not presented in the outputted HTML. They
are merely for plain-text readability and are transformed to generic <li> elements in the
HTML. It is up to you to use CSS to style them to the matching numbering style.
Lists can be nested inside each other. Simply maintain the indent of the first, and continue with the second:
• Item + Sub Item + Sub Item • Item 1. Sub Item a. 3rd Level Item b. 3rd Level Item 2. Sub Item
A definition list presents a number of terms, and descriptions of those terms.
These are good for lists where each list item has to be named or titled.
Start a definition list with it’s first term by using two colons, a space, and then your term.
The definition follows on the next line, always indented one tab character.
:: Definition term Description. This is always indented one tab and can span multiple paragraphs by¬ maintaining indenting, like below. Blockquotes, and all other kinds of lists, can be included in a definition | This is a blockquote 1. And a list 2. Like this :: Second term :: Third term The description itself is optional.
To include code examples and other programming language text create inline <code> spans using
double back-ticks.
Using `*emphasis*` will generate ``<em>emphasis</em>``.
Anything inside the code spans will be presented to the user as-is.
Single back-ticks can be included in the code span.
Switch to the working directory by using ``cd "`dirname "$0"`"``.
To include multiple lines, potentially with indentation (such as computer code examples), use a fence block:
(Leave a blank line after the fence block for the paragraphs to be created after)
~~~> Preformatted text Whitespace like this is kept. ~ReMarkable~ _formatting_ is *not* processed. <~~~
All whitespace inside the fence is kept in the HTML output so the user sees the text exactly as it is written.
Preformatted text Whitespace like this is kept. ~ReMarkable~ _formatting_ is *not* processed.
If you are presenting source code, you can specify the language for plain text readability
~~~ HTML ~~~> I’m <em>emphasising</em> this point <strong>strongly</strong>. <~~~
When a language is specified, <pre><code>…</code></pre> is used in the output HTML instead of just <pre>…</pre>.
A ReMarkable extension is planned in the future to auto syntax highlight code, but this would be quite easy to do already with little modification to ReMarkable.
Preformatted blocks can be placed inside lists, definition lists and even blockquotes as long as the whole block, code and all is indented correctly.
For example, a preformatted block inside two different lists:
1. ~~~> example... <~~~ :: Term ~~~> example... <~~~
The fence start and end posts must be indented to the list level as well as the code (it will automatically be un-indented by one tab character in the output).
However, when a preformatted block is in a blockquote you must not put the blockquote pipe within the fence posts:
(otherwise the pipe will appear inside the preformatted block)
| Lorem ipsum dolor sit amet. | | ~~~> example... <~~~ | | Consectetur adipisicing elit.
Recursion is supported, so you can place a preformatted block inside a second-level list item &c.
Writing various typographical marks such as em and en-dashes is easier on some operating systems than others. When writing ReMarkable content on different operating systems, ReMarkable provides a number of ASCII conventions that are automatically corrected to better unicode or HTML equivalents.
Primes are used as shorthand for measurements in inches and feet. Inches are shortened to a double-prime, e.g. “A 15″ monitor” and feet are shortened to a single-prime “He was 5′5″ high”.
These are different unicode characters than quotes or curly quotes and are created whenever next to a number; therefore beware that you may get them unintentionally if quoted text ends in a number. For example: "Not before 5" may be incorrectly interpreted as a use of a prime (5 inches). Instead try to work around this with your writing, either adding punctuation or altering the grammar: "Not before 5 pm" or "Not before 5.".
ReMarkable automatically converts straight quotes ‘" / '’ into curly quotes ““ ” / ‘ ’”. Apostrophes for contractions are also converted into curly versions, for example: “can’t won’t shouldn’t wouldn’t”, as well as contractions omitting starting letters such as “’till” and “’twas” as well as date abbreviations: “The ’90s”.
An em-dash is represented by two normal dashes: “--”, ReMarkable will correct all such instances to a real em-dash: “—”.
An en-dash is used between a range of numbers, dates or times. For example: “1980–1985”, or “July –
August”.
In ASCII write “-to-” and it will be converted into a unicode en-dash. Spaces either
side are optional.
Easy Copyright “©” and All Rights Reserved “®” symbols can be added using “(C)” (or “(c)”) and “(R)” respectively. The superscript Trade Mark symbol “™” is written “^TM” (or “^tm”); for example: “Camen Design^TM” yields “Camen Design™”.
“1st 2nd 3rd 4th” &c. are automatically superscripted—“1st 2nd 3rd 4th”.
A custom ordinal or superscript can be substituted by using a caret “^” at the end of a word, the rest of the word will then be superscripted. For example:
{M^lle|Mademoiselle}
Gives: “Mlle”
Only a–z and 0–9 letters are allowed for the superscript portion, no spaces or other symbols or markup.
Another example is displaying numerical powers, the example:
2^10 = 1024
Is converted to: “210 = 1024”
Half and quarter-fraction symbols “½”, “¼” are created by writing “ 1/2” and
“ 1/4” respectively.
The required preceding space before the mark is eaten; i.e.
“3 1/2" Floppy Diskette” becomes “3½″ Floppy Diskette”.
The stacked plus-minus symbol “±” is written “+/-”.
The symbol for “therefore”—“∴” can be written either “:therefore:” or “:ergo:” (the Latin for “therefore”).
The real multiplication symbol “×” will be used where there a normal lowercase letter ‘X’ is either between two words, or at the end of a word next to a number.
1024 x 768 => 1024 × 768 12x6 => 12×6 for numbers, the space is optional 8" x 11" => 8″ × 11″ but letters / symbols text the space is required 3x as much => 3× as much
Comments and Suggestions → kroccamen@gmail.com