Implemented transclusions.
h3rald h3rald@h3rald.com
Sat, 11 Mar 2017 15:15:31 +0100
12 files changed,
924 insertions(+),
881 deletions(-)
A
doc/-credits.md
@@ -0,0 +1,29 @@
+# Credits + +HastyScribe is powered by the following open source software (see [LICENSE.md]({{repo}}/blob/master/LICENSE.md) for licensing details): + +* The wonderful [Discount][discount] C library, used to parse markdown code. +* The ...awesome [FontAwesome][fa] font, used for all the icons. +* The beautiful [Mr Bedfort][sudtipos] font, used as the base for the {{hs}} logo. +* The neat [Source Sans Pro](https://store1.adobe.com/cfusion/store/html/index.cfm?event=displayFontPackage&code=1959) and [Source Code Pro](http://store1.adobe.com/cfusion/store/html/index.cfm?event=displayFontPackage&code=1960) fonts, used for all standard text. + +Special thanks to: + +* Philip Wernersbach and Joshua Ellis, for contributing to {{hs}}. +* Andreas Rumpf, creator of the amazing [Nim][nim] programming language, used to implement {{hs}}. +* Ethan Lai, developer of the handy [Koala](http://koala-app.com/) app, used to compile all the LESS code into CSS. + +->  <- + + +[nim]: http://nim-lang.org/ +[df]: https://daringfireball.net/projects/markdown/ +[discount]: http://www.pell.portland.or.us/~orc/Code/discount/ +[pandoc]: http://johnmacfarlane.net/pandoc/ +[md-syntax]: https://daringfireball.net/projects/markdown/syntax +[fa]:http://fortawesome.github.io/Font-Awesome/ +[fa-icons]:http://fortawesome.github.io/Font-Awesome/icons/ +[pme]:http://michelf.com/projects/php-markdown/extra/ +[sudtipos]:http://www.sudtipos.com/ +[release]:{{release -> https://github.com/h3rald/hastyscribe/releases/download/v}} +[nifty]: https://github.com/h3rald/nifty
A
doc/-getting-started.md
@@ -0,0 +1,33 @@
+# Getting Started + +## Downloading Pre-built Binaries + +{# release -> [HastyScribe for $1]({{release}}{{$version}}/hastyscribe_v{{$version}}_$2.zip) -- $3 #} + +The easiest way to get {{hs}} is by downloading one of the prebuilt binaries from the [Github Release Page][release]: + + * {#release||Mac OS X (x64)||macos_x64||Compiled on {{osx -> Mac OS X Sierra}} (LLVM CLANG 8.0.0)#} + * {#release||Windows (x64)||windows_x64||{{xcc -> Cross-compiled on}} {{osx}} (MinGW-w64 GCC 4.8.2)#} + * {#release||Linux (x64)||linux_x64||{{xcc}} {{osx}} (GNU GCC 4.8.1)#} + * {#release||Linux (x86)||linux_x86||{{xcc}} {{osx}} (GNU GCC 4.8.1)#} + * {#release||Linux (ARM)||linux_arm||{{xcc}} {{osx}} (GNU GCC 4.8.2)#} + +## Installing using Nimble + +If you already have [Nim][nim] installed on your computer, you can simply run + +[nimble install hastyscribe](class:cmd) + +## Building from Source + +You can also build HastyScribe from source, if there is no pre-built binary for your platform. + +To do so, you can: + +1. Download and install [Nim][nim]. +2. Download and build [Nifty][nifty], and put the nifty executable somewhere in your $PATH. +3. Clone the HastyScribe [repository]({{repo -> https://github.com/h3rald/hastyscribe}}). +4. Navigate to the HastyScribe repository local folder. +5. Run **nifty install** to download HastyScribe's dependencies. +6. Run **nifty build discount** to build the Discount markdown library. +7. Run **nim c -d:release -d:discount hastyscribe.nim**
A
doc/-overview.md
@@ -0,0 +1,78 @@
+# Overview + +[](class:hastyscribe) is a self-contained {{mdlink -> [Markdown][df]}} compiler that can create single-file HTML documents. All documents created by {{hs -> HastyScribe}} use well-formed HTML and embed all stylesheets, fonts, and images that are necessary to display them in any (modern) browser (don't even try to display them in IE8 or lower). + +In other words, all documents created by HastyScribe are constituted by only one [.HTML](class:ext) file, for easy distribution. + +## Rationale + +There are plenty of programs and services that can convert {{mdlink}} into HTML but they are typically either too simple --they convert {{md -> markdown}} code into an HTML fragment-- or too complex --they produce a well-formed document, but they require too much configuration, or the installation of additional software dependencies. + +Sometimes you just want to write your document in markdown, and get a full HTML file out, ready to be distributed, ideally with no dependencies (external stylesheets or images) --that's where {{hs}} comes in. + +{{hs}}: + +* lets you focus on content and keeps things simple, while giving you all the power of {{disclink -> [Discount][discount]}}-enriched {{md}} (plus some more goodies). +* takes care of styling your documents properly, making sure they look good on your desktop and even on small screens, ready to be distributed. +* is a single, small executable file, with no dependencies. To be fair, it's about 1MB in size when compiled for OSX -- but that's only because the {{hs}} executable embeds all the fonts and stylesheets it needs to produce documents. + +## Key Features + +### Standard Markdown + +{{hs}} supports standard {{md}} for formatting text. Markdown is a lightweight markup language created by John Gruber, and used on many web sites and programs to enable users to write HTML code _without actually writing HTML tags_. + +> %tip% +> Tip +> +> You can learn about Markdown syntax in the [Syntax Reference](#Syntax.Reference) section of this document. Alternatively, you can also read the original [Markdown syntax page][md-syntax] on John Gruber's blog, Daring Fireball. + +### Discount Extensions + +Standard markdown is great, but sometimes you wish it had a few more features, like tables or fenced code blocks perhaps. The good news is that under the hood {{hs}} uses {{disclink}}, a markdown compiler library written in C that extends markdown with a few useful extensions, which allow you to, for example: + +* format blocks of texts to create [notes](#Notes) and [sidebars](#Sidebars) +* style text using CSS classes +* create definition lists and alphabetical lists + +### Text Snippets + +Although not part of neither {{md}} nor Discount, {{hs}} allows you to create text [snippets](#Snippets) to reuse content. Useful when you have to use a sentence or a formatted block of text over and over in a document, or shorten long words (like the word _{{hs}}_ in this document [](class:fa-smile-o)). + +### Custom Fields + +{{hs}} also supports [fields](#Fields) to easily include things like the current date or time, but also custom values specified as command-line parameters. + + +### Substitution Macros + +If you find yourself writing chunks of text that follows the same format except for some content, you can define simple text substitution [macros](#Macros) for even higher content reuse. + +### Image (and font) Embedding + +{{hs}} only produces single HTML files. With _no dependencies_: + +* By default, the HastyScribe, FontAwesome, Source Sans Pro, and Source Code Pro fonts are automatically embedded. +* All referenced images (both local and remote) are automatically embedded using the {{datauri -> [data URI scheme](http://en.wikipedia.org/wiki/Data_URI_scheme)}}. + +### FontAwesome Icons + +[FontAwesome][fa] icons can be used in [badges](#Badges) or simply to customize text. [](class:fa-thumbs-up) + +### Notes, tips, warnings, sidebars and badges + +> %sidebar% +> About notes etc. +> +> HastyScribe has built-in [tips](#Tips), [notes](#Notes), [warnings](#Warnings), [sidebars](#Sidebars), like this one. + +[...and this is a comment badge.](class:draftcomment) + +### Responsive Design + +All HTML documents created by {{hs}} are responsive and can be viewed perfectly on small devices. + +### Printed Media Support + +{{hs}}'s stylesheet contains styles that are specific for printed media. This means that if you try to print an HTML file generated by {{hs}} it will paginate properly and it will display headers and footers (with page numbers). +
A
doc/-syntax-block-classes.md
@@ -0,0 +1,127 @@
+# Class Blocks + +## Notes + +[Discount][discount] supports the definition of _class blocks_: [div](class:kwd)s with a class attribute. The syntax is very similar to the one used for [block quotes](#Block.Quotes), with the addition of the class name wrapped in [%](class:kwd)s on the first line. + +In {{hs}}, this syntax is used to produce notes, [tips](#Tips), [warmings](#Warnings), [sidebars](#Sidebars) and [terminal sessions](#Terminal.Sessions). + +{{input-text}} + +~~~ +> %note% +> Note +> +> This is a note. +~~~ + +{{output-text}} + +> %note% +> Note +> +> This is a note. + +## Tips + +Tips are used for optional information that can help the user in some way. + +{{input-text}} + +~~~ +> %tip% +> Tip +> +> This is a tip. +~~~ + +{{output-text}} + +> %tip% +> Tip +> +> This is a tip. + +## Warnings + +Warnings are used for important information the user should not overlook. + +{{input-text}} + +~~~ +> %warning% +> Warning +> +> This is a warning or an important note. +~~~ + +{{output-text}} + +> %warning% +> Warning +> +> This is a warning or an important note. + +## Sidebars + +Sidebars are used for digressions and asides. + +{{input-text}} + +~~~ +> %sidebar% +> This is a _sidebar_ +> +> Although not always placed on the side of the page, _sidebars_ contain +> additional content and asides. +~~~ + +{{output-text}} + +> %sidebar% +> This is a _sidebar_ +> +> Although not always placed on the side of the page, _sidebars_ contain additional content and asides. + + +## Terminal Sessions + +Terminal sessions are used to display commands entered in a terminal, in sequence, without displaying their output. + +{{input-text}} + +~~~ +> %terminal% +> +> cd src +> +> ./configure +> +> make && sudo make install +~~~ + +{{output-text}} + +> %terminal% +> cd src +> +> ./configure +> +> make && sudo make install + +If commands must be executed as a super-user, use the [terminal-su](class:kwd) class instead: + +{{input-text}} + +~~~ +> %terminal-su% +> +> shutdown -h now +~~~ + +{{output-text}} + +> %terminal-su% +> +> shutdown -h now +
A
doc/-syntax-block-lists.md
@@ -0,0 +1,152 @@
+# Lists + +## Unordered Lists + +{{input-text}} + +~~~ +* An item +* Another item +* And another... +~~~ + +{{output-text}} + +* An item +* Another item +* And another... + +## Ordered Lists + +{{input-text}} + +~~~ +1. First item +2. Second item +3. Third item +~~~ + +{{output-text}} + +1. First item +2. Second item +3. Third item + +> %tip% +> Tip +> +> You don't have to write numbers in order -- any number followed by a dot will do. + +## Alphabetical Lists + +{{input-text}} + +~~~ +a. First item +b. Second item +c. Third item +~~~ + +{{output-text}} + +a. First item +d. Second item +c. Third item + +> %tip% +> Tip +> +> You don't have to write letters in order -- any letter followed by a dot will do. + + +## Unstyled Lists + +{{input-text}} + +~~~ +> %unstyled% +> * An item +> * Another item +> * And another... +~~~ + +{{output-text}} + +> %unstyled% +> * An item +> * Another item +> * And another... + + +## Nested Lists + +To create a list within a list, simply indent the whole nested list with four space. + + +{{input-text}} + +~~~ +* This is a normal list +* Another item + * A nested unordered list + * Another item +* Back in the main list + a. A nested alphabetical list + b. Another item +~~~ + +{{output-text}} + +* This is a normal list +* Another item + * A nested unordered list + * Another item +* Back in the main list + a. A nested alphabetical list + b. Another item + +## Definition Lists + +In some cases you may want to write a list of terms and their corresponding definitions. You could use an ordinary unordered list, but semantically speaking the _proper_ type of list to use in this case is a definition list. + +{{input-text}} + +~~~ +unordered list +: A list for unordered items. Also called _bulleted list_. +ordered list +: A list for ordered items. Also called _numbered list_. +alphabetical list +: Technically speaking just an ordered list, but formatted with letters instead + of numbers +definition list +: A list of terms and definitions. +~~~ + +{{output-text}} + +unordered list +: A list for unordered items. Also called _bulleted list_. +ordered list +: A list for ordered items. Also called _numbered list_. +alphabetical list +: Technically speaking just an ordered list, but formatted with letters instead + of numbers +definition list +: A list of terms and definitions. + +Alternatively, you can write the above definition list as follows: + +~~~ +=unordered list= + A list for unordered items. Also called _bulleted list_. +=ordered list= + A list for ordered items. Also called _numbered list_. +=alphabetical list= + Technically speaking just an ordered list, but formatted with letters instead + of numbers +=definition list= + A list of terms and definitions. +~~~ + +
A
doc/-syntax-block.md
@@ -0,0 +1,118 @@
+# Block-level Formatting + +## Headings + +Headings can be specified simply by prepending [#](class:kwd)s to text, as follows: + + # Heading 1 + ## Heading 2 + ### Heading 3 + #### Heading 4 + ##### Heading 5 + ###### Heading 6 + +> %note% +> Note +> +> If you use [Document Headers](#Document.Headers), A [H1](class:kwd) is used for the title of the {{hs}} document. Within the document, start using headings from [H2](class:kwd). + +## Tables + +{{hs}} supports [PHP Markdown Extra][pme] table syntax using pipes and dashes. + +{{input-text}} + +~~~ +Column Header 1 | Column Header 2 | Column Header 3 +----------------|-----------------|---------------- +Cell 1,1 | Cell 1,2 | Cell 1, 3 +Cell 2,1 | Cell 2,2 | Cell 2, 3 +Cell 3,1 | Cell 3,2 | Cell 3, 3 +~~~ + +{{output-text}} + +Column Header 1 | Column Header 2 | Column Header 3 +----------------|-----------------|---------------- +Cell 1,1 | Cell 1,2 | Cell 1, 3 +Cell 2,1 | Cell 2,2 | Cell 2, 3 +Cell 3,1 | Cell 3,2 | Cell 3, 3 + +> %note% +> Note +> +> Multi-row cells are not supported. If you need more complex tables, use HTML code instead. + + +> %sidebar% +> Responsive Tables +> +> To make tables responsive, put them in a _responsive_ block, like in the previous example. The [responsive](class:kwd) class causes a table not to shrink and makes it scrollable horizontally on small devices. + +## Block Quotes + +Block quotes can be created simply by prepending a [>](class:kwd) to a line, and they can be nested by prepending additional [>](class:kwd)s. + +{{input-text}} + +~~~ +> This is a block quote. +> > This is a nested quote. +~~~ + +{{output-text}} + +> This is a block quote. +> > This is a nested quote. + +## Code Blocks + +To format a block of source code, indent it by at least four spaces. Here's the result: + + proc encode_image_file*(file, format): string = + if (file.existsFile): + let contents = file.readFile + return encode_image(contents, format) + else: + echo("Warning: image '"& file &"' not found.") + return file + +Alternatively, you can also use Github-style fenced blocks, by adding three tildes (~~~) before and after the source code. + +> %warning% +> Warning +> +> {{hs}} does not support syntax highlighting for code blocks. To do so, it would require Javascript and {{hs}} is currently kept purposedly "Javascript-free". + + +## Images + +{{input-text -> The following HastyScribe Markdown code:}} + +~~~ + +~~~ + +{{output-text -> Produces the following output:}} + + + +> %tip% +> Tip +> +> You can use URL placeholders for images as well, exactly like for links. + +> %warning% +> Limitations on automatic image download +> +> {{hs}} will attempt to download all HTTP image links. Note that: +> +> * If no response is received within 5 seconds, the download will be aborted. +> * Connecting through a proxy is currently not supported. +> * To download an image via HTTPS, you must explicitly recompile {{hs}} with [-d:ssl](class:kwd) and OpenSSL must be installed on your system. +> +> If {{hs}} is unable to download an image, it will leave it linked. + +{@ -syntax-block-lists.md || 3 @} + +{@ -syntax-block-classes.md || 3 @}
A
doc/-syntax-inline.md
@@ -0,0 +1,151 @@
+# Inline Formatting + +The following table lists all the most common ways to format inline text: + +> %responsive% +> Source | Output +> ----------------------------------------------------|-------------------- +> `**strong emphasis**` or `__strong emphasis__` | __strong emphasis__ +> `*emphasis*` or `_emphasis_` | *emphasis* +> `~~deleted text~~` | ~~deleted text~~ +> `<ins>inserted text<ins>` | <ins>inserted text</ins> +> ```code` `` | `code` +> `[HTML](abbr:Hypertext Markup Language)` | [HTML](abbr:Hypertext Markup Language) +> `<kbd>CTRL</kbd>+<kbd>C</kbd>` | <kbd>CTRL</kbd>+<kbd>C</kbd> +> `<mark>marked</mark>` | <mark>marked</mark>. +> `Sample output: <samp>This is a test.</samp>` | Sample output: <samp>This is a test.</samp> +> `Set the variable <var>test</var> to 1.` | Set the variable <var>test</var> to 1. +> `<q>This is a short quotation</q>` | <q>This is a short quotation</q> +> `<cite>Hamlet</cite>, by William Shakespeare.` | <cite>Hamlet</cite>, by William Shakespeare. +> `A [.md](class:ext) file` | A [.md](class:ext) file +> `[my_markdown_file.md](class:file) file` | [my_markdown_file.md](class:file) file + +> %tip% +> Tip +> +> The [kwd](class:kwd), [opt](class:kwd), [file](class:kwd), [dir](class:kwd), [arg](class:kwd), [tt](class:kwd) and [cmd](class:kwd) classes are all rendered as inline monospace text. [kwd](class:kwd) and [ext](class:ext) are also rendered in bold. + + +## SmartyPants Substitutions + +Special characters can be easily entered using some special character sequences. + +{{hs}} supports all the sequences supported by [Discount][discount]: + +* <code>`` text‘’</code> → “text”. +* `"double-quoted text"` → “double-quoted text” +* `'single-quoted text'` → ‘single-quoted text’ +* `don't` → don’t. as well as anything-else’t. (But foo'tbar is just foo'tbar.) +* `it's` → it’s, as well as anything-else’s (except not foo'sbar and the like.) +* `(tm)` → ™ +* `(r)` → ® +* `(c)` → © +* `1/4th` → 1/4th. Same goes for 1/2 and 3/4. +* `...` or `. . .` → … +* `---` → — +* `--` → – +* `A^B` becomes A^B. Complex superscripts can be enclosed in brackets, so `A^(B+2)` → A^(B+2). + + +## Icons + +{{hs}} bundles the [FontAwesome][fa] icon font. To prepend an icon to text you can use Discount's _class:_ pseudo-protocol, and specify a valid [fa-*](class:kwd) (non-alias) class. + +Examples: + +> %responsive% +> Source | Output +> -----------------------------------------|------------ +> `[a paper plane](class:fa-paper-plane)` | [ a paper plane](class:fa-paper-plane) +> `[Galactic Empire](class:fa-empire)` | [ Galactic Empire](class:fa-empire) +> `[Rebel Alliance](class:fa-rebel)` | [ Rebel Alliance](class:fa-rebel) + +> %tip% +> Tip +> +> See the [FontAwesome Icon Reference][fa-icons] for a complete list of all CSS classes to use for icons (aliases are not supported). + +## Badges + +Badges are normally just shorthands for [Icons](#Icons) formatted with different colors. To add a _badge_ to some inline text, use the corresponding class among those listed in the following table. For example, the following code: + + [Genoa, Italy](class:geo) + +produces the following result: + +[Genoa, Italy](class:geo) + +{{hs}} currently supports the following badges: + +> %responsive% +> Class | Badge | Class | Badge +> ---------------------|------------------------------|-------------------------------------------- +> `todo` | [](class:todo) |`user` | [](class:user) +> `fixme` | [](class:fixme) |`tag` | [](class:tag) +> `deadline` | [](class:deadline) |`tags` | [](class:tags) +> `draftcomment` | [](class:draftcomment) |`attachment` | [](class:attachment) +> `urgent` | [](class:urgent) |`bug` | [](class:bug) +> `verify` | [](class:verify) |`geo` | [](class:geo) +> `project` | [](class:project) |`eur` | [](class:eur) +> `red-circle` | [](class:red-circle) |`gbp` | [](class:gbp) +> `yellow-circle` | [](class:yellow-circle) |`usd` | [](class:usd) +> `green-circle` | [](class:green-circle) |`rub` | [](class:rub) +> `gray-circle` | [](class:gray-circle) |`jpy` | [](class:jpy) +> `star` | [](class:star) |`btc` | [](class:btc) +> `heart` | [](class:heart) |`try` | [](class:try) +> `square` | [](class:square) |`krw` | [](class:krw) +> `check` | [](class:check) |`inr` | [](class:inr) +> `lock` | [](class:lock) |`danger` | [](class:danger) +> `unlock` | [](class:unlock) |`question` | [](class:question) +> `email` | [](class:email) |`website` | [](class:website) +> `phone` | [](class:phone) |`fax` | [](class:fax) +> `tm` | [](class:tm) |`reg` | [](class:reg) +> `copy` | [](class:copy) |`red-flag` | [](class:red-flag) +> `green-flag` | [](class:green-flag) |`yellow-flag` | [](class:yellow-flag) +> `story` | [](class:story) |`feature` | [](class:feature) +> `add` | [](class:add) |`remove` | [](class:remove) +> `time` | [](class:time) |`date` | [](class:date) +> `html5` | [](class:html5) |`css3` | [](class:css3) +> `apple` | [](class:apple) |`windows` | [](class:windows) +> `linux` | [](class:linux) |`android` | [](class:android) +> `idea` | [](class:idea) |`link` | [](class:link) +> `chrome` | [](class:chrome) |`firefox` | [](class:firefox) +> `ie` | [](class:ie) |`edge` | [](class:edge) +> `safari` | [](class:safari) |`opera` | [](class:opera) +> `sticky` | [](class:sticky) |`bluetooth` | [](class:bluetooth) +> `wifi` | [](class:wifi) |`signal` | [](class:signal) +> `usb` | [](class:usb) |`print` | [](class:print) + +## HastyScribe Logo + +To display the {{hs}} logo, use the [hastyscribe](class:kwd) class, like this: + +`[](class:hastyscribe)` → [](class:hastyscribe) + + +## Links + +> %responsive% +> Source | Output +> ----------------------------------------|------------ +> `[H3RALD](https://h3rald.com/)` | [H3RALD](https://h3rald.com/) +> `[H3RALD](https://h3rald.com/ "H3RALD")`| [H3RALD](https://h3rald.com/ "H3RALD") +> `<https://h3rald.com>` | <https://h3rald.com> + +Additionally, you can define placeholders for URLs and link titles, like this: + +`[h3rald]: https://h3rald.com/ "Fabio Cevasco's Web Site"` + +And use them in hyperlinks (note the usage of square brackets instead of round brackets): + +`[H3RALD][h3rald]` + +> %sidebar% +> Link Icons +> +> {{hs}} automatically adds an envelope icon to email links, an arrow icon to links to external web sites, and logo icons to links to well-known web sites: +> +> * [h3rald@h3rad.com](mailto:h3rald@h3rald.com) +> * [@h3rald](https://twitter.com/h3rald) +> * [fabiocevasco](http://it.linkedin.com/in/fabiocevasco) +
A
doc/-syntax.md
@@ -0,0 +1,93 @@
+# Syntax Reference + +## Document Headers + +{{hs}} supports [Pandoc][pandoc]-style Document Headers, as implemented by the [Discount][discount] library. Basically, you can specify the title of the document, author and date as the first three lines of the document, prepending each with a [%](class:kwd), like this + +~~~ +% HastyScribe User Guide +% Fabio Cevasco +% - +~~~ + +> %warning% +> Important +> +> * The order of the document headers is significant. +> * If you want to use the current date, enter [% -](class:kwd) in the third line. + + +## Snippets + +If you want to reuse a few words or even entire blocks of texts, you can use {{hs}}'s snippets. + +A snippet definition is constituted by an identifier, followed by an arrow (->), followed by some text -- all wrapped in double curly brackets. + +The following definition creates a snippet called [test](class:kwd) which is transformed into the text "This is a test snippet.". + +<code>\{\{test -> This is a test snippet.\}\}</code> + +Once a snippet is defined _anywhere_ in the document, you can use its identifier wrapped in double curly brackets (<code>\{\{test}\}\}</code> in the previous example) anywhere in the document to reuse the specified text. + +> %note% +> Remarks +> +> * It doesn't matter where a snippet is defined. Snippets can be used anywhere in the document, before or after their definition. +> * When a document is compiled, both snippets _and snippets definitions_ are evaluated their body text. + +## Fields + +Besides user-defined snippets, {{hs}} also support fields, which can be used to insert current time and date information in a variety of formats: + +> %responsive% +> Source | Output +> --------------------------------------------|---------------------- +> <code>\{\{$timestamp\}\}</code> | {{$timestamp}} +> <code>\{\{$date\}\}</code> | {{$date}} +> <code>\{\{$full-date\}\}</code> | {{$full-date}} +> <code>\{\{$long-date\}\}</code> | {{$long-date}} +> <code>\{\{$medium-date\}\}</code> | {{$medium-date}} +> <code>\{\{$short-date\}\}</code> | {{$short-date}} +> <code>\{\{$short-time\}\}</code> | {{$short-time}} +> <code>\{\{$short-time-24\}\}</code> | {{$short-time-24}} +> <code>\{\{$time\}\}</code> | {{$time}} +> <code>\{\{$time-24\}\}</code> | {{$time-24}} +> <code>\{\{$day\}\}</code> | {{$day}} +> <code>\{\{$short-day\}\}</code> | {{$short-day}} +> <code>\{\{$month\}\}</code> | {{$month}} +> <code>\{\{$short-month\}\}</code> | {{$short-month}} +> <code>\{\{$year\}\}</code> | {{$year}} +> <code>\{\{$short-year\}\}</code> | {{$short-year}} +> <code>\{\{$weekday\}\}</code> | {{$weekday}} +> <code>\{\{$weekday-abbr\}\}</code> | {{$weekday-abbr}} +> <code>\{\{$month-name\}\}</code> | {{$month-name}} +> <code>\{\{$month-name-abbr\}\}</code> | {{$month-name-abbr}} +> <code>\{\{$timezone-offset\}\}</code> | {{$timezone-offset}} + +Additionally, you can define your own custom fields via command-line parameters, using the [--field/](class:arg) dynamic parameter, like this: + +> %terminal% +> hastyscribe my-document.md --field/product:HastyScribe --field/version:1.2.0 + +In this case it will be possible to access the [product](class:kwd) and [product](class:kwd) fields within [my-document.md](class:file) using <code>\{\{$product\}\}</code> and <code>\{\{$version\}\}</code>. + +## Macros + +If snippets are not enough, and you want to reuse chunks of _similar_ content, you can define substitution macros using the following syntax: + +<code>\{#greet -> Hello, $1! Are you $2?#\}</code> + +This defines a macro called [greet](class:kwd) that takes two parameters which will be substituted instead of [$1](class:kwd) and [$2](class:kwd). To use the macro, use the following syntax: + +<code>\{#greet||Fabio||ready#\}</code> + +> %note% +> Note +> +> * Like snippets, macros can be multiline. +> * Spaces and newline character are preseved ad the start and end of parameters. +> * You can use snippets and fields within macros (but you cannot nest macros inside other macros). + +{@ -syntax-inline.md || 2 @} + +{@ -syntax-block.md || 2 @}
A
doc/-usage.md
@@ -0,0 +1,48 @@
+# Usage + +{{hs}} is a command-line application that can compile one or more Markdown files into one or more HTML files with the same name(s). + +## Command Line Syntax + +[hastyscribe](class:cmd) _filename-or-glob-expression_ **[** [_<options\>_](class:opt) **]** + +Where: + + * _filename-or-glob-expression_ is a valid file or [glob](http://en.wikipedia.org/wiki/Glob_(programming)) expression that will be compiled into HTML. + * The following options are supported: + * [\-\-field/<field>=<value>](class:opt) causes {{hs}} to set a custom field to a specific value. + * [\-\-notoc](class:opt) causes {{hs}} to output HTML documents _without_ automatically generating a Table of Contents at the start. + * [\-\-user-css=<file>](class:opt) causes {{hs}} to insert the contents of the specified local file as a CSS stylesheet. + * [\-\-user-js=<file>](class:opt) causes {{hs}} to insert the contents of the specified local file as a Javascript script. + * [\-\-output-file=<file>](class:opt) causes {{hs}} to write output to a local file (Use [\-\-output-file=-](class:opt) to output to standard output). + * [\-\-watermark=<file>](class:opt) causes {{hs}} to embed and display an image as a watermark throughout the document. + * [\-\-fragment](class:opt) causes {{hs}} to output just an HTML fragment instead of a full document, without embedding any image, font or stylesheet. + +## Linux/OSX Examples + +Executing {{hs}} to compile [my_markdown_file.md](class:file) within the current directory: + +> %terminal% +> ./hastyscribe my\_markdown\_file.md + +Executing {{hs}} to compile all [.md](class:ext) files within the current directory: + +> %terminal% +> ./hastyscribe \*.md + +## Windows Examples + +Executing {{hs}} to compile [my_markdown_file.md](class:file) within the current directory: + +> %terminal% +> hastyscribe.exe my\_markdown\_file.md + +Executing {{hs}} to compile all [.md](class:ext) files within the current directory: + +> %terminal% +> hastyscribe.exe \*.md + +> %tip% +> Tip +> +> You can also drag a Markdown file directly on [hastyscribe.exe](class:kwd) to compile it to HTML.
M
doc/HastyScribe_UserGuide.htm
→
doc/HastyScribe_UserGuide.htm
@@ -4684,59 +4684,59 @@ </thead>
<tbody> <tr> <td><code>{{$timestamp}}</code> </td> -<td> 1487863280</td> +<td> 1489241627</td> </tr> <tr> <td><code>{{$date}}</code> </td> -<td> 2017-02-23</td> +<td> 2017-03-11</td> </tr> <tr> <td><code>{{$full-date}}</code> </td> -<td> Thursday, February 23, 2017</td> +<td> Saturday, March 11, 2017</td> </tr> <tr> <td><code>{{$long-date}}</code> </td> -<td> February 23, 2017</td> +<td> March 11, 2017</td> </tr> <tr> <td><code>{{$medium-date}}</code> </td> -<td> Feb 23, 2017</td> +<td> Mar 11, 2017</td> </tr> <tr> <td><code>{{$short-date}}</code> </td> -<td> 2/23/17</td> +<td> 3/11/17</td> </tr> <tr> <td><code>{{$short-time}}</code> </td> -<td> 16:21 PM</td> +<td> 15:13 PM</td> </tr> <tr> <td><code>{{$short-time-24}}</code> </td> -<td> 16:21</td> +<td> 15:13</td> </tr> <tr> <td><code>{{$time}}</code> </td> -<td> 16:21:20 PM</td> +<td> 15:13:47 PM</td> </tr> <tr> <td><code>{{$time-24}}</code> </td> -<td> 16:21:20</td> +<td> 15:13:47</td> </tr> <tr> <td><code>{{$day}}</code> </td> -<td> 23</td> +<td> 11</td> </tr> <tr> <td><code>{{$short-day}}</code> </td> -<td> 23</td> +<td> 11</td> </tr> <tr> <td><code>{{$month}}</code> </td> -<td> 02</td> +<td> 03</td> </tr> <tr> <td><code>{{$short-month}}</code> </td> -<td> 2</td> +<td> 3</td> </tr> <tr> <td><code>{{$year}}</code> </td>@@ -4748,19 +4748,19 @@ <td> 17</td>
</tr> <tr> <td><code>{{$weekday}}</code> </td> -<td> Thursday</td> +<td> Saturday</td> </tr> <tr> <td><code>{{$weekday-abbr}}</code> </td> -<td> 23</td> +<td> 11</td> </tr> <tr> <td><code>{{$month-name}}</code> </td> -<td> February</td> +<td> March</td> </tr> <tr> <td><code>{{$month-name-abbr}}</code> </td> -<td> Feb</td> +<td> Mar</td> </tr> <tr> <td><code>{{$timezone-offset}}</code> </td>@@ -5675,7 +5675,7 @@
<p style="text-align:center;"> <img src="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAFgAAAAfCAYAAABjyArgAAAGa0lEQVRo3u1aW08bRxTmuSqIV0SlIFWtAKkVtEpfWiVI6Q+gT60qpeIhTXkrSpqoaZ1AkJMobSRkkUahEtAWCVWBYMDcfME22MZ3rw0hrzzwAxC/4FTfrGeYXXa9u8Y0yGGkEeu5nGW+OfOdy2wDETU1NDTQea19JcKf8o/lwBKthlbIH16j0EaQwrEwbSSiFEvFaCuToFQuSel8mrKFDOWULOWKObUqWcoqGcrk02wMxsZTMTY3EgszWf6wn8nGO3xri7SwOk/zy16aW3pJL32zrM4uztDMwou6qRLQR+AGIn5a3wxRNB6hWHKTgZXOpxiAhVKeijsKlV4VaXt3m3ZeqxXPpVcl1ocxWSXL5mAuZEQTESYTsvUge5fnBMgAuE5BbtCCm4gyDUxmk0xbARpAdT9w05Uvr1BjU+Oxo4A29LkfutnYwnaBbQo0Op6OM21e31zXgLy4tkDzK14VZN8RyHdcd6ijo+PYO9CGPruLOwtyBMCgBRlcAJMrZplWekY91Nraapt3MNbz1MPmgkKgzQkBckjQxZLfR4urKsjQ4j/GnlJ7R7uQ09PTQwMDA6zimbdjzOjzUdNFoe+syBEAgydBC0fg5pgm9n7VqwGvubmZ+vr6aGhoiCKRCKt4Rhv65LGYG0/GKF9SQYYmgy5UTl6jleCyoIp/pv+mpqYmdV5vL+3t7ZG+oA19GIOxRouanJo4U3IEwDBo4EvQAjRXDy7AA5AHBwdUqUxOTmqAxu4CZGwYNg7vgOELRgO0tr6qUsXqgjiC2Ci5SNZY8w4uW78grnF6OZ6REfr2629OLMdszWZyBMA4vjBK4FwcbRncrq4uwx00K9gEzJE1GTLByXjHEVWoWnx30CU05fXuriXAKFxzZA7EM9o+6e6mP5+PacBtaWmhxncb6fbNn2h/f9+WHKP/x6wYydEAHGPUkGIGDZwrg2ultXZABifD8DGqSMUoEle1GFzc0alqr5NNxFhuaPhi+Clo/+BDev9CG13+/Avq//46a8Ppe/TwEXuenZmxJeek/48GYKa9SoZRAzdoOOqKolC1BSBzuoBMyIYLx7U4tKFqMTcg+oLjyTfI6KhyQyMvBm23btykn2/dZiDzyjXXSCPN5MhFliXXSnI0AIMf86U8c8X4orDrJy2cn1DhwuGEcC4Ol9029MEy64tBVKQpmKMHRpaTSiYZsLIM/NaDbCUHpf+HfsNaSY4GYERoyo7CfFmuvTI1wFsAz2CXUGXw9X0jIyOaF3MthmxwMSI+mSZOC2BeoLkAtvujj4XmweAF/H5HcqxKRYBh3HCEeRAhH0kAaOTvAkyv12vYJ8/nRx2yEfGBihJlly0YDdacIuRyeHhIE+Pj7Bmaqz/i4On/hSKQT9jeLYkFyVrIjVVbWxsjcwCOZxx/3sc9DQDO+4xoAmF1TsPDQers7DQ1Kmbaa9c4QVMBBLQXldMEDN29X110ofU9W3KuX7tmWG0bOfi+yCvwBQFE/SKNONkOX8snAO+AT7yV2RIAD96/J9wiuwBbuVcyPbjvDws3DS4btNqpnBO7aW8SYAQc3FWzE2hwrnMSIDz57fdjgUY1cipxb8VAwy5FwPDBdcMzQJUpQt9nlyIA8PSL6foOlSsZuUqGzI6R4zusGrkie5ds5ADwUsBHU/9OabJW2DTIwXw5aLFK0gAcOUnzJuUcc9N4iAzXSn/Mzdw0gMzb9X0o0GjZTUtLblogEhCZNZYfXpqjX+7WYbqSBxpymKz3Z2sZaGyWAw2kLnlWjact6+l2QwCcSBuHyk7i8WpDZTn5XrcAy8meib/Ga5/sGfUw2Uj24F08ZSkn3vnNRj1dHQmAUV2DLpGuvPrdVQ3ITpI+0HrDdGUhQ8MPht/G2+WjHwM3fmRuVLGKhDv6MEZOuF/87CKjBvjZrnLe960GGBUJcAQDAFnW5GqujABuvpijZ2PP7H5HYBhk6MfYkWP22yyZ5EROpaSUJcACZEW99AQnO770HOWXnlnb4BoBYbQwJxtVab7djaqBHOMO0IV8bQ/QrK7tcXPBru3xfUQh45gWrNKVTjfK7G8t5VQNMLvf+rSbvIte5sLBT1bEhycl6cOTEmuTPzyZ93np0uVL1XxqdCJqsKKEajS4BnKs/2GA9fjJYwpFQ9KnU+WKT6cKGdaHMdUAe1oafGY5+LzWsBLRO+dAnN7Xlf8BOGLNYHeHmZwAAAAASUVORK5CYII=" alt="Creative Commons Attribution-Noncommercial-No Derivative Works 3.0 Unported License" /></p> </div> <div id="footer"> - <p><span class="copy"></span> Fabio Cevasco – February 23, 2017</p> + <p><span class="copy"></span> Fabio Cevasco – March 11, 2017</p> <p><span>Powered by</span> <a href="https://h3rald.com/hastyscribe"><span class="hastyscribe"></span></a></p> </div> </div>
M
doc/HastyScribe_UserGuide.md
→
doc/HastyScribe_UserGuide.md
@@ -2,831 +2,8 @@ % HastyScribe User Guide
% Fabio Cevasco % - -## Overview - -[](class:hastyscribe) is a self-contained {{mdlink -> [Markdown][df]}} compiler that can create single-file HTML documents. All documents created by {{hs -> HastyScribe}} use well-formed HTML and embed all stylesheets, fonts, and images that are necessary to display them in any (modern) browser (don't even try to display them in IE8 or lower). - -In other words, all documents created by HastyScribe are constituted by only one [.HTML](class:ext) file, for easy distribution. - -### Rationale - -There are plenty of programs and services that can convert {{mdlink}} into HTML but they are typically either too simple --they convert {{md -> markdown}} code into an HTML fragment-- or too complex --they produce a well-formed document, but they require too much configuration, or the installation of additional software dependencies. - -Sometimes you just want to write your document in markdown, and get a full HTML file out, ready to be distributed, ideally with no dependencies (external stylesheets or images) --that's where {{hs}} comes in. - -{{hs}}: - -* lets you focus on content and keeps things simple, while giving you all the power of {{disclink -> [Discount][discount]}}-enriched {{md}} (plus some more goodies). -* takes care of styling your documents properly, making sure they look good on your desktop and even on small screens, ready to be distributed. -* is a single, small executable file, with no dependencies. To be fair, it's about 1MB in size when compiled for OSX -- but that's only because the {{hs}} executable embeds all the fonts and stylesheets it needs to produce documents. - -### Key Features - -#### Standard Markdown - -{{hs}} supports standard {{md}} for formatting text. Markdown is a lightweight markup language created by John Gruber, and used on many web sites and programs to enable users to write HTML code _without actually writing HTML tags_. - -> %tip% -> Tip -> -> You can learn about Markdown syntax in the [Syntax Reference](#Syntax.Reference) section of this document. Alternatively, you can also read the original [Markdown syntax page][md-syntax] on John Gruber's blog, Daring Fireball. - -#### Discount Extensions - -Standard markdown is great, but sometimes you wish it had a few more features, like tables or fenced code blocks perhaps. The good news is that under the hood {{hs}} uses {{disclink}}, a markdown compiler library written in C that extends markdown with a few useful extensions, which allow you to, for example: - -* format blocks of texts to create [notes](#Notes) and [sidebars](#Sidebars) -* style text using CSS classes -* create definition lists and alphabetical lists - -#### Text Snippets - -Although not part of neither {{md}} nor Discount, {{hs}} allows you to create text [snippets](#Snippets) to reuse content. Useful when you have to use a sentence or a formatted block of text over and over in a document, or shorten long words (like the word _{{hs}}_ in this document [](class:fa-smile-o)). - -#### Custom Fields - -{{hs}} also supports [fields](#Fields) to easily include things like the current date or time, but also custom values specified as command-line parameters. - - -#### Substitution Macros - -If you find yourself writing chunks of text that follows the same format except for some content, you can define simple text substitution [macros](#Macros) for even higher content reuse. - -#### Image (and font) Embedding - -{{hs}} only produces single HTML files. With _no dependencies_: - -* By default, the HastyScribe, FontAwesome, Source Sans Pro, and Source Code Pro fonts are automatically embedded. -* All referenced images (both local and remote) are automatically embedded using the {{datauri -> [data URI scheme](http://en.wikipedia.org/wiki/Data_URI_scheme)}}. - -#### FontAwesome Icons - -[FontAwesome][fa] icons can be used in [badges](#Badges) or simply to customize text. [](class:fa-thumbs-up) - -#### Notes, tips, warnings, sidebars and badges - -> %sidebar% -> About notes etc. -> -> HastyScribe has built-in [tips](#Tips), [notes](#Notes), [warnings](#Warnings), [sidebars](#Sidebars), like this one. - -[...and this is a comment badge.](class:draftcomment) - -#### Responsive Design - -All HTML documents created by {{hs}} are responsive and can be viewed perfectly on small devices. - -#### Printed Media Support - -{{hs}}'s stylesheet contains styles that are specific for printed media. This means that if you try to print an HTML file generated by {{hs}} it will paginate properly and it will display headers and footers (with page numbers). - -## Getting Started - -### Downloading Pre-built Binaries - -{# release -> [HastyScribe for $1]({{release}}{{$version}}/hastyscribe_v{{$version}}_$2.zip) -- $3 #} - -The easiest way to get {{hs}} is by downloading one of the prebuilt binaries from the [Github Release Page][release]: - - * {#release||Mac OS X (x64)||macos_x64||Compiled on {{osx -> Mac OS X Sierra}} (LLVM CLANG 8.0.0)#} - * {#release||Windows (x64)||windows_x64||{{xcc -> Cross-compiled on}} {{osx}} (MinGW-w64 GCC 4.8.2)#} - * {#release||Linux (x64)||linux_x64||{{xcc}} {{osx}} (GNU GCC 4.8.1)#} - * {#release||Linux (x86)||linux_x86||{{xcc}} {{osx}} (GNU GCC 4.8.1)#} - * {#release||Linux (ARM)||linux_arm||{{xcc}} {{osx}} (GNU GCC 4.8.2)#} - -### Installing using Nimble - -If you already have [Nim][nim] installed on your computer, you can simply run - -[nimble install hastyscribe](class:cmd) - -### Building from Source - -You can also build HastyScribe from source, if there is no pre-built binary for your platform. - -To do so, you can: - -1. Download and install [Nim][nim]. -2. Download and build [Nifty][nifty], and put the nifty executable somewhere in your $PATH. -3. Clone the HastyScribe [repository]({{repo -> https://github.com/h3rald/hastyscribe}}). -4. Navigate to the HastyScribe repository local folder. -5. Run **nifty install** to download HastyScribe's dependencies. -6. Run **nifty build discount** to build the Discount markdown library. -7. Run **nim c -d:release -d:discount hastyscribe.nim** - -## Usage - -{{hs}} is a command-line application that can compile one or more Markdown files into one or more HTML files with the same name(s). - -### Command Line Syntax - -[hastyscribe](class:cmd) _filename-or-glob-expression_ **[** [_<options\>_](class:opt) **]** - -Where: - - * _filename-or-glob-expression_ is a valid file or [glob](http://en.wikipedia.org/wiki/Glob_(programming)) expression that will be compiled into HTML. - * The following options are supported: - * [\-\-field/<field>=<value>](class:opt) causes {{hs}} to set a custom field to a specific value. - * [\-\-notoc](class:opt) causes {{hs}} to output HTML documents _without_ automatically generating a Table of Contents at the start. - * [\-\-user-css=<file>](class:opt) causes {{hs}} to insert the contents of the specified local file as a CSS stylesheet. - * [\-\-user-js=<file>](class:opt) causes {{hs}} to insert the contents of the specified local file as a Javascript script. - * [\-\-output-file=<file>](class:opt) causes {{hs}} to write output to a local file (Use [\-\-output-file=-](class:opt) to output to standard output). - * [\-\-watermark=<file>](class:opt) causes {{hs}} to embed and display an image as a watermark throughout the document. - * [\-\-fragment](class:opt) causes {{hs}} to output just an HTML fragment instead of a full document, without embedding any image, font or stylesheet. - -### Linux/OSX Examples - -Executing {{hs}} to compile [my_markdown_file.md](class:file) within the current directory: - -> %terminal% -> ./hastyscribe my\_markdown\_file.md - -Executing {{hs}} to compile all [.md](class:ext) files within the current directory: - -> %terminal% -> ./hastyscribe \*.md - -### Windows Examples - -Executing {{hs}} to compile [my_markdown_file.md](class:file) within the current directory: - -> %terminal% -> hastyscribe.exe my\_markdown\_file.md - -Executing {{hs}} to compile all [.md](class:ext) files within the current directory: - -> %terminal% -> hastyscribe.exe \*.md - -> %tip% -> Tip -> -> You can also drag a Markdown file directly on [hastyscribe.exe](class:kwd) to compile it to HTML. - -## Syntax Reference - -### Document Headers - -{{hs}} supports [Pandoc][pandoc]-style Document Headers, as implemented by the [Discount][discount] library. Basically, you can specify the title of the document, author and date as the first three lines of the document, prepending each with a [%](class:kwd), like this - -~~~ -% HastyScribe User Guide -% Fabio Cevasco -% - -~~~ - -> %warning% -> Important -> -> * The order of the document headers is significant. -> * If you want to use the current date, enter [% -](class:kwd) in the third line. - - -### Snippets - -If you want to reuse a few words or even entire blocks of texts, you can use {{hs}}'s snippets. - -A snippet definition is constituted by an identifier, followed by an arrow (->), followed by some text -- all wrapped in double curly brackets. - -The following definition creates a snippet called [test](class:kwd) which is transformed into the text "This is a test snippet.". - -<code>\{\{test -> This is a test snippet.\}\}</code> - -Once a snippet is defined _anywhere_ in the document, you can use its identifier wrapped in double curly brackets (<code>\{\{test}\}\}</code> in the previous example) anywhere in the document to reuse the specified text. - -> %note% -> Remarks -> -> * It doesn't matter where a snippet is defined. Snippets can be used anywhere in the document, before or after their definition. -> * When a document is compiled, both snippets _and snippets definitions_ are evaluated their body text. - -### Fields - -Besides user-defined snippets, {{hs}} also support fields, which can be used to insert current time and date information in a variety of formats: - -> %responsive% -> Source | Output -> --------------------------------------------|---------------------- -> <code>\{\{$timestamp\}\}</code> | {{$timestamp}} -> <code>\{\{$date\}\}</code> | {{$date}} -> <code>\{\{$full-date\}\}</code> | {{$full-date}} -> <code>\{\{$long-date\}\}</code> | {{$long-date}} -> <code>\{\{$medium-date\}\}</code> | {{$medium-date}} -> <code>\{\{$short-date\}\}</code> | {{$short-date}} -> <code>\{\{$short-time\}\}</code> | {{$short-time}} -> <code>\{\{$short-time-24\}\}</code> | {{$short-time-24}} -> <code>\{\{$time\}\}</code> | {{$time}} -> <code>\{\{$time-24\}\}</code> | {{$time-24}} -> <code>\{\{$day\}\}</code> | {{$day}} -> <code>\{\{$short-day\}\}</code> | {{$short-day}} -> <code>\{\{$month\}\}</code> | {{$month}} -> <code>\{\{$short-month\}\}</code> | {{$short-month}} -> <code>\{\{$year\}\}</code> | {{$year}} -> <code>\{\{$short-year\}\}</code> | {{$short-year}} -> <code>\{\{$weekday\}\}</code> | {{$weekday}} -> <code>\{\{$weekday-abbr\}\}</code> | {{$weekday-abbr}} -> <code>\{\{$month-name\}\}</code> | {{$month-name}} -> <code>\{\{$month-name-abbr\}\}</code> | {{$month-name-abbr}} -> <code>\{\{$timezone-offset\}\}</code> | {{$timezone-offset}} - -Additionally, you can define your own custom fields via command-line parameters, using the [--field/](class:arg) dynamic parameter, like this: - -> %terminal% -> hastyscribe my-document.md --field/product:HastyScribe --field/version:1.2.0 - -In this case it will be possible to access the [product](class:kwd) and [product](class:kwd) fields within [my-document.md](class:file) using <code>\{\{$product\}\}</code> and <code>\{\{$version\}\}</code>. - -### Macros - -If snippets are not enough, and you want to reuse chunks of _similar_ content, you can define substitution macros using the following syntax: - -<code>\{#greet -> Hello, $1! Are you $2?#\}</code> - -This defines a macro called [greet](class:kwd) that takes two parameters which will be substituted instead of [$1](class:kwd) and [$2](class:kwd). To use the macro, use the following syntax: - -<code>\{#greet||Fabio||ready#\}</code> - -> %note% -> Note -> -> * Like snippets, macros can be multiline. -> * Spaces and newline character are preseved ad the start and end of parameters. -> * You can use snippets and fields within macros (but you cannot nest macros inside other macros). - -### Inline Formatting - -The following table lists all the most common ways to format inline text: - -> %responsive% -> Source | Output -> ----------------------------------------------------|-------------------- -> `**strong emphasis**` or `__strong emphasis__` | __strong emphasis__ -> `*emphasis*` or `_emphasis_` | *emphasis* -> `~~deleted text~~` | ~~deleted text~~ -> `<ins>inserted text<ins>` | <ins>inserted text</ins> -> ```code` `` | `code` -> `[HTML](abbr:Hypertext Markup Language)` | [HTML](abbr:Hypertext Markup Language) -> `<kbd>CTRL</kbd>+<kbd>C</kbd>` | <kbd>CTRL</kbd>+<kbd>C</kbd> -> `<mark>marked</mark>` | <mark>marked</mark>. -> `Sample output: <samp>This is a test.</samp>` | Sample output: <samp>This is a test.</samp> -> `Set the variable <var>test</var> to 1.` | Set the variable <var>test</var> to 1. -> `<q>This is a short quotation</q>` | <q>This is a short quotation</q> -> `<cite>Hamlet</cite>, by William Shakespeare.` | <cite>Hamlet</cite>, by William Shakespeare. -> `A [.md](class:ext) file` | A [.md](class:ext) file -> `[my_markdown_file.md](class:file) file` | [my_markdown_file.md](class:file) file - -> %tip% -> Tip -> -> The [kwd](class:kwd), [opt](class:kwd), [file](class:kwd), [dir](class:kwd), [arg](class:kwd), [tt](class:kwd) and [cmd](class:kwd) classes are all rendered as inline monospace text. [kwd](class:kwd) and [ext](class:ext) are also rendered in bold. - - -#### SmartyPants Substitutions - -Special characters can be easily entered using some special character sequences. - -{{hs}} supports all the sequences supported by [Discount][discount]: - -* <code>`` text‘’</code> → “text”. -* `"double-quoted text"` → “double-quoted text” -* `'single-quoted text'` → ‘single-quoted text’ -* `don't` → don’t. as well as anything-else’t. (But foo'tbar is just foo'tbar.) -* `it's` → it’s, as well as anything-else’s (except not foo'sbar and the like.) -* `(tm)` → ™ -* `(r)` → ® -* `(c)` → © -* `1/4th` → 1/4th. Same goes for 1/2 and 3/4. -* `...` or `. . .` → … -* `---` → — -* `--` → – -* `A^B` becomes A^B. Complex superscripts can be enclosed in brackets, so `A^(B+2)` → A^(B+2). - - -#### Icons - -{{hs}} bundles the [FontAwesome][fa] icon font. To prepend an icon to text you can use Discount's _class:_ pseudo-protocol, and specify a valid [fa-*](class:kwd) (non-alias) class. - -Examples: - -> %responsive% -> Source | Output -> -----------------------------------------|------------ -> `[a paper plane](class:fa-paper-plane)` | [ a paper plane](class:fa-paper-plane) -> `[Galactic Empire](class:fa-empire)` | [ Galactic Empire](class:fa-empire) -> `[Rebel Alliance](class:fa-rebel)` | [ Rebel Alliance](class:fa-rebel) - -> %tip% -> Tip -> -> See the [FontAwesome Icon Reference][fa-icons] for a complete list of all CSS classes to use for icons (aliases are not supported). - -#### Badges - -Badges are normally just shorthands for [Icons](#Icons) formatted with different colors. To add a _badge_ to some inline text, use the corresponding class among those listed in the following table. For example, the following code: - - [Genoa, Italy](class:geo) - -produces the following result: - -[Genoa, Italy](class:geo) - -{{hs}} currently supports the following badges: - -> %responsive% -> Class | Badge | Class | Badge -> ---------------------|------------------------------|-------------------------------------------- -> `todo` | [](class:todo) |`user` | [](class:user) -> `fixme` | [](class:fixme) |`tag` | [](class:tag) -> `deadline` | [](class:deadline) |`tags` | [](class:tags) -> `draftcomment` | [](class:draftcomment) |`attachment` | [](class:attachment) -> `urgent` | [](class:urgent) |`bug` | [](class:bug) -> `verify` | [](class:verify) |`geo` | [](class:geo) -> `project` | [](class:project) |`eur` | [](class:eur) -> `red-circle` | [](class:red-circle) |`gbp` | [](class:gbp) -> `yellow-circle` | [](class:yellow-circle) |`usd` | [](class:usd) -> `green-circle` | [](class:green-circle) |`rub` | [](class:rub) -> `gray-circle` | [](class:gray-circle) |`jpy` | [](class:jpy) -> `star` | [](class:star) |`btc` | [](class:btc) -> `heart` | [](class:heart) |`try` | [](class:try) -> `square` | [](class:square) |`krw` | [](class:krw) -> `check` | [](class:check) |`inr` | [](class:inr) -> `lock` | [](class:lock) |`danger` | [](class:danger) -> `unlock` | [](class:unlock) |`question` | [](class:question) -> `email` | [](class:email) |`website` | [](class:website) -> `phone` | [](class:phone) |`fax` | [](class:fax) -> `tm` | [](class:tm) |`reg` | [](class:reg) -> `copy` | [](class:copy) |`red-flag` | [](class:red-flag) -> `green-flag` | [](class:green-flag) |`yellow-flag` | [](class:yellow-flag) -> `story` | [](class:story) |`feature` | [](class:feature) -> `add` | [](class:add) |`remove` | [](class:remove) -> `time` | [](class:time) |`date` | [](class:date) -> `html5` | [](class:html5) |`css3` | [](class:css3) -> `apple` | [](class:apple) |`windows` | [](class:windows) -> `linux` | [](class:linux) |`android` | [](class:android) -> `idea` | [](class:idea) |`link` | [](class:link) -> `chrome` | [](class:chrome) |`firefox` | [](class:firefox) -> `ie` | [](class:ie) |`edge` | [](class:edge) -> `safari` | [](class:safari) |`opera` | [](class:opera) -> `sticky` | [](class:sticky) |`bluetooth` | [](class:bluetooth) -> `wifi` | [](class:wifi) |`signal` | [](class:signal) -> `usb` | [](class:usb) |`print` | [](class:print) - -#### HastyScribe Logo - -To display the {{hs}} logo, use the [hastyscribe](class:kwd) class, like this: - -`[](class:hastyscribe)` → [](class:hastyscribe) - - -#### Links - -> %responsive% -> Source | Output -> ----------------------------------------|------------ -> `[H3RALD](https://h3rald.com/)` | [H3RALD](https://h3rald.com/) -> `[H3RALD](https://h3rald.com/ "H3RALD")`| [H3RALD](https://h3rald.com/ "H3RALD") -> `<https://h3rald.com>` | <https://h3rald.com> - -Additionally, you can define placeholders for URLs and link titles, like this: - -`[h3rald]: https://h3rald.com/ "Fabio Cevasco's Web Site"` - -And use them in hyperlinks (note the usage of square brackets instead of round brackets): - -`[H3RALD][h3rald]` - -> %sidebar% -> Link Icons -> -> {{hs}} automatically adds an envelope icon to email links, an arrow icon to links to external web sites, and logo icons to links to well-known web sites: -> -> * [h3rald@h3rad.com](mailto:h3rald@h3rald.com) -> * [@h3rald](https://twitter.com/h3rald) -> * [fabiocevasco](http://it.linkedin.com/in/fabiocevasco) - -### Block-level Formatting - -#### Headings - -Headings can be specified simply by prepending [#](class:kwd)s to text, as follows: - -~~~ -# Heading 1 -## Heading 2 -### Heading 3 -#### Heading 4 -##### Heading 5 -###### Heading 6 -~~~ - -> %note% -> Note -> -> If you use [Document Headers](#Document.Headers), A [H1](class:kwd) is used for the title of the {{hs}} document. Within the document, start using headings from [H2](class:kwd). - -#### Tables - -{{hs}} supports [PHP Markdown Extra][pme] table syntax using pipes and dashes. - -{{input-text}} - -~~~ -Column Header 1 | Column Header 2 | Column Header 3 -----------------|-----------------|---------------- -Cell 1,1 | Cell 1,2 | Cell 1, 3 -Cell 2,1 | Cell 2,2 | Cell 2, 3 -Cell 3,1 | Cell 3,2 | Cell 3, 3 -~~~ - -{{output-text}} - -Column Header 1 | Column Header 2 | Column Header 3 -----------------|-----------------|---------------- -Cell 1,1 | Cell 1,2 | Cell 1, 3 -Cell 2,1 | Cell 2,2 | Cell 2, 3 -Cell 3,1 | Cell 3,2 | Cell 3, 3 - -> %note% -> Note -> -> Multi-row cells are not supported. If you need more complex tables, use HTML code instead. - - -> %sidebar% -> Responsive Tables -> -> To make tables responsive, put them in a _responsive_ block, like in the previous example. The [responsive](class:kwd) class causes a table not to shrink and makes it scrollable horizontally on small devices. - -#### Block Quotes - -Block quotes can be created simply by prepending a [>](class:kwd) to a line, and they can be nested by prepending additional [>](class:kwd)s. - -{{input-text}} - -~~~ -> This is a block quote. -> > This is a nested quote. -~~~ - -{{output-text}} - -> This is a block quote. -> > This is a nested quote. - -#### Code Blocks - -To format a block of source code, indent it by at least four spaces. Here's the result: - - proc encode_image_file*(file, format): string = - if (file.existsFile): - let contents = file.readFile - return encode_image(contents, format) - else: - echo("Warning: image '"& file &"' not found.") - return file - -Alternatively, you can also use Github-style fenced blocks, by adding three tildes (~~~) before and after the source code. - -> %warning% -> Warning -> -> {{hs}} does not support syntax highlighting for code blocks. To do so, it would require Javascript and {{hs}} is currently kept purposedly "Javascript-free". - - -#### Images - -{{input-text -> The following HastyScribe Markdown code:}} - -~~~ - -~~~ - -{{output-text -> Produces the following output:}} - - - -> %tip% -> Tip -> -> You can use URL placeholders for images as well, exactly like for links. - -> %warning% -> Limitations on automatic image download -> -> {{hs}} will attempt to download all HTTP image links. Note that: -> -> * If no response is received within 5 seconds, the download will be aborted. -> * Connecting through a proxy is currently not supported. -> * To download an image via HTTPS, you must explicitly recompile {{hs}} with [-d:ssl](class:kwd) and OpenSSL must be installed on your system. -> -> If {{hs}} is unable to download an image, it will leave it linked. - - -#### Lists - -##### Unordered Lists - -{{input-text}} - -~~~ -* An item -* Another item -* And another... -~~~ - -{{output-text}} - -* An item -* Another item -* And another... - -##### Ordered Lists - -{{input-text}} - -~~~ -1. First item -2. Second item -3. Third item -~~~ - -{{output-text}} - -1. First item -2. Second item -3. Third item - -> %tip% -> Tip -> -> You don't have to write numbers in order -- any number followed by a dot will do. - -##### Alphabetical Lists - -{{input-text}} - -~~~ -a. First item -b. Second item -c. Third item -~~~ - -{{output-text}} - -a. First item -d. Second item -c. Third item - -> %tip% -> Tip -> -> You don't have to write letters in order -- any letter followed by a dot will do. - - -##### Unstyled Lists - -{{input-text}} - -~~~ -> %unstyled% -> * An item -> * Another item -> * And another... -~~~ - -{{output-text}} - -> %unstyled% -> * An item -> * Another item -> * And another... - - -##### Nested Lists - -To create a list within a list, simply indent the whole nested list with four space. - - -{{input-text}} - -~~~ -* This is a normal list -* Another item - * A nested unordered list - * Another item -* Back in the main list - a. A nested alphabetical list - b. Another item -~~~ - -{{output-text}} - -* This is a normal list -* Another item - * A nested unordered list - * Another item -* Back in the main list - a. A nested alphabetical list - b. Another item - -##### Definition Lists - -In some cases you may want to write a list of terms and their corresponding definitions. You could use an ordinary unordered list, but semantically speaking the _proper_ type of list to use in this case is a definition list. - -{{input-text}} - -~~~ -unordered list -: A list for unordered items. Also called _bulleted list_. -ordered list -: A list for ordered items. Also called _numbered list_. -alphabetical list -: Technically speaking just an ordered list, but formatted with letters instead - of numbers -definition list -: A list of terms and definitions. -~~~ - -{{output-text}} - -unordered list -: A list for unordered items. Also called _bulleted list_. -ordered list -: A list for ordered items. Also called _numbered list_. -alphabetical list -: Technically speaking just an ordered list, but formatted with letters instead - of numbers -definition list -: A list of terms and definitions. - -Alternatively, you can write the above definition list as follows: - -~~~ -=unordered list= - A list for unordered items. Also called _bulleted list_. -=ordered list= - A list for ordered items. Also called _numbered list_. -=alphabetical list= - Technically speaking just an ordered list, but formatted with letters instead - of numbers -=definition list= - A list of terms and definitions. -~~~ - - -#### Class Blocks - -##### Notes - -[Discount][discount] supports the definition of _class blocks_: [div](class:kwd)s with a class attribute. The syntax is very similar to the one used for [block quotes](#Block.Quotes), with the addition of the class name wrapped in [%](class:kwd)s on the first line. - -In {{hs}}, this syntax is used to produce notes, [tips](#Tips), [warmings](#Warnings), [sidebars](#Sidebars) and [terminal sessions](#Terminal.Sessions). - -{{input-text}} - -~~~ -> %note% -> Note -> -> This is a note. -~~~ - -{{output-text}} - -> %note% -> Note -> -> This is a note. - -##### Tips - -Tips are used for optional information that can help the user in some way. - -{{input-text}} - -~~~ -> %tip% -> Tip -> -> This is a tip. -~~~ - -{{output-text}} - -> %tip% -> Tip -> -> This is a tip. - -##### Warnings - -Warnings are used for important information the user should not overlook. - -{{input-text}} - -~~~ -> %warning% -> Warning -> -> This is a warning or an important note. -~~~ - -{{output-text}} - -> %warning% -> Warning -> -> This is a warning or an important note. - -##### Sidebars - -Sidebars are used for digressions and asides. - -{{input-text}} - -~~~ -> %sidebar% -> This is a _sidebar_ -> -> Although not always placed on the side of the page, _sidebars_ contain -> additional content and asides. -~~~ - -{{output-text}} - -> %sidebar% -> This is a _sidebar_ -> -> Although not always placed on the side of the page, _sidebars_ contain additional content and asides. - - -##### Terminal Sessions - -Terminal sessions are used to display commands entered in a terminal, in sequence, without displaying their output. - -{{input-text}} - -~~~ -> %terminal% -> -> cd src -> -> ./configure -> -> make && sudo make install -~~~ - -{{output-text}} - -> %terminal% -> cd src -> -> ./configure -> -> make && sudo make install - -If commands must be executed as a super-user, use the [terminal-su](class:kwd) class instead: - -{{input-text}} - -~~~ -> %terminal-su% -> -> shutdown -h now -~~~ - -{{output-text}} - -> %terminal-su% -> -> shutdown -h now - -## Credits - -HastyScribe is powered by the following open source software (see [LICENSE.md]({{repo}}/blob/master/LICENSE.md) for licensing details): - -* The wonderful [Discount][discount] C library, used to parse markdown code. -* The ...awesome [FontAwesome][fa] font, used for all the icons. -* The beautiful [Mr Bedfort][sudtipos] font, used as the base for the {{hs}} logo. -* The neat [Source Sans Pro](https://store1.adobe.com/cfusion/store/html/index.cfm?event=displayFontPackage&code=1959) and [Source Code Pro](http://store1.adobe.com/cfusion/store/html/index.cfm?event=displayFontPackage&code=1960) fonts, used for all standard text. - -Special thanks to: - -* Philip Wernersbach and Joshua Ellis, for contributing to {{hs}}. -* Andreas Rumpf, creator of the amazing [Nim][nim] programming language, used to implement {{hs}}. -* Ethan Lai, developer of the handy [Koala](http://koala-app.com/) app, used to compile all the LESS code into CSS. - -->  <- - - -[nim]: http://nim-lang.org/ -[df]: https://daringfireball.net/projects/markdown/ -[discount]: http://www.pell.portland.or.us/~orc/Code/discount/ -[pandoc]: http://johnmacfarlane.net/pandoc/ -[md-syntax]: https://daringfireball.net/projects/markdown/syntax -[fa]:http://fortawesome.github.io/Font-Awesome/ -[fa-icons]:http://fortawesome.github.io/Font-Awesome/icons/ -[pme]:http://michelf.com/projects/php-markdown/extra/ -[sudtipos]:http://www.sudtipos.com/ -[release]:{{release -> https://github.com/h3rald/hastyscribe/releases/download/v}} -[nifty]: https://github.com/h3rald/nifty +{@ -overview.md || 1 @} +{@ -getting-started.md || 1 @} +{@ -usage.md || 1 @} +{@ -syntax.md || 1 @} +{@ -credits.md || 1 @}
M
hastyscribe.nim
→
hastyscribe.nim
@@ -141,12 +141,49 @@ create_font_face(sourcesanspro_boldit_font, "Source Sans Pro", "italic", 800)
] return style_tag(fonts.join); +proc preprocess(hs: var HastyScribe, document, dir: string, offset = 0): string + +proc applyHeadingOffset(contents: string, offset: int): string = + if offset == 0: + return contents + let peg_heading = peg"""heading <- (^ / \n){'#'+}""" + var handleHeading = proc (index: int, count: int, matches: openArray[string]): string = + let heading = matches[0] + result = "\n" & "#".repeat(heading.len + offset) + return contents.replace(peg_heading, handleHeading) + +# Transclusion with heading offset: +# {@ some/file.md || 1 @} +proc parse_transclusions(hs: var HastyScribe, document: string, dir = "", offset = 0): string = + result = document.applyHeadingOffset(offset) + let peg_transclusion = peg""" + transclusion <- '{\@' \s* {path} \s* '||' \s* {offset} \s* '\@}' + path <- [^|]+ + offset <- [0-5] + """ + var cwd = dir + if cwd != "": + cwd = cwd & "/" + for transclusion in document.findAll(peg_transclusion): + var matches: array[0..1, string] + discard transclusion.match(peg_transclusion, matches) + let path = cwd & matches[0].strip + let value = matches[1].strip + let offset = value.split("||")[0].parseInt() + if path.fileExists(): + let fileInfo = path.splitFile() + let contents = path.readFile() + result = result.replace(transclusion, hs.parse_transclusions(contents, fileInfo.dir, offset)) + else: + stderr.writeLine "Warning: File '$1' not found" % [path] + result = result.replace(transclusion, "") + # Macro Definition: -# {{#test -> This is a $1}} +# {#test -> This is a $1} # # Macro Usage: -# {{#test||simple test}} -proc parse_macros(hs: var HastyScribe) = +# {#test||simple test} +proc parse_macros(hs: var HastyScribe, document: string): string = let peg_macro_def = peg""" definition <- '{#' \s* {id} \s* '->' {@} '#}' id <- [a-zA-Z0-9_-]+@@ -155,15 +192,15 @@ let peg_macro_instance = peg"""
instance <- "{#" \s* {id} \s* "||" \s* {@} "#}" id <- [a-zA-Z0-9_-]+ """ - var doc = hs.document - for def in findAll(hs.document, peg_macro_def): + result = document + for def in document.findAll(peg_macro_def): var matches: array[0..1, string] discard def.match(peg_macro_def, matches) let id = matches[0].strip let value = matches[1].strip hs.macros[id] = value - doc = doc.replace(def, "") - for instance in findAll(doc, peg_macro_instance): + result = result.replace(def, "") + for instance in findAll(result, peg_macro_instance): var matches: array[0..1, string] discard instance.match(peg_macro_instance, matches) let id = matches[0].strip@@ -171,39 +208,37 @@ let value = matches[1].strip
let params = value.split("||") if hs.macros.hasKey(id): try: - doc = doc.replace(instance, hs.macros[id] % params) + result = result.replace(instance, hs.macros[id] % params) except: stderr.writeLine "Warning: Incorrect number of parameters specified for macro '$1'\n -> Instance: $2" % [id, instance] else: stderr.writeLine "Warning: Macro '" & id & "' not defined." - doc = doc.replace(instance, "") - hs.document = doc + result = result.replace(instance, "") # Field Usage: # {{$timestamp}} -proc parse_fields(hs: var HastyScribe) = +proc parse_fields(hs: var HastyScribe, document: string): string = let peg_field = peg""" field <- '{{' \s* '$' {id} \s* '}}' id <- [a-zA-Z0-9_-]+ """ - var doc = hs.document - for field in hs.document.findAll(peg_field): + result = document + for field in document.findAll(peg_field): var matches:array[0..0, string] discard field.match(peg_field, matches) var id = matches[0].strip if hs.fields.hasKey(id): - doc = doc.replace(field, hs.fields[id]()) + result = result.replace(field, hs.fields[id]()) else: stderr.writeLine "Warning: Field '" & id & "' not defined." - doc = doc.replace(field, "") - hs.document = doc + result = result.replace(field, "") # Snippet Definition: # {{test -> My test snippet}} # # Snippet Usage: # {{test}} -proc parse_snippets(hs: var HastyScribe) = +proc parse_snippets(hs: var HastyScribe, document: string): string = let peg_snippet_def = peg""" definition <- '{{' \s* {id} \s* '->' {@} '}}' id <- [a-zA-Z0-9_-]+@@ -215,32 +250,36 @@ """
type TSnippetDef = array[0..1, string] TSnippet = array[0..0, string] - var doc = hs.document - for def in findAll(hs.document, peg_snippet_def): + result = document + for def in document.findAll(peg_snippet_def): var matches:TSnippetDef discard def.match(peg_snippet_def, matches) var id = matches[0].strip var value = matches[1].strip(true, false) hs.snippets[id] = value - doc = doc.replace(def, value) - for snippet in findAll(hs.document, peg_snippet): + result = result.replace(def, value) + for snippet in document.findAll(peg_snippet): var matches:TSnippet discard snippet.match(peg_snippet, matches) var id = matches[0].strip if hs.snippets[id] == nil: stderr.writeLine "Warning: Snippet '" & id & "' not defined." - doc = doc.replace(snippet, "") + result = result.replace(snippet, "") else: - doc = doc.replace(snippet, hs.snippets[id]) - hs.document = doc + result = result.replace(snippet, hs.snippets[id]) + +proc preprocess(hs: var HastyScribe, document, dir: string, offset = 0): string = + result = hs.parse_transclusions(document, dir, offset) + result = hs.parse_fields(result) + result = hs.parse_snippets(result) + result = hs.parse_macros(result) + -proc compileFragment*(hs: var HastyScribe, input: string): string {.discardable.} = +proc compileFragment*(hs: var HastyScribe, input, dir: string): string {.discardable.} = hs.options.input = input hs.document = hs.options.input - # Parse fields, snippets, and macros - hs.parse_fields() - hs.parse_snippets() - hs.parse_macros() + # Parse transclusions, fields, snippets, and macros + hs.document = hs.preprocess(hs.document, dir) # Process markdown hs.document = hs.document.md(MKD_EXTRA_FOOTNOTE or MKD_NOHEADER) return hs.document@@ -248,10 +287,8 @@
proc compileDocument*(hs: var HastyScribe, input, dir: string): string {.discardable.} = hs.options.input = input hs.document = hs.options.input - # Parse fields, snippets, and macros - hs.parse_fields() - hs.parse_snippets() - hs.parse_macros() + # Parse transclusions, fields, snippets, and macros + hs.document = hs.preprocess(hs.document, dir) # Document Variables var main_css_tag = stylesheet.style_tag@@ -342,7 +379,7 @@ else:
output = hs.options.output if hs.options.fragment: - hs.compileFragment(input) + hs.compileFragment(input, inputsplit.dir) else: hs.compileDocument(input, inputsplit.dir) if output != "-":