What is Norg?

The Norg syntax is a structured plain-text file format which aims to be human-readable when viewed standalone while also providing a suite of markup utilities for typesetting structured documents. Compared to other plain-text file formats like e.g. Markdown, Org, RST or AsciiDoc, it sets itself apart most notably by following a strict philosophy to abide by the following simple rules:

1. Consistency the syntax should be consistent. Even if you know only a part of the syntax, learning new parts should not be surprising and rather feel predictable and intuitive.

2. Unambiguity the syntax should leave no room for ambiguity. This is especially motivated by the use of tree-sitter for the original syntax parser, which takes a strict left-to-right parsing approach and only has single-character look-ahead.

3. Free-form whitespace is only used to delimit tokens but has no other significance! This is probably the most contrasting feature to other plain-text formats which often adhere to the off-side rule, meaning that the syntax relies on whitespace-indentation to carry meaning.

Although built with Neorg in mind, Norg can be utilized in a wide range of applications, from external note-taking plugins to even messaging applications. Thanks to its layer system one can choose the feature set they'd like to support and can ignore the higher levels.

Characters

A Norg file is made up of characters. A character is any Unicode code point or grapheme.

Words

The Norg format is designed to be parsed on a word-by-word basis from left-to-right through the entire document in a single pass. This is possible because the language is free-form, meaning that whitespace has no semantic meaning, and because the markup follows strict rules which are outlined in the later sections of this document.

A word is considered to be any combination of characters which are neither whitespace nor punctuation (see regular characters).

Paragraph Segments

Words are first combined into paragraph segments. A paragraph segment may then contain any inline element of type:

• attached modifiers

• linkables

Usually, a line ending terminates the paragraph segment. This means that a paragraph segment is for the most part just a line of text:

    
           I am a paragraph segment.
   I am another paragraph segment.
   Together we form a paragraph.

    

Structural Detached Modifiers

The first detached modifier type is the structural modifier type. As the name suggests, modifiers under this category structure the Norg document in some form or another.

After a structural modifier, one paragraph segment is consumed as the title of the modifier.

A property of structural detached modifiers is that they consume all other non-structural detached modifiers, lower-level structural modifiers, inline markup and paragraphs; they are the most important detached modifier in the hierarchy of modifiers.

To manually terminate a structural detached modifier (like a heading) you must use a delimiting modifier. Structural detached modifiers are automatically closed when you use another structural modifier of the same or lower level.

    
            * Heading level 1
    ** Heading level 2
    *** Heading level 3
    **** Heading level 4
    ***** Heading level 5
    ****** Heading level 6
    ******* Heading level 7 (falls back to level 6 in the tree-sitter parser)

    

Although headings are both structural and nestable (see next section), the former takes precedence over the latter, meaning that headings only affect a single paragraph segment as their title. This is for user convenience as it does not require an empty line right below a heading. Because of this precedence, headings are also non-grouping.

Headings serve as a way to categorize and organize other elements into smaller chunks for better readability. They are currently the only structural detached modifier present in the Norg syntax.

Nestable Detached Modifiers

Nestable detached modifiers are a kind which may be repeated multiple times in order to produce a nested object of the given type. The nesting levels are capped at 6 in the tree-sitter parser but longer repetitions of the same modifier are allowed, falling back to the sixth nesting level. Other parsers may choose to support higher (or infinite) nesting levels.

Furthermore, in contrast to most other (standard) detached modifiers, this detached modifier type has no title, and affects the following paragraph instead of only the next paragraph segment. Said paragraph then becomes the modifier's content. This means that in order to terminate the detached modifier contents, you need an empty line (see paragraph break).

Below you will find some examples of nestable detached modifiers.

    
            - Unordered list level 1
    -- Unordered list level 2
    --- Unordered list level 3
    ---- Unordered list level 4
    ----- Unordered list level 5
    ------ Unordered list level 6
    ------- Unordered list level 7 (falls back to level 6 in the tree-sitter parser)

    - Unordered list level 1
      This text is still part of the level 1 list item.
    -- Unordered list level 2
       This text is still part of the level 2 list item.
    --- Unordered list level 3
        This text is still part of the level 3 list item.
    ---- Unordered list level 4
         This text is still part of the level 4 list item.
    ----- Unordered list level 5
          This text is still part of the level 5 list item.
    ------ Unordered list level 6
           This text is still part of the level 6 list item.
    ------- Unordered list level 7 (falls back to level 6 in the tree-sitter parser)
            This text is still part of the level 7 list item.

    

Unordered lists provide an easy way to enumerate items in an unordered fashion. Useful for data that's categorically similar but doesn't need to follow a strict order.

    
            ~ Ordered list level 1
    ~~ Ordered list level 2
    ~~~ Ordered list level 3
    ~~~~ Ordered list level 4
    ~~~~~ Ordered list level 5
    ~~~~~~ Ordered list level 6
    ~~~~~~~ Ordered list level 7 (falls back to level 6 in the tree-sitter parser)

    ~ Ordered list level 1
      This text is still part of the level 1 list item.
    ~~ Ordered list level 2
       This text is still part of the level 2 list item.
    ~~~ Ordered list level 3
        This text is still part of the level 3 list item.
    ~~~~ Ordered list level 4
         This text is still part of the level 4 list item.
    ~~~~~ Ordered list level 5
          This text is still part of the level 5 list item.
    ~~~~~~ Ordered list level 6
           This text is still part of the level 6 list item.
    ~~~~~~~ Ordered list level 7 (falls back to level 6 in the tree-sitter parser)
            This text is still part of the level 7 list item.

    

This list type is only useful for data that needs to be kept in sequence. In contrast to other formats which may use a syntax like 1./1), Norg counts the items automatically - this reduces complexity and makes reordering items simple.

    
            > Quote level 1
    >> Quote level 2
    >>> Quote level 3
    >>>> Quote level 4
    >>>>> Quote level 5
    >>>>>> Quote level 6
    >>>>>>> Quote level 7 (falls back to level 6 in the tree-sitter parser)

    > Quote level 1
      This text is still part of the level 1 quote.
    >> Quote level 2
       This text is still part of the level 2 quote.
    >>> Quote level 3
        This text is still part of the level 3 quote.
    >>>> Quote level 4
         This text is still part of the level 4 quote.
    >>>>> Quote level 5
          This text is still part of the level 5 quote.
    >>>>>> Quote level 6
           This text is still part of the level 6 quote.
    >>>>>>> Quote level 7 (falls back to level 6 in the tree-sitter parser)
            This text is still part of the level 7 quote.

    

Quotes are rather self-explanatory - they allow you to cite e.g. a passage from another source.

    
            % attrib1
    %% attrib2
    %%% attrib3
    %%%% attrib4
    %%%%% attrib5
    %%%%%% attrib6

    

Attributes are detached modifiers that exist solely for the purpose of having altered behavior through carryover tags. These can then be referenced within attached modifier extensions and the tags applied to the attribute will be applied to the attached modifier with said attribute.

These modifiers can be nested to create a hierarchy of attributes. Below is an example of this in action:

    
            % color
    +color #FF0000
    %% red
    +color #00FF00
    %% green
    +color #0000FF
    %% blue

    This will be /red/(color:red), /green/(color:green) and /blue/(color:blue).

    

Limits

You can impose limits on where the attribute can be used through the attribute-limits tag, which should be placed before the attribute definition. The tag takes in a list of the following parameters:

• none - no limits

• verbatim - can be used only for the `verbatim` attached modifier

• math - can be only used on the $mathematics$ attached modifier

• macro - can be only used on the inline &macro& attached modifier

• links - can only be used on links (this includes anchors)

• non-verbatim - for all the other non-verbatim attached modifiers (bold, italic, subscript, superscript, underline, the null modifier etc.)

These limits can be chained, i.e. #attribute-limits links non-verbatim.

Invalid Nestable Detached Modifier Examples

    
            >I am not a quote

    some preceding text > I am also not a quote

    >- I am not a valid detached modifier

    > > I am only a level 1 quote

    *
        I am not a valid heading title.

    

Range-able Detached Modifiers

Range-able detached modifiers can occur in two forms:

• As a single detached modifier in which case they affect:

  • The next paragraph_segment which becomes the title

  • Any following paragraph which becomes the content

• As a pair of two detached modifiers in which case:

  • The next paragraph_segment also becomes the title

  • The content continues until the "closing" detached modifier is found

The closing modifier has the same rules as an opening detached modifier except it must be directly succeeded by a line ending in contrast to the whitespace character which must follow the opening modifier.

    
            $ Term
    Definition content.

    

To create longer definitions, use the ranged definition syntax instead:

    
            $$ Term
    Content of the definition.

    Which scans up to the closing modifier.
    $$

    

Footnotes

Footnotes allow the user to give supplementary information related to some text without polluting the paragraph itself. Footnotes can be linked to using linkables.

    
            ^ Single Footnote
    Optional footnote content.

    

Examples

    
            The following items naturally group because they are range-able, for example forming a
    definition list:
    $ Term 1
      Definition 1!
    $ Term 2
      Definition 2!

    

Weak Delimiting Modifier

This modifier uses the - character and immediately closes the current nesting level (decreases the current nesting level by one).

    
            * Heading level 1
      Text under first level heading.

    ** Heading level 2
       Text under second level heading.
       ---

      Text under first level heading again.

    

Strong Delimiting Modifier

This modifier uses the = character and immediately closes all nesting levels.

    
            * Heading level 1
      Text under first level heading.

    ** Heading level 2
       Text under second level heading.
       ===

    Text belonging to no heading level (i.e. belonging to the document's root).

    

Horizontal Rule

This modifier uses the _ character and simply renders a horizontal line. It does NOT affect the heading level but immediately terminates any paragraph.

    
            * Heading level 1
      Text under first level heading.
      ___
      This is a new paragraph separated from the previous one by a horizontal line.
      This text still belongs to the first level heading.

    

TODO Status Extension

The TODO item extension assigns a task status to a certain modifier. You probably know this concept from Org where unordered lists can become tasks. In Norg we take this concept to the next level because any detached modifier can be assigned a task status. This can for example be useful for the author of a document to keep track of the status of certain sections.

The following characters are reserved for the TODO status extension:

• undone (a literal space)

• x done

• ? needs further input/clarification

• ! urgent

• + recurring (with an optional timestamp)

• - in-progress/pending

• = on hold

• _ put down/cancelled

Some examples include:

    
            - ( ) Undone
    - (x) Done

    - (# B| ) Undone with a priority of B
    - (+) Recurring
    - (+ 5th Jan) Recurring every 5th of January

    

Advanced Detached Modifier Extensions

Apart from just being able to assign a TODO state it is also possible to apply more complex states with parameters to certain indicators. Such examples are the timestamp extension and the priority extension. In the following sections you will find descriptions for a few other extensions supported within Norg.

    
             {@ 5th Aug 2022 - 20th August 2022}
     {@ 5th Aug 2022-20th August 2022} <- Also valid

    

    
             {@ 5th - 20th August 2022}

    

    
             * (# A) This heading has priority A (highest priority)

    

    
             - (< Tue 5th Feb) Do this before the 5th of February.

    

    
             - (> Tue 5th Feb) This task starts after the 5th of February.

    

Slide

The slide, denoted with a single :, allows for a set of contiguous complex items below:

    
            - :
      This is some text.
      $ Term
        And this is the term's definition.

    

Examples

    
              - :
        This is part of the list item.
        @code lua
        print("This is also a part of the list item")

        -- Despite the fact that there is a double newline dividing the `print` statement and this
        -- comment, it is not a paragraph break, therefore it does not terminate the slide.
        @end
        $ Term
        Here is a definition!

      Now that there is a {$ paragraph break} between this paragraph and the previous item
      this paragraph no longer belongs to the slide.

    

    
              -- :
         Content of the slide.
      - Because this item is a level lower than the item containing the slide above
        the slide is terminated.

    

Indent Segment

The indent segment, denoted with two colons (::), creates a ranged version of the slide. This indent segment must be closed with any of the delimiting modifiers, or an element of the same type with the same or lower nesting level. By "lower" nesting level we mean higher up in the hierarchy of nodes, or in other words unordered_list_level_1 is "lower" than an unordered_list_level_2 item, because it is nested less.

The indent segment may contain an arbitrary amount of complex items.

Examples:

    
            - ::
      This is some content.

      $ Term
        Definition.
    - This is the second item of the list.
      The indent segment did not need to be terminated.

    - ::
      This is another list.

      |details
      *hello* world!
      |end

      -- This is a nested item in the indent segment
      -- And so is this.

      But you can still continue your content here.
      ---

    Since there was no other item of the same type after the indent segment
    it must be closed with `---` or `===`.

    

Macro Tags

Macro tags (also known as macro definitions) are a tag type designed to declare and define macros. Macros are templates that can be executed with parameters in order to place some structured text into the document.

The content of the macro tag is any Norg markup - this includes structural detached modifiers and nested tags. The macro tag is closed with the =end statement.

Under the hood, all other tag types are implemented as macros with special parameters and contents.

The following is an example of a macro:

    
            =see url
    (see {&url&})
    =end

    

Examples

example`: |example |example * This is an example heading. |end |end `|comment`: |example |comment This is a very long comment with some content and with some markup! * Heading /italic/ and *bold*. |end |end `|details`: |example |details * Here is some hidden markup! Wowzers. |end |end `|group`: |example #color red |group This will be red. So will this. * So will this And this. |end |end **** Edge Cases and Semantic Interpretation A commonly arising question is "how are these interpreted at parse time?" - can you link to elements within `|comment` tags? What governs the behavior of these differing tags? The answer may be illustrated simply by showing how these tags are implemented. As mentioned in the {*** macro tags} section, all tag types (apart from the macro tag) are a macro invocation under the hood. Below are the implementations for `|comment` and `|group`, respectively: - : |example =comment ... =end |end - : |example =group ... &...& =end |end The `|comment` tag evaluates to /no value/. Anything that is placed within a comment during invocation (the `...` parameter) is simply dropped. Because of this it is *not* possible to link to elements within comment tags. The `|group` tag returns everything that you give it, because of this it *is* possible to freely link to any element within a `|group`. To summarize - the behavior of each individual standard ranged tag is fully governed by its implementation - see the [semantics document] for more details. *** Verbatim Ranged Tags In other cases you may be more interested in an isolated block /without/ Norg markup (i.e. a /verbatim/ block). A prime example of this is `@code`, which creates a code block - you obviously don't want nested Norg syntax within that! Note how in the following example the `@MyAnnotation` would clash with Norg's verbatim ranged tag syntax, but doesn't as no nested markup is allowed within: @code java @MyAnnotation(name="someName", value="Hello World") public class TheClass { // ... } @end This ranged tag type is the most commonly used one as it has the widest range of applications. The {*** standard ranged tags}[standard ranged tag] is a much more niche syntax element targeted at specific use cases. ** Carryover Tags Carryover tags are a construct used to assign certain properties to the next item or whole {# objects}[object]. /Note/: Internally, they are a type of {** macro tags}[macro tag], where the next element is given as the last parameter to the macro. For more info see {*** macro tags} and the [semantics document]. There are two types of carryover tag, the {*** weak carryover tags}[weak carryover tag] and the {*** strong carryover tags}[strong variant]. *** Weak Carryover Tags The weak carryover tag affects the next element and next element /only/. It does not work with whole collections of elements (see {*** strong carryover tags}). Weak carryover tags only apply to the next element; their behavior is as follows: - When the element has children, the weak carryover tag only applies to the single item (it does not carry over to its children). - When the element is part of an {# object}, no items other than the one below the weak carryover tag is affected. - An exception is made when a weak carryover tag is applied to an {# indent segment} or a {** ranged tags}[ranged tag], in which case everything within that segment/tag is affected. **** Examples Only the second item is affected: |example - List item 1 +color red - List item 2 (which is red) - List item 3 (which is normal-colored) |end Only the `Heading 1` and `This is some content` text is highlighted: |example +color red * Heading 1 (which is red) This is some content. (which is still red) ** Heading 2 (which is normal-colored) This is also some content. (which is normal-colored) |end Special behavior for indent segments: |example - List item 1 +color red - List item 2 (which is red) -- But this isn't red -- Neither is this +color green - :: This is green. -- This is also green -- And so is this. --- |end *** Strong Carryover Tags Contrary to its {*** weak carryover tags}[weak variant], the strong carryover tag exists to annotate an entire {# object} versus just a single item. Its behavior is opposite to its weak counterpart, namely: - When the element has children, the strong carryover tag applies to both the whole item and all of its children. - When the element is part of an {# object}, all items in the object are affected. **** Examples A nice use case is the `#choice` carryover tag, which converts all items in a list into a single-choice question with right/wrong answers: |example What is your favorite activity? Hint: there's only one correct answer :) #choice - ( ) Sleeping - ( ) Learning - (x) Writing `.norg` documents |end Here, both the level 1 heading and the level 2 heading along with their contents will be colored red: |example #color red * Heading 1 This is some content. ** Heading 2 This is also some content. |end *** Carryover Tags and Paragraphs A feature of {** carryover tags} which we have not discussed yet is how they interact with {** paragraphs} (and {** paragraph segments}). The following simple rules apply: - {*** strong carryover tags} affect the next {** paragraphs}[paragraph] - {*** weak carryover tags} affect the next {** paragraph segments}[paragraph segment] For example: |example #color blue This entire paragraph will now appear in blue color. This next paragraph is normal-colored. +color red But this single line is colored red, whereas this line is normal-colored again. #color blue This part is blue, +color red but the latter carryover tag takes precedence, making this part red, and this part blue again, since the weak carryover tag does not affect this segment. |end ** Infirm Tag The infirm tag is the simplest form of executing a macro. It is a single-line, embeddable macro invocation with the ability to supply parameters. It is denoted with the `.` character. Below is an example: |example =LoremIpsum Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. =end This is a paragraph, and below you will find the lorem ipsum text: .LoremIpsum This is still the same paragraph (assuming the macro invocation only inserted text; which it did in this specific example). |end * Attached Modifiers This section discusses attached modifiers (which originally gave rise to the name of {* detached modifiers} as their natural counter-parts). Attached modifiers encapsulate some text within a {** paragraphs}[paragraph] and change the way it is displayed in the document. An attached modifier consists of two parts: the /opening modifier/ and the /closing modifier/. Below are the general rules for attached modifiers: - An opening modifier may only be preceded by {# whitespace} or {# punctuation} - An opening modifier may _NOT_ be succeeded by {# whitespace} - A closing modifier may _NOT_ be preceded by {# whitespace} - A closing modifier may only be succeeded by {# whitespace} or {# punctuation} +name attached modifier range - :: {* Attached modifiers} can only span at maximum a single {# paragraphs}[paragraph], i.e. they get terminated as soon as they encounter a {$ paragraph break}. This means that this: |example *this text* |end will *not* result in any bold text, as it's divided by a {$ paragraph break}. However, this: |example *this text* |end is fine, and will result in *`this text`* being bold. - Nested {* attached modifiers} should be closed in the opposite order they were opened. - Two or more consecutive attached modifiers of the same type (i.e. `**`, `//` etc.) should be instantly "disqualified" and parsed as raw text in /all/ circumstances and without any exceptions. Their name should be rather self-explanatory - both the opening and closing modifier are /attached/ to one another. The following attached modifiers exist and have respective meaning: - \*bold\*: *bold* - \/italic\/: /italic/ - \_underline\_: _underline_ - \-strike-through\-: -strike-through- - \!spoiler\!: !spoiler! - \^superscript\^: ^superscript^ (cannot be nested into `subscript`) - \,subscript\,: ,subscript, (cannot be nested into `superscript`) - \`inline code\`: `inline code` (disables any nested markup - verbatim) - \%{** Null Modifier}[null modifier]\%: %null modifier% - \$inline math\$: $f(x) = y$ (verbatim) - \&variable\&: &variable& (verbatim) ** Valid Examples |example *Bold text* *Bold text*, .*Bold text*, *Bold text* */Bold and italic/* <- closing modifiers closed in the opposite order they were opened */Bold and italic/ and only bold* Text */with/ _different_ ^markup^ !types!* |end ** Invalid Examples |example * Bold text * *Bold text * other text*Bold text* *Bold text*other text * Bold text* *Bold text * *Bold text* Closed in the wrong order: */Bold and italic*/ Also closed in the wrong order: */Bold and italic* and only italic/ |end ** Null Modifier This section expands a bit on the concept of the `%null modifier%` in order to understand some of its use cases. When used in a standalone fashion, the null modifier nullifies (removes) all of the text inside. This means that on its own it behaves like a comment, which is never rendered: |example Cats %TODO: create section about cats% are very cute animals. |end In higher {* layers}, this modifier can have its behaviour extended with the {** attached modifier extensions}[attached modifier extension] syntax, which essentially makes it a configurable modifier suit for many occasions. For example, if you wanted to make an arbitrary part of your text red, you may do: |example This part of the text is %colored red%(color:red)! |end ** Variables Variables are a {** layer 5} attached modifier that allow a user to invoke a macro without any parameters and place the result inside e.g. a paragraph. For more information on their behavior see the [semantics document]. ** Free-form Attached Modifiers Even with all the rules described in the above sections there are still some evident limitations with attached modifiers, namely: - Arbitrary {*** whitespace} within {* attached modifiers} is not permitted: `* bold *` is invalid and thus not bold. - Representing verbatim attached modifier chars within the corresponding verbatim blocks is not possible: `I cannot place a () char inside here without accidentally terminating the block.|.

Free-form modifiers fix this with a special syntax to specify the beginning and end of a ranged block. For example:

    
           Here, I can write `| leading and trailing whitespace (with a ` char)  |` within a verbatim block
   without accidentally terminating it.

   Here, I can use a literal `$` inside inline math: $| 10$ + 10$ = 20$ |$.

    

Examples

    
            `print("This is some python")`(lang:python) <- The lang:python attribute highlights the text as python
    *some green and bold text!*(color:green)    <- some green and bold text

    {* Link location}[this is an important link](important|color:red) <- Highlights the link as big,
                                                                         bold (important) and red.

    

File Location

The file location is a construct that allows you to specify the target file into which you want to link to. This allows you to link to targets within other files or just link to other Norg files entirely.

When standalone, the link syntax will simply point to another .norg file relative to the current file the link is contained in:

    
            {:path/to/other-file:}

    

The Magic Char (#)

Sometimes you simply want to be lazy, or you want to link to an inline linkable that does not have a dedicated modifier to denote it - in these scenarios you would use the magic char: #. It links to any item type. The syntax is exactly the same as with the other modifiers: {# My Location}.

The File Linkable (/)

Sometimes you may want to link to an external file that is not a Norg file. In that case you may use {/ /path/to/my/file.txt} (notice the mandatory space after the / char, just like with the detached modifiers). Paths are relative to the Norg file that contains the link unless started with a / to denote your file system root.

In addition to just providing a path, you may also specify a line number at the end via a colon :. Example:

    
             {/ my-file.txt:123} <- This is a link to `my-file.txt` at line 123

    

Timestamps (@)

The syntax for timestamps within links is the same as the syntax used in the timestamp extension.

Example:

    
             Frank's birthday is on {@ 5th May}.

    

Wiki Links (?)

When building large knowledge bases it's sensible to want to quickly create links between files without worrying about the location of said file. The wiki link allows you to link to any heading in any file in the current workspace. You don't specify any file paths within the link, just the title of the heading you want to search for.

Syntax:

    
             Cats are {? mammals}, they make for great {? house pets} too!

    

Additional Behaviors With {:file:}

The wiki link can also be used with the {:file:} to limit the search. It can actually double as a "heading catchall" operator as mentioned in the previous section - it will match all headings regardless of nesting level in the file provided.

Extendable Links (=)

Apart from having links with set behaviors Norg also features an extendable link marked with the = character. This link has its behaviors governed by attached modifier extensions supplied to the link and by the software running the Norg format (e.g. Neorg).

Syntax:

    
             +bibliography ./myreferences.bib
     % my_bibliography

     This is a reference to a bibliography: {= Neorg2022}(my_bibliography).

    

Valid Examples

    
            {link}

    {* 
    text}

    {* text }

    {* some
    text   }

    {:link:}

    {:link:20}

    {# link
       text}

    {* a link
    to a heading}

    {* text}[content ]

    {* a
    link to a heading}[with
    a description]

    [te
    xt]{# linkable}

    {* Link to {# headings}[heading]}[*markup*]

    

Invalid Examples

    
            {*text}

    {:file:https://github.com}
    {:file:/ file.txt}
    {:file:@ Wednesday 30th Jan}

    {
    * text}

    {
        * text
    }

    {* text
    }

    { * text}

    {* text}[
        text
    ]

    {* text}[text
    ]

    {* text}[
    text]

    

Layer 1

The first layers contains a very low level implementation of Norg's markup for use in e.g. a messaging application. This includes:

• Attached Modifiers (excluding variables, inline mathematics and the null detached modifier)

• Links (only the URL type)

• The escape sequence char (\)

Layer 2

The second layer outlines the basic structure for a document:

• Nestable Detached Modifiers (only quotes, lists)

• Headings

• Linkables (broader support for links (minus timestamps (`@`), wiki links (`?`) and extendable links (`=`)), anchors)

• Verbatim Ranged Tags (@code, etc.)

• Delimiting Modifiers

Layer 3

This layer is for documents of medium/high complexity:

• Support for timestamps (`@`) and wiki links (`?`) in links

• Inline Link Targets

• Carryover Tags (#name, #color+name, +color etc.)

• Detached Modifier Extensions

• Detached Modifier Suffix

• Range-able Detached Modifiers (excluding table cells)

• Link Modifier

Layer 4

The fourth layer supports 80% of the most commonly used features for writing high level and typeset Norg documents.

• Support for extendable links (`=`) and scoping

• Standard Ranged Tags (|comment, etc.)

• Table cells

• Free-form Attached Modifiers

• Intersecting modifiers

• Attached Modifier Extensions

• The inline mathematics ($$) and variable (&&) attached modifiers

Layer 5

Layer five can be seen as the ultimate boss - it features the dynamic elements of Norg documents, including macros, variables and parsing of eval blocks.

• Interpretation/Execution of macro tags

• Semantic understanding/execution of all other tag types

• Evaluation of @code blocks for the NIP language (if they are marked with #eval).