# xmark = Markdown + Tufte CSS ## Antonio Vieiro ## A brief introduction [Markdown](https://daringfireball.net/projects/markdown/) is a plain text format for writing structured documents, based on formatting conventions from email and usenet. It was developed in 2004 by John Gruber. [CommonMark](http://commonmark.org) is a proposal for a standard, **unambiguous syntax specification for Markdown**, along with a **suite of comprehensive tests** to validate Markdown implementations against this specification. It was created by a group of [Markdown fans](http://commonmark.org). [tufte-css](https://edwardtufte.github.io/tufte-css/) provides tools to style web articles using the ideas demonstrated by Edward Tufte's books and handouts. It was created by [Dave Liepmann](http://www.daveliepmann.com/) in late 2015 and is now an Edward Tufte project. [xmark](https://github.com/vieiro/xmark) is a simple XSLT stylesheet that transforms CommonMark compliant plain text documents ([see the source of this one here](https://raw.githubusercontent.com/vieiro/xmark/master/test.markdown)), with some additional conventions, into tufte-css styled web pages. This document enumerates the goals of xmark, its conventions and explains how to use it. ## xmark goals xmark has two main goals: ### I: Generate tufte-css styled web pages The first goal of xmark is to generate tufte-css styled web pages from plain text files that follow the CommonMark specification. ### II: Serve as an experimentation tool The second goal of xmark is to serve as a tool to manipulate the XML structure generated with CommonMark's cmark parser. By modifying a simple XSLT one can generate all sort of structured documents out from plain CommonMark text files. ## xmark conventions Nor Markdown nor CommonMark support document metadata so, for instance, there is no standard way to specify a title in a CommonMark document. It is not possible either to mark a paragraph as an epigraph, or as a figure caption, or as a margin note. [*Def. xmark convention*: a simple rule that allows emulating metadata in CommonMark markdown documents.](sidenote) These limitations in Markdown, and in the CommonMark standard, are overcome in xmark by means of conventions, that assign special meanings to paragraphs. This section lists these conventions: ### Document title convention > The document title is the first section of the document with level one. This is, the first paragraph tagged with a single '#' in the markdown document. It does not matter where you hide the first level one tag in your markdown document: xmark always places the title as the first paragraph of the document, using an ```
``` tufte-css element. The subtitle does not appear in the Table of Contents.
### Epigraph convention
CommonMark does not support epigraphs, but allows for nested block quotes. xmark makes use of this feature, making the double-nested block quotes work as epigraphs:
> Two-level nested block quotes (i.e., a pagraph starting with ```>>```) are always transformed to epigraphs.
So, for instance, this text:
``` markdown
>> xmark epigraphs are started with two ```>``` at the beginning of the paragraph.
```
Will generate a tufte-css epigraph like this one:
>> xmark epigraphs are started with two ```>``` at the beginning of the paragraph.
Epigraphs may also contain a footer using plain HTML, but you will have to specify the ```footer``` and ```cite``` in plain HTML, like this one:
```markdown
>> I do not paint things, I paint only the differences between things.
>>
```
That gets translated in the following HTML:
>> I do not paint things, I paint only the differences between things.
>>
### Sidenote convention
Nor markdown nor CommonMark support sidenotes [Sidenotes are like footnotes, except they don't force the user to scroll the page](sidenote).
Markdown uses the ```[link text](url)``` structure to define links. xmark abuses this structure with the following convention:
> Sidenotes are normal markdown links that use the word ```sidenote``` as its url.
Sidenote numbers are automatically generated, so there's no need to worry about that detail.
``` markdown
This is a normal paragraph with a
sidenote [Write your sidenotes
inside square brackets and then
add a ```(sidenote)```
url.](sidenote).
```
Will produce the following paragraph with a sidenote:
This is a normal paragraph with a sidenote [Write your sidenotes inside square brackets and then add a ```(sidenote)``` url.](sidenote).
As in tufte-css, sidenotes (and margin notes, below) are visible in wider screens, but are hidden in smaller screens. In these smaller screens, the symbol ⊕ (``⊕``) or the sidenote number can be tapped to view the content.
### Margin note convention
Margin notes are just like sidenotes, but do not have footnote-style numbers. The xmark convention for margin notes is similar to the previous convention:
> To create a margin note write a normal markdown link, but use the word ```margin``` as the url.
So, for instance, the markdown text:
```markdown
For example, this paragraph has a
[Margin note text here](margin)
margin note.
```
Will result in the following paragraph with a margin note:
For example, this paragraph has a [Margin note text here](margin) margin note.
### Figure convention
CommonMark supports images by using the construction:
```markdown
![alt](url "title")]
```
that gets translated by CommonMark into the following HTML:
```html
```
Sadly nor CommonMark nor Markdown support figures with captions [(there's an ongoing discussion, though)](http://talk.commonmark.org/t/image-tag-should-expand-to-figure-when-used-with-title/265/5).
To overcome this limitation xmark uses the following convention
> Use the 'alt' text as the caption for the figure, and abuse the 'title' text as both the HTML alt and the title.
So, for instance, the following text:
``` markdown
![From Edward Tufte, *Visual Display of
Quantitative Information*,
page 92.](tufte-css/img/exports-imports.png
"Visual Display of Quantitative Information")
```
Will be transformed in the following ```
``` and ```
```
## Deviations from tufte-css
### Table of Contents
xmark automatically generates a Table of Contents and places it in a marginnote at the top of the document.
You can disable this feature by setting the XSLT parameter ```generate-toc``` to ```no``` (see below for an example).
### Sections
xmark does not generate ```def foo(x)
return 3
end