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 %, 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 % - in the third line.

Transclusion

When writing a long document, it is often useful to split it into many different files, to manage its contents better. {{hs}} provides basic content transclusion support through the following syntax:

{@ my-file.md || 1 @}

When a file is processed, the line above will cause the contents of file my-file.md to be included in the current file, as if they were part of it. Additionally, when using content transclusion syntax, it is mandatory to specify a number between 0 and 5 to indicate the offset of the headings present in the transcluded file. In this example, the heading numbers of all headings present in my-file.md will be increased by 1, so any h2 will become h3, any h3 will become h4, and so on.

%warning% Limitations

• It is recommended to place all transcluded files in the same folder as the transcluding file. If a transcluded file includes any image, its relative path will be interpreted as if it was relative to the transcluding file.
• Heading offset will only work if headings are created using #s. Underline syntax for h1 and h2 is not supported.

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 which is transformed into the text "This is a test snippet.".

{{test -> This is a test snippet.}}

Once a snippet is defined anywhere in the document, you can use its identifier wrapped in double curly brackets ({{test}}} in the previous example) anywhere in the document to reuse the specified text.

%sidebar% Alternative Snippet Definition Syntax

When a document is compiled, both snippets and snippet defininotions are evaluated to their body text. To avoid snippet definitions being evaluated, you can use a double arrow (=>) in the definition:

{{test => This snippet definition will not be evaluated to its 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
{{$timestamp}}	{{$timestamp}}
{{$date}}	{{$date}}
{{$full-date}}	{{$full-date}}
{{$long-date}}	{{$long-date}}
{{$medium-date}}	{{$medium-date}}
{{$short-date}}	{{$short-date}}
{{$short-time}}	{{$short-time}}
{{$short-time-24}}	{{$short-time-24}}
{{$time}}	{{$time}}
{{$time-24}}	{{$time-24}}
{{$day}}	{{$day}}
{{$short-day}}	{{$short-day}}
{{$month}}	{{$month}}
{{$short-month}}	{{$short-month}}
{{$year}}	{{$year}}
{{$short-year}}	{{$short-year}}
{{$weekday}}	{{$weekday}}
{{$weekday-abbr}}	{{$weekday-abbr}}
{{$month-name}}	{{$month-name}}
{{$month-name-abbr}}	{{$month-name-abbr}}
{{$timezone-offset}}	{{$timezone-offset}}

Additionally, you can define your own custom fields via command-line parameters, using the --field/ 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 and product fields within my-document.md using {{$product}} and {{$version}}.

Macros

If snippets are not enough, and you want to reuse chunks of similar content, you can define substitution macros using the following syntax:

{#greet => Hello, $1! Are you $2?#}

This defines a macro called greet that takes two parameters which will be substituted instead of $1 and $2. To use the macro, use the following syntax:

{#greet||Fabio||ready#}

%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).
• You can define macros using either -> or =>, although => is preferred.

{@ -syntax-inline.md || 1 @}

{@ -syntax-block.md || 1 @}