├── .gitmodules ├── LICENSE ├── Makefile ├── README.md ├── test.markdown └── xmark.xsl /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "tufte-css"] 2 | path = tufte-css 3 | url = https://github.com/edwardtufte/tufte-css.git 4 | [submodule "cmark"] 5 | path = cmark 6 | url = https://github.com/jgm/cmark.git 7 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 Antonio Vieiro 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /Makefile: -------------------------------------------------------------------------------- 1 | # CMARK must point to the "cmark" executable 2 | CMARK=/Users/antonio/SOFTWARE/CMARK/bin/cmark 3 | # And XSLTPROC must point to the xsltproc executable 4 | XSLTPROC=/usr/bin/xsltproc 5 | 6 | all: test.html test-notoc.html 7 | 8 | test-notoc.html: test.markdown xmark.xsl 9 | $(CMARK) -t xml test.markdown | $(XSLTPROC) --novalid --nonet --stringparam generate.toc no xmark.xsl - > test-notoc.html 10 | 11 | test.html: test.markdown xmark.xsl Makefile 12 | $(CMARK) -t xml test.markdown > test.xml 13 | $(XSLTPROC) --novalid --nonet xmark.xsl test.xml > test.html 14 | 15 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # xmark 2 | 3 | A simple XSLT stylesheet that generates [tufte-css](https://github.com/edwardtufte/tufte-css) powered HTML from [CommonMark](http://commonmark.org) markdown documents. 4 | 5 | More information [available here](http://vieiro.github.io/xmark/). 6 | 7 | -------------------------------------------------------------------------------- /test.markdown: -------------------------------------------------------------------------------- 1 | # xmark = Markdown + Tufte CSS 2 | ## Antonio Vieiro 3 | 4 | ## A brief introduction 5 | 6 | [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. 7 | 8 | [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). 9 | 10 | [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. 11 | 12 | [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. 13 | 14 | This document enumerates the goals of xmark, its conventions and explains how to use it. 15 | 16 | ## xmark goals 17 | 18 | xmark has two main goals: 19 | 20 | ### I: Generate tufte-css styled web pages 21 | 22 | The first goal of xmark is to generate tufte-css styled web pages from plain text files that follow the CommonMark specification. 23 | 24 | ### II: Serve as an experimentation tool 25 | 26 | 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. 27 | 28 | ## xmark conventions 29 | 30 | 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. 31 | 32 | [*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: 33 | 34 | ### Document title convention 35 | 36 | > 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. 37 | 38 | 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 ```

``` HTML tag. The title does not appear in the Table of Contents. 39 | 40 | 41 | ``` markdown 42 | # This is the document title 43 | ``` 44 | 45 | Of course, the document title is also set in the `````` HTML tag of the resulting document. 46 | 47 | ### Document sutbitle convention 48 | 49 | > The document subtitle is the first section of the document with level two. This is, the first paragraph tagged with a double '##' in the document. 50 | 51 | For instance: 52 | 53 | ``` markdown 54 | ## This is the document subtitle 55 | ``` 56 | 57 | It does not matter where you specify the subtitle in the source document, xmark always places the subtitle as the second paragraph of the document, using the ```<p class='subtitle'>``` tufte-css element. The subtitle does not appear in the Table of Contents. 58 | 59 | ### Epigraph convention 60 | 61 | 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: 62 | 63 | > Two-level nested block quotes (i.e., a pagraph starting with ```>>```) are always transformed to epigraphs. 64 | 65 | So, for instance, this text: 66 | 67 | ``` markdown 68 | >> xmark epigraphs are started with two ```>``` at the beginning of the paragraph. 69 | ``` 70 | 71 | Will generate a tufte-css epigraph like this one: 72 | 73 | >> xmark epigraphs are started with two ```>``` at the beginning of the paragraph. 74 | 75 | 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: 76 | 77 | ```markdown 78 | >> I do not paint things, I paint only the differences between things. 79 | >> <footer>Henri Matisse, <cite>Henri Matisse Dessins: 80 | >> thèmes et variations</cite> (Paris, 1943), 37</footer></blockquote> 81 | ``` 82 | 83 | That gets translated in the following HTML: 84 | 85 | >> I do not paint things, I paint only the differences between things. 86 | >> <footer>Henri Matisse, <cite>Henri Matisse Dessins: thèmes et variations</cite> (Paris, 1943), 37</footer></blockquote> 87 | 88 | ### Sidenote convention 89 | 90 | Nor markdown nor CommonMark support sidenotes [Sidenotes are like footnotes, except they don't force the user to scroll the page](sidenote). 91 | 92 | Markdown uses the ```[link text](url)``` structure to define links. xmark abuses this structure with the following convention: 93 | 94 | > Sidenotes are normal markdown links that use the word ```sidenote``` as its url. 95 | 96 | Sidenote numbers are automatically generated, so there's no need to worry about that detail. 97 | 98 | ``` markdown 99 | This is a normal paragraph with a 100 | sidenote [Write your sidenotes 101 | inside square brackets and then 102 | add a ```(sidenote)``` 103 | url.](sidenote). 104 | ``` 105 | 106 | Will produce the following paragraph with a sidenote: 107 | 108 | This is a normal paragraph with a sidenote [Write your sidenotes inside square brackets and then add a ```(sidenote)``` url.](sidenote). 109 | 110 | 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. 111 | 112 | ### Margin note convention 113 | 114 | 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: 115 | 116 | > To create a margin note write a normal markdown link, but use the word ```margin``` as the url. 117 | 118 | So, for instance, the markdown text: 119 | 120 | ```markdown 121 | For example, this paragraph has a 122 | [Margin note text here](margin) 123 | margin note. 124 | ``` 125 | 126 | Will result in the following paragraph with a margin note: 127 | 128 | For example, this paragraph has a [Margin note text here](margin) margin note. 129 | 130 | 131 | ### Figure convention 132 | 133 | CommonMark supports images by using the construction: 134 | 135 | ```markdown 136 | ![alt](url "title")] 137 | ``` 138 | 139 | that gets translated by CommonMark into the following HTML: 140 | 141 | ```html 142 | <img src='url' alt='alt' title='title' /> 143 | ``` 144 | 145 | 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). 146 | 147 | To overcome this limitation xmark uses the following convention 148 | 149 | > Use the 'alt' text as the caption for the figure, and abuse the 'title' text as both the HTML alt and the title. 150 | 151 | So, for instance, the following text: 152 | 153 | ``` markdown 154 | ![From Edward Tufte, *Visual Display of 155 | Quantitative Information*, 156 | page 92.](tufte-css/img/exports-imports.png 157 | "Visual Display of Quantitative Information") 158 | ``` 159 | 160 | Will be transformed in the following ```<figure>```, ```<img>``` and ```<caption>```: 161 | 162 | ![From Edward Tufte, *Visual Display of Quantitative Information*, page 92.](tufte-css/img/exports-imports.png "Visual Display of Quantitative Information") 163 | 164 | Note that figures are automatically numbered by xmark. 165 | 166 | ### Margin and full-width figure conventions 167 | 168 | Graphics that are ancillary to the main body of the text are placed in margin figures in tufte-css. 169 | 170 | But CommonMark and Markdown have just a single construct for images. ![F.J. Cole, “The History of Albrecht Dürer’s Rhinoceros in Zooological Literature,” *Science, Medicine, and History: Essays on the Evolution of Scientific Thought and Medical Practice (London, 1953)*, ed. E. Ashworth Underwood, 337-356. From page 71 of Edward Tufte’s *Visual Explanations*.](tufte-css/img/rhino.png "margin Rhino image") 171 | 172 | How could xmark support margin figures easily? By abusing the construct, of course. 173 | 174 | xmark abuses the title part of the image (that appears when you place the mouse over the image for a while), and if the title starts with the word 'margin' then the image is placed in a margin note, and if the title starts with the word 'fullwidth' then the image will be rendered as a full-width figure. The conventions are then: 175 | 176 | > If the title of the image starts with the word ```margin``` the figure will be placed in the margin. 177 | 178 | > If the title of the image starts with the word ```fullwidth``` the figure will be full-width. 179 | 180 | So any image constructed like this: 181 | 182 | ```markdown 183 | ![text caption here](image-name-or-url "margin Rhino image") 184 | ``` 185 | 186 | (note the ```margin``` word at the beginning of the title) will be considered a margin figure. 187 | 188 | And the following markup: 189 | 190 | ```markdown 191 | ![Edward Tufte’s English translation of the 192 | Napoleon’s March data visualization. 193 | From *Beautiful Evidence*, page 194 | 122-124.](tufte-css/img/napoleons-march.png 195 | "fullwidth Napoleon's march"). 196 | ``` 197 | 198 | Will be rendered as: 199 | 200 | ![Edward Tufte’s English translation of the Napoleon’s March data visualization. From *Beautiful Evidence*, page 122-124.](tufte-css/img/napoleons-march.png "fullwidth Napoleon's march"). 201 | 202 | Note that the ```margin``` and ```fullwidth``` special words are removed from the resulting HTML figure title. As in Tufte-CSS, full-width images are also numbered automaticcally with xmark. 203 | 204 | ### Source code convention 205 | 206 | Source code is translated to tufte-css equivalents, but CommonMark's ```info-string``` tag is kept, so it is possible to remember which programming language is being used for each part of the code. 207 | 208 | So, for instance, the markdown paragraph: 209 | 210 | ```` markdown 211 | ``` ruby 212 | def foo(x) 213 | return 3 214 | end 215 | ``` 216 | ```` 217 | 218 | That is tagged as a Ruby program, will be translated to the HTML equivalent: 219 | 220 | ``` html 221 | <pre class='code'><code class='language-ruby code'>def foo(x) 222 | return 3 223 | end</code></pre> 224 | ``` 225 | 226 | ## Deviations from tufte-css 227 | 228 | ### Table of Contents 229 | 230 | xmark automatically generates a Table of Contents and places it in a marginnote at the top of the document. 231 | 232 | You can disable this feature by setting the XSLT parameter ```generate-toc``` to ```no``` (see below for an example). 233 | 234 | ### Sections 235 | 236 | xmark does not generate ```<section>``` HTML 5 tags. 237 | 238 | ### Syntax highlighting 239 | 240 | xmark automatically embeds some ```<script>``` and CSS stylesheets from [highlight.js](https://github.com/isagalaev/highlight.js) to enable language-specific syntax highlighting. 241 | 242 | You can disable this feature by setting the XSLT parameter ```highlight``` to ```no```. 243 | 244 | ## Using xmark 245 | 246 | In order to use xmark one needs the following software: 247 | 248 | 1. A CommonMark processor that generates XML, such as the excellent [John MacFarlane's cmark](https://github.com/jgm/cmark). 249 | 2. The tufte-css project under the 'tufte-css' folder in a working directory of your liking. 250 | 3. The xmark.xsl stylesheet, [available here](https://github.com/vieiro/xmark/blob/master/xmark.xsl). 251 | 4. An XSLT processor, such as [xsltproc](http://www.xmlsoft.org). If you're using Mac OS/X, Linux or FreeBSD you may already have it installed. 252 | 253 | If you have cloned [xmark's github repository](https://github.com/vieiro/xmark) you can issue the ```git submodule init``` command to clone CommonMark's cmark and tufte-css projects. 254 | 255 | Once everything is set up you process your CommonMark file (```myfile.markdown```) with cmark, and then pipe that to xsltproc to generate an output file ```myfile.html```, like so: 256 | 257 | cmark -t xml myfile.markdown | xsltproc --novalid --nonet xmark.xsl - > myfile.html 258 | 259 | Or, if you want to disable the Table of Contents: 260 | 261 | cmark -t xml myfile.markdown | xsltproc --novalid --nonet \ 262 | --stringparam generate.toc no xmark.xsl - > myfile.html 263 | 264 | And, if you want to disable syntax highlighting: 265 | 266 | cmark -t xml myfile.markdown | xsltproc --novalid --nonet \ 267 | --stringparam highlight no xmark.xsl - > myfile.html 268 | 269 | ### License 270 | 271 | xmark is released under the MIT License. 272 | 273 | ## Further reading 274 | 275 | Some links you may find of interest: 276 | 277 | * [Tufte CSS homepage](https://edwardtufte.github.io/tufte-css/) 278 | * [CommonMark homepage](http://commonmark.org) 279 | * [xmark's project page at github](https://github.com/vieiro/xmark). 280 | * [The source of this document](https://raw.githubusercontent.com/vieiro/xmark/master/test.markdown) 281 | * [This document as rendered by GitHub](https://github.com/vieiro/xmark/blob/master/test.markdown) 282 | 283 | ## Epilogue 284 | 285 | Many thanks go to Edward Tufte, Dave Liepmann, John Gruber, John MacFarlane, Ivan Sagalaev and the CommonMark volunteers. 286 | 287 | 288 | -------------------------------------------------------------------------------- /xmark.xsl: -------------------------------------------------------------------------------- 1 | <?xml version="1.0" encoding="UTF-8"?> 2 | <!-- 3 | XMARK 4 | XSLT Stylesheet to generate tufte-css styled web pages from CommonMark documents. 5 | (C) 2016 Antonio Vieiro. MIT License. 6 | --> 7 | <xsl:stylesheet xmlns:xsl='http://www.w3.org/1999/XSL/Transform' xmlns:cm='http://commonmark.org/xml/1.0' xmlns:html='http://www.w3.org/1999/xhtml' version='1.1' exclude-result-prefixes='xsl cm html'> 8 | <xsl:output indent='no' version='1.0' omit-xml-declaration='yes' encoding='UTF-8' method='xml' /> 9 | <xsl:strip-space elements='cm:heading cm:paragraph cm:text cm:link cm:emph pre'/> 10 | 11 | <!-- options to generate table of contents and to include syntax highlighting --> 12 | <xsl:param name="generate.toc" select="'yes'"/> 13 | <xsl:param name='highlight' select="'yes'" /> 14 | 15 | <!-- title and subtitle --> 16 | <xsl:variable name='title' select='/cm:document/cm:heading[@level = "1"][1]' /> 17 | <xsl:variable name='subtitle' select='/cm:document/cm:heading[@level = "2"][1]' /> 18 | 19 | <!-- entry point to common mark document (cm:document) --> 20 | <xsl:template match="cm:document"> 21 | <!-- <!DOCTYPE html> --> 22 | <xsl:text disable-output-escaping='yes'><!DOCTYPE html></xsl:text> 23 | <html> 24 | <head> 25 | <xsl:if test='not($highlight = "no")'> 26 | <link rel="stylesheet" href="http://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.1.0/styles/default.min.css" /> 27 | </xsl:if> 28 | <link rel="stylesheet" href="tufte-css/tufte.css"/> 29 | <meta charset="UTF-8" /> 30 | <meta name="viewport" content="width=device-width, initial-scale=1"/> 31 | <title><xsl:value-of select='$title/cm:text/text()' /> 32 | 36 | 37 | 38 |
39 |

40 |

41 | 42 | 43 |

44 | 45 | 46 | toc 47 | checkbox 48 | margin-toggle 49 | 50 | 51 | Table of Contents
52 | 53 | 54 |

55 | 56 | 57 |
58 | 59 | 60 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | toc- 77 | # 78 | 79 | 80 | 81 | 82 |
83 | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 91 | 92 | 93 | 94 | 95 | 96 | 97 | 98 | 99 |

100 | 101 | 102 | 103 | 104 | 105 | 106 |
107 |
108 | 109 |
110 |
111 | 112 | 113 | 114 |
115 | 116 |
117 | 118 | 119 | 120 | 121 | 122 | 123 | 124 | 125 | 126 | 127 | 128 | 129 | 130 | 131 | 132 | 133 | 134 | 135 | checkbox 136 | margin-toggle 137 | 138 | 139 | 140 | 141 | 142 | 143 | 144 | 145 | 146 | 147 | 148 | 149 | 150 | checkbox 151 | margin-toggle 152 | 153 | 154 | 155 | 156 | 157 | 158 | 159 | 160 | 161 | 162 | 163 | 164 | 165 | 166 | 167 | 168 | 169 | 170 | 171 | 172 | 173 | 174 | 175 | 176 | 177 | 178 | 179 | 
180 |                         
181 |                                 
182 |                                         
183 |                                                 language- code
184 |                                         
185 |                                         
186 |                                                 nohighlight code
187 |                                         
188 |                                 
189 |                                 
190 |                         
191 |
192 | 193 | 194 | 195 | 196 | 197 | 198 | 199 | 200 | 201 | 202 | 203 | 204 | 205 |
    206 | 207 |
208 | 209 | 210 | 211 | 212 | 213 |
  • 214 | 215 |
    • 216 |     217 | 218 | 219 | 220 | 221 | 222 | 223 | 224 | 225 | 226 | 227 | 228 | 229 | 230 | 231 | 232 | 233 | 234 | 235 | checkbox 236 | margin-toggle 237 | 238 | 239 | 240 | 241 | 242 | 243 | 244 | 245 | 246 | 247 | 248 | 249 | 250 | 251 | 252 | 253 | 254 | 255 | fullwidth 256 | 257 | 258 | 259 | 260 | 261 | 262 | 263 | 264 | 265 | 266 | 267 | 268 | 269 | 270 | 271 | 272 |
    273 | Fig. . 274 |
    275 |     276 |     277 |     278 |     279 | 280 | 281 | 282 | 283 | 284 | 285 | 286 | 287 | 288 | 289 | 290 | 294 | 295 | 296 | 297 | 298 | 299 | > 300 | 301 | 302 | 303 | 304 | 305 | 306 | 307 | 308 | 309 | 310 | 311 | 315 | 316 | 317 | 318 | 319 | 320 | < 321 | 322 | 323 | 324 | 325 | 326 | 327 | 328 | 329 | 330 | 331 | 332 | 333 | 334 | 335 | 336 | 343 | 344 | 345 | 346 | --------------------------------------------------------------------------------