Text on its own is converted to a paragraph element:

This is one paragraph.

This is another paragraph;
you can use single newlines
to hard-wrap your text if
you prefer.

To create a code block, place at least three backticks (```) on a line before your code, and the same number on a line after it. The code will be taken verbatim, and no Nimble syntax will be parsed within the block.

Here is a simple Perl script:

```
#!/usr/bin/perl -w
use strict;

print "Hello, world!\n";
```

When run, it prints `Hello, world!`.

#!/usr/bin/perl -w
use strict;

print "Hello, world!\n";

Nimble documents can define any number of key-value pairs which are returned by the parser in addition to the other parts of the document. (Check your parser's documentation for how to access them.) They are useful for specifying values that need to be used outside the Nimble document, such as the page title, related tags, or the name of the author. The code using your document can use these values however it likes. Attribute values are a single line of raw text — they do not get parsed as Nimble markup. To define an attribute, write @name value:

@title How to slay a dragon in twelve easy steps
@author King Arthur
@tags dragonslaying, self-help guides

To kill a dragon...

Again, these attributes aren't used by Nimble. They're merely returned by the parser for use elsewhere. For example, with the above document, the application might choose to put the @title within part of the page's <title> tags, use the @author to link the article from the author's page, and split the @tags by commas to index them in a database.

Several kinds of lists are supported by Nimble syntax.

An unordered list is simply a series of items for which the order is irrelevant. It is often drawn as a bulletted list, and so Nimble uses lines prefixed by asterisks (*) to indicate elements of an unordered list:

Today's menu:

* Roast flank of dragon
* Dragon ribs with a honey glaze
* Dragonscale stew with fresh bread

Lists allow nesting; you can put several elements within a list, such as paragraphs and other lists:

Places I'd like to visit:

* The dragon's cave
  
  Why?
  * It's full of tasty dragon meat
  * Also probably treasure
* The castle kitchen
  * It's /also/ full of tasty dragon meat
    * (we just killed a dragon)

An ordered list is a series of items for which the order does matter. It is often drawn as a numbered list, and so Nimble uses lines prefixed by numbers and a dot (1., 2., ...) or just a number sign and a dot (#.) if you'd like the item to be numbered automatically:

Top three reasons to kill a dragon:

3. They're scary.
2. Their treasure.
1. There is tasty meat.

How to kill a dragon:

#. Hire a fighter with a proven track
   record for killing dragons.
#. Hire a bunch of clerics to constantly
   heal the fighter.
#. Hire at least twelve high-level wizards.
   
   Seriously, more like a hundred would be better.
#. Tell them to go kill the dragon.
#. At this point, there are only two outcomes:
   * They kill the dragon; pay them
     with part of its vast treasure.
   * The dragon kills them; don't
     pay them.  That would be silly.

As shown above, by continuing the indent level of the first line of a list item, sub-elements are placed within that item.

A definition list is a list of topics and their definitions. Topics are given on lines starting with a question mark (?), and definitions are given on lines starting with an equals sign (=). A definition list must begin with a topic, after which topics and definitions can be freely intermixed in any amounts.

Parts of a dragon:

? Mouth
= Contains teeth
= Can breathe fire
? Claws
= Very pointy, probably avoid
? Tasty meats
= ? Flank
  = Good for cooking on its own
  ? Ribs
  = Let's try this one with a honey glaze
  ? Other bits
  = Maybe turn them into a stew?
? Scales
= Good for fashioning into armor!

A figure is a self-contained piece of content that often has a caption and is referred to from the main document. A figure's contents and optional caption are all contained by a block starting with a percent symbol (%); a caption is denoted by a sub-element block starting with an equals sign (=). When rendering to HTML, if a caption is used, there should only be one at either the start or the end of the figure.

% ```
  #!/usr/bin/perl -w
  use strict;
  
  use Dragon::Meat;
  
  my $bits = Dragon::Meat::bits->new("tasty");
  my $stew = $bits->dice->cook;
  ```
  = Mom's recipe for Dragon stew.

#!/usr/bin/perl -w
use strict;

use Dragon::Meat;

my $bits = Dragon::Meat::bits->new("tasty");
my $stew = $bits->dice->cook;

A blockquote is a block-level quotation; it is similar to merely writing something like He said, "how are you?", but is more semantically meaningful and often uses styling meant for larger sections of text. A blockquote is indicated by a line starting with a quotation mark ("). To include a citation, add a sibling block-level element starting with a dash (-); in the HTML renderer, this will place the quotation's resulting <blockquote> in a <figure> with CSS class quote and the citation in a corresponding <figcaption>.

Just a blockquote:

" I once killed a dragon the size of a castle!

A blockquote with a citation:

" Wow, these dragons sure are delicious!
- Anybody who has tasted one.

Much like in HTML, there are two ways to semantically define the outline of your document. The first way, taken from old-style HTML and often seen in other markup languages, is to use headers with explicitly specified depth. In Nimble, you can create an explicit header element (HTML's <h1> – <h6> tags) by starting a line with an exclamation mark (!) immediately followed by a number (1 – 6) to indicate the depth (or no number, which defaults to depth 1).

! All About Dragons

This document covers all aspects of dragons.

!2 Weapons

Stuff to avoid while hunting dragons.

!3 Claws

Pointy. Avoid.

!3 Teeth

Pointier. Definitely avoid.

!2 Meat

Delicious. Bring back to castle.

The second mechanism for defining the outline of your document is by implicitly expressing depth through nested sections. HTML support for this sort of document structure is new as of HTML5. Using sections alleviates many issues with headers with explicit depths; for example, reorganizing a document no longer requires renumbering headers.

Nimble syntax uses a block starting with an open curly brace ({), optionally followed by the section header, to begin a section, and a closed curly brace (}) to end one. In addition, you can simultaneously close any number of sections and optionally start a new one by stacking all of the braces together; for example to close one section and start a new sibling section, you might write }{ Section Title. Any sections left open at the end of the document will be automatically closed.

In HTML rendering, the block started by an open curly brace actually corresponds to a <header> at the start of a section; if the header contains a single paragraph, that paragraph is converted to an <h1> tag.

{ All About Dragons

This document covers all aspects of dragons.

{ Weapons

Stuff to avoid while hunting dragons.

{ Claws

Pointy. Avoid.

}{ Teeth

Pointier. Definitely avoid.

}

}{ Meat

Delicious. Bring back to castle.

}}

Sometimes, like above, it can be clearer to close a section separately from its parent (see Meat, above) rather than all at once (like }}{ Meat).

The contents of a section aren't indented any more than the section itself. Extra elements you'd like to appear within the header of the section are indented, however. For example, a section header with a paragraph subtitle might look like this:

{ ! Nimble markup language -- syntax documentation
  
  An elegant markup language for a more civilized age.

...

}

Because the contents of the above example section's header isn't a lone paragraph, an explicit ! is used to create the <h1> in the section's header element.

Sometimes, you need to include some particular raw data in the middle of your output. Maybe you need to create an HTML tag that isn't supported by Nimble. To do this, Nimble provides a mechanism to produce raw data for a specific output format. When using a raw data declaration, it is up to you to ensure that the output is valid for your output format. Nimble makes no attempt to protect you from invalid output.

Every use of a raw data declaration requires the target output format to be specified. If the current output format does not match the format specified in the raw data declaration, no output is produced.

Block-level syntax for raw data has two ways to use it. For raw data that fits on a single line, use #raw <format> <data>, replacing <format> with the output format for which this raw declaration is enabled, and replacing <data> with the raw text you would like produced at the location of the declaration.

#raw html <aside>

When in HTML output mode, this paragraph
will end up in an `<aside>` block.

#raw html <input type="button" value="Click me!"/>

Another paragraph that will end up
inside the `<aside>` block.

#raw html </aside>

The second way to use block-level syntax allows for multiple lines of raw data. To do this, omit the <data> part of the declaration, and instead merely write #raw <format>. After this, all subsequent lines indented further than the #raw declaration will be treated as raw output.

#raw html
  <table style="width:100%;">
    <tr><td>1</td><td>2</td></tr>
    <tr><td>3</td><td>4</td></tr>
  </table>

There also exists an inline syntax for raw data: anywhere within inline text, write [raw <format> <data>], again replacing <format> with the target output format and <data> with the raw text you would like produced at the location of the declaration. This syntax comes with a caveat: the square brackets must be balanced, but backslashes can be used to escape square brackets or other backslashes if necessary. Thus, [raw html [a]] is legal, but to produce [\[ as raw data using inline syntax, one would write [raw html \[\\\[].

Nimble includes a simple system for defining and reusing custom output structures via macros. A macro is a named set of raw data declarations which support variable substitution. Macros must be declared before they can be used.

Each macro can define a raw data output (called a #result) for each output format you'd like to target; if a macro has no #result for the current output format, no output is produced by the macro. Each macro can also have zero or more arguments (each called an #arg); each argument has a name, whether it should be parsed as nimble markup or raw data, and optionally a default value to use when it is not given.

When a macro is used, arguments of type nimble will be parsed as Nimble text and rendered to the current output format before variable substitution. Arguments of type raw will be passed through verbatim. Examples of this are below.

#macro example

  #arg apple nimble This is /Nimble/-style markup.
  #arg banana raw This text will be taken <em>literally</em>.
  #arg pear nimble
    * This text is the default value for argument `pear`.
    * It will only be used if no `pear` argument is given to the macro.

  #result html <div>{{content}}</div>

#macro phpdoc
  #arg topic raw
  #result html
    <a class="phplink" href="http://php.net/{{topic|urlenc|xmlenc}}">{{topic|xmlenc}}</a>

$example
  apple: The *actual* value for this argument.
  banana:
    This raw text input
    spans several lines.

#macro phpdoc
  #arg topic raw
  #result html
    <a class="phplink" href="http://php.net/{{topic|urlenc|xmlenc}}">{{topic|xmlenc}}</a>

#raw html
  <style>
  /* Add some extra styles to make
     phpdoc links stand out. */
  .phplink {
    background-color: #eeeeee;
    border: 1px solid #777bb4;
    color: #3b3d5a;
    padding-right: 4px;
  }
  .phplink:hover {
    color: #999999;
  }
  .phplink:before {
    content: "php";
    background-color: #777bb4;
    color: #000000;
    padding: 0 4px;
    margin-right: 4px;
  }
  </style>

In PHP, [$phpdoc topic=array_map] takes its callback first,
but [$phpdoc topic=array_filter] takes it last.

/Example/ Nimble *syntax*.

#macro example
  #arg code raw
  #arg result nimble
  #result html
    <table class="example">
      <tr><th>Code</th><th>Result</th></tr>
      <tr><td><pre>{{code|xmlenc}}</pre></td><td>{{result}}</td></tr>
    </table>

$example
  code:
    /Example/ Nimble *syntax*.
  result:
    /Example/ Nimble *syntax*.

/Example/ Nimble *syntax*.

#macro example_html
  #arg code raw
  #arg result raw
  #result html
    <table class="example">
      <tr><th>Code</th><th>Result</th></tr>
      <tr><td><pre>{{code|xmlenc}}</pre></td><td>{{result}}</td></tr>
    </table>

$example_html
  code:
    <s>Strikethrough!</s>
  result:
    <s>Strikethrough!</s>

<s>Strikethrough!</s>

#macro youtube
  #arg id raw
  #result html
    <object width="640" height="390">
      <param name="movie" value="https://www.youtube.com/v/{{id|xmlenc}}?version=3"></param>
      <param name="allowScriptAccess" value="always"></param>
      <embed src="https://www.youtube.com/v/{{id|xmlenc}}?version=3"
             type="application/x-shockwave-flash"
             allowscriptaccess="always"
             width="640" height="390"></embed>
    </object>

$youtube
  id: w-nBuRToaNQ

#macro citation_needed
  #result html <sup>[citation needed]</sup>

That dragon was delicious. [$citation_needed]

#macro ref
  #arg id raw
  #result html
    <sup
      ><a href="#cite-{{id|urlenc|xmlenc}}">[{{id|xmlenc}}]</a
    ></sup>

#macro cite
  #arg id raw
  #arg text nimble
  #result html
    <div>
      <a name="cite-{{id|xmlenc}}" id="cite-{{id|xmlenc}}"></a>
      {{id|xmlenc}}. {{text}}
    </div>

That dragon was delicious.[$ref id=1]  We could catch another
in that cave.[$ref id=2]

[$cite id=1 text="I should know; I just ate it."]
[$cite id=2 text="I just saw a dragon in that cave."]

The HTML output format tries to produce semantically-useful HTML5 — sections ({ ... }) are <section>s, blockquotes with citations are contained within <figure>s, and so forth.

In general, the HTML renderer tries to keep stray whitespace within tags rather than outside them. This prevents extra text nodes from being generated. For example, paragraphs might look like this:

<p>paragraph 1</p
><p>paragraph 2</p
><p>paragraph 3</p
>

This is valid HTML; when an application reads it, it will generate only a series of paragraph nodes with no intervening text nodes containing merely unnecessary newlines. This means that newline-separated inline or inline-block elements won't have extra spaces between them, and any JavaScript using the Node.childNodes DOM interface will only see the nodes you intended.

You can see an example of HTML output from Nimble by viewing the source of this page, specifically the section within the <article> tags.