! Spec.rb documentation = Character escaping You won't do much with special chars here: <>!@#$%^&*()_+[]\ = Comments Every once a blue moon, you might need to comment out part of a document. # i love this feature ;) That's what lines starting with pound character (`#`) are for. = Paragraphs Each paragraph is separated by blank line. So this is second one. = Heading Each heading is denoted by one or more `=` at the very beginning of line. == So this is second level heading Not surprising, huh? = Lists: Besides the free-form text you can have lists. Either unnumbered (ul): * one * two (with a link<#URLs>) * three or definition: : HTML = HyperText Mark-up Language : CSS = Cascading Style Sheets : HTTP = HyperText Transfer Protocol = Code blocks Another possibility is to have code blocks: {{{ while(1){ printf("I am code, you know?\n"); } }}} Good thing on code block is, it behaves like "verbatim" in TeX and the delimiters were selected to auto-fold in "vim". Code blocks also contain possibility of JavaScript powered syntax highlighting: {{{cpp while(1){ printf("I am code, you know?\n"); } }}} In order for this to work opening curly braces `{{{` must be followed by name of the language used (`{{{cpp` in the example above). See "highlight.js" for details. = Inline code All occurences of text within backslash (`) per single line is treated as `inline code` block. That, `of course, means` putting stray `backslash` on a line like this: ` has no effect. = Highlighted text All occurences of text within caret (^) per single line is treated as ^highlighted text^. That, ^of course, means^ putting stray ^caret^ on a line like this: ^ has no effect. = Keywords All occurences of FIXME, XXX, TODO are treated as keywords and marked as such. = Non-breakable spaces All occurences of tilde (`~`) will result in translation to non-breaking space: ` ` = Explicit line-breaks All occurences of two semicolons (`;``;`) will translate to;;explicit;;line;;break. = URLs You can also specify URLs. Either: {{{ Ruby }}} which will be: Ruby or: {{{ "Ruby on Rails" }}} which will end up: "Ruby on Rails". Supported schemes are (for now): http, https, ftp, mailto, news, irc. Also supported is "relative link" scheme. Also supported is "section link"<#:Hea> scheme (with "this variant"<#Hea>). Also, you can use empty label to get the URL itself used as the label. Not to mention "&@!#$!#@~*)!(^!#$&!()#$&)098$#&^!@#)$(*7<>!@#$$&*(^)" special chars shouldn't mess things up. = Images All lines beginning with at-sign are interpreted as image tag. Syntax: {{{ @ [style]+ }}} Ex1: {{{ @ https://wejn.org/favicon.ico }}} @ https://wejn.org/favicon.ico Ex2: {{{ @ https://wejn.org/favicon.ico border: 2px solid red }}} @ https://wejn.org/favicon.ico border: 2px solid red Ex3: {{{ @ https://wejn.org/favicon.ico border: 2px solid green @ https://wejn.org/favicon.ico border: 2px solid red }}} @ https://wejn.org/favicon.ico border: 2px solid green @ https://wejn.org/favicon.ico border: 2px solid red = Tables All lines beginning with pipe (`|`) character denote table. All cells are separated with pipe, too. Heading row can be created using two pipes (`||`) at the beginning of line. If you want first cell empty, use one non-breakable space: `|~|`. ||Name|Value |One|2 |Two|3 |Three|5 |~|Empty space ||Name|Value |Link|<#URLs> |Inline|This TODO `should` ^also^ display You could also align the table cells in your source, to look a bit prettier: || Numbers | here | One | 1 | Two | 2 | Three | 3 And it is properly supported (heading/trailing space is deleted). = Auto-TOC Of course the system has automatically generated TOC, whose items are pointing to appropriate headings in the spec. = Alternative layout By default there's hardcoded layout at the end of spec.rb ... which is sometimes undesirable. You can specify alternative layout in two ways: * by placing global layout file with name "layout.spec" in same dir as source * by placing local (per-file) layout file with name "input.lsp" for "input.ext" file Layout can contain normal HTML/XHTML markup with special tags in form: {{{{TAG_NAME}}}}. Allowed/supported tag names are: : CONTENT = Content of the spec file (final markup) : TOC = Table of contents, including heading : TOC_NO_HEADING = Table of contents, excluding heading : TITLE = Title of the document : NOW = Timestamp created by Time.now.to_s : NOW_NUMERIC = Timestamp in form: "YYYY-MM-DD HH:MM:SS" (MySQL datetime format) : FILENAME = Input filename = That's it. Not much, but for writing specs it's sufficient, IMHO. Oh, and the HTML code should validate, IMHO.