# Overview

{{hs -> HastyScribe}} is a self-contained {{mdlink -> [Markdown][df]}} compiler that can create single-file HTML documents. All documents created by {{hs}} 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-face-smile)).

### 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. 

### Content Transclusion

When managing long documents, you can take advantage of {{hs}}'s [transclusion](#Transclusion) support to split your content into several files, and transclude them as you see fit.

### 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).