From b21efee0e87354b8daf2b5848e1cb31e2410895b Mon Sep 17 00:00:00 2001 From: "Documenter.jl" Date: Tue, 19 Sep 2023 06:07:48 +0000 Subject: [PATCH] build based on 5f03e26 --- dev/1.0-specification/index.html | 2 +- dev/index.html | 12 ++++++------ dev/internals/ast/index.html | 2 +- dev/internals/codegen/html/index.html | 2 +- dev/internals/codegen/index.html | 4 ++-- dev/internals/codegen/json/index.html | 2 +- dev/internals/index.html | 2 +- dev/internals/kinds/index.html | 4 ++-- dev/internals/match/index.html | 2 +- dev/internals/parser/index.html | 2 +- dev/internals/scanners/index.html | 2 +- dev/internals/tokens/index.html | 2 +- dev/search/index.html | 2 +- dev/search_index.js | 2 +- 14 files changed, 21 insertions(+), 21 deletions(-) diff --git a/dev/1.0-specification/index.html b/dev/1.0-specification/index.html index 676d734..653fdb8 100644 --- a/dev/1.0-specification/index.html +++ b/dev/1.0-specification/index.html @@ -1579,4 +1579,4 @@

Layer 5

- + diff --git a/dev/index.html b/dev/index.html index 8913d33..c089e4f 100644 --- a/dev/index.html +++ b/dev/index.html @@ -10,9 +10,9 @@ open("1.0-specification.json", "w") do f JSON.print(f, norg(JSONTarget(), s), 2) end;

You can then invoke Pandoc as follow:

pandoc -f json -t markdown 1.0-specification.json -o 1.0-specification.md

Advanced usage

You can also generate an Abstract Syntax Tree (AST) that implements AbstractTrees.jl interface using norg. See also the AST module.

norg(s)

Public API

Norg.Norg — Module

Norg.jl provides a way to parse Neorg files in pure Julia.

It overloads Base.parse with custom targets. So far the only available target is HTMLTarget.

Example usage :

using Norg
-norg(HTMLTarget(), "Read {https://github.com/nvim-neorg/norg-specs}[the spec !]")
source
Norg.NORG_SEMANTICS_PATH — Constant

Path to the Norg semantics specification.

source
Norg.NORG_SPEC_PATH — Constant

Path to the Norg specification.

source
Norg.NORG_SPEC_ROOT — Constant

The root directory of the Norg specification.

source
Norg.NORG_STDLIB_PATH — Constant

Path to the Norg standard library.

source
Norg.consume_until — Method
consume_until(k, tokens, i)
-consume_until((k₁, k₂...), tokens, i)

Consume tokens until a token of kind k is encountered, or final token is reached.

source
Norg.findtargets! — Method
findtargets!(ast[, node])

Iterate over the tree to (re)build the targets attribute of the AST, listing all possible targets for magic links among direct children of node.

If node is not given, iterate over the whole AST, and empty! the targets attribute of the AST first.

source
Norg.getchildren — Method
getchildren(node, k)
-getchildren(node, k[, exclude])

Return all children and grandchildren of kind k. It can also exclude certain nodes from recursion.

source
Norg.idify — Method
idify(text)

Make some text suitable for using it as an id in a document.

source
Norg.norg — Method
norg([codegentarget, ] s)

Parse the input s to an AST. If codegentarget is included, return the result of code generation for the given target.

Examples

julia> norg("* Hello world!")
+norg(HTMLTarget(), "Read {https://github.com/nvim-neorg/norg-specs}[the spec !]")
source
Norg.NORG_SEMANTICS_PATH — Constant

Path to the Norg semantics specification.

source
Norg.NORG_SPEC_PATH — Constant

Path to the Norg specification.

source
Norg.NORG_SPEC_ROOT — Constant

The root directory of the Norg specification.

source
Norg.NORG_STDLIB_PATH — Constant

Path to the Norg standard library.

source
Norg.consume_until — Method
consume_until(k, tokens, i)
+consume_until((k₁, k₂...), tokens, i)

Consume tokens until a token of kind k is encountered, or final token is reached.

source
Norg.findtargets! — Method
findtargets!(ast[, node])

Iterate over the tree to (re)build the targets attribute of the AST, listing all possible targets for magic links among direct children of node.

If node is not given, iterate over the whole AST, and empty! the targets attribute of the AST first.

source
Norg.getchildren — Method
getchildren(node, k)
+getchildren(node, k[, exclude])

Return all children and grandchildren of kind k. It can also exclude certain nodes from recursion.

source
Norg.idify — Method
idify(text)

Make some text suitable for using it as an id in a document.

source
Norg.norg — Method
norg([codegentarget, ] s)

Parse the input s to an AST. If codegentarget is included, return the result of code generation for the given target.

Examples

julia> norg("* Hello world!")
 NorgDocument
 └─ (K"Heading1", 2, 8)
    └─ (K"ParagraphSegment", 4, 7)
@@ -21,10 +21,10 @@
       ├─ world
       └─ !
 julia> norg(HTMLTarget(), "* Hello world!")
-<div class="norg"><section id="section-h1-hello-world"><h1 id="h1-hello-world">Hello world&#33;</h1></section><section class="footnotes"><ol></ol></section></div>
source
Norg.parse_norg_timestamp — Method
parse_norg_timestamp(tokens, start, stop)

Parse a Norg timestamp to Julia DateTime. A timestamp has the following structure:

<day>,? <day-of-month> <month> <year> <time> <timezone>

Refer to the Norg specification for further explanations.

Example usage:

using Norg, AbstractTrees
+<div class="norg"><section id="section-h1-hello-world"><h1 id="h1-hello-world">Hello world&#33;</h1></section><section class="footnotes"><ol></ol></section></div>
source
Norg.parse_norg_timestamp — Method
parse_norg_timestamp(tokens, start, stop)

Parse a Norg timestamp to Julia DateTime. A timestamp has the following structure:

<day>,? <day-of-month> <month> <year> <time> <timezone>

Refer to the Norg specification for further explanations.

Example usage:

using Norg, AbstractTrees
 ast = norg"{@ Wed, 12th Jan - 20th Feb 2022}"
 node = first(collect(Leaves(ast)))
-Norg.parse_norg_timestamp(ast.tokens, node.start, node.stop)
source
Norg.textify — Method
textify(ast, node)

Return the raw text associated with a node.

source
Norg.@norg_str — Macro

Easily parse Norg string to an AST. This can be used in e.g. Pluto notebooks, because Base.show has a method for "text/html" type mime for ASTs.

Examples

julia> norg"* Norg Header 1 Example"
+Norg.parse_norg_timestamp(ast.tokens, node.start, node.stop)
source
Norg.textify — Function
textify(ast, node, escape=identity)

Return the raw text associated with a node. You can specify an escape function.

source
Norg.@norg_str — Macro

Easily parse Norg string to an AST. This can be used in e.g. Pluto notebooks, because Base.show has a method for "text/html" type mime for ASTs.

Examples

julia> norg"* Norg Header 1 Example"
 NorgDocument
 └─ (K"Heading1", 2, 11)
    └─ (K"ParagraphSegment", 4, 10)
@@ -34,4 +34,4 @@
       ├─
       ├─ 1
       ├─
-      └─ Example
source

Inner API

The inner API is documented in the Norg internals page.

+ └─ Examplesource

Inner API

The inner API is documented in the Norg internals page.

diff --git a/dev/internals/ast/index.html b/dev/internals/ast/index.html index 18ef55f..7dffa04 100644 --- a/dev/internals/ast/index.html +++ b/dev/internals/ast/index.html @@ -1,2 +1,2 @@ -AST · Norg.jl
Edit on GitHub
+AST · Norg.jl
Edit on GitHub
diff --git a/dev/internals/codegen/html/index.html b/dev/internals/codegen/html/index.html index 505a835..d19104a 100644 --- a/dev/internals/codegen/html/index.html +++ b/dev/internals/codegen/html/index.html @@ -1,2 +1,2 @@ -HTMLCodegen · Norg.jl
Edit on GitHub

HTMLCodegen

Norg.Codegen.HTMLCodegen.FootnotesLevel — Type

Controls the position where footnotes are rendered. It can be within the lowest heading level i by setting HiFootnotes or at the root of the document or directly as it appears in the Norg document.

source
+HTMLCodegen · Norg.jl
Edit on GitHub

HTMLCodegen

Norg.Codegen.HTMLCodegen.FootnotesLevel — Type

Controls the position where footnotes are rendered. It can be within the lowest heading level i by setting HiFootnotes or at the root of the document or directly as it appears in the Norg document.

source
diff --git a/dev/internals/codegen/index.html b/dev/internals/codegen/index.html index 22af6b7..dbcfceb 100644 --- a/dev/internals/codegen/index.html +++ b/dev/internals/codegen/index.html @@ -1,3 +1,3 @@ -Codegen · Norg.jl
Edit on GitHub
+Codegen · Norg.jl
Edit on GitHub
diff --git a/dev/internals/codegen/json/index.html b/dev/internals/codegen/json/index.html index d4b1fec..46adba2 100644 --- a/dev/internals/codegen/json/index.html +++ b/dev/internals/codegen/json/index.html @@ -1,2 +1,2 @@ -JSONCodegen · Norg.jl
Edit on GitHub
+JSONCodegen · Norg.jl
Edit on GitHub

JSONCodegen

diff --git a/dev/internals/index.html b/dev/internals/index.html index 56bff6a..71a067b 100644 --- a/dev/internals/index.html +++ b/dev/internals/index.html @@ -1,2 +1,2 @@ -How parsing works · Norg.jl
Edit on GitHub

Norg internals

This page describes the internals of Norg.jl and how it parses .norg files.

There are three main steps for turning Norg files into HTML (since it's the only supported target for now).

  1. Tokenizing (identifying the different chunks of code)
  2. Parsing (create an Abstract Syntax Tree, AST)
  3. Code generation (turning the AST into HTML)

Notes on using Julia's dispatch system

Earlier Norg.jl would rely on Julia's type system, but that made the code type-unstable. That's why I refactored it using a kind of enumeration to label each token and node of the AST. I did not invent anything here, it comes straight from JuliaSyntax.jl super cool ideas. See Norg.Kinds.

That does not mean that the native type system is not used. Rather, there are some dispatch functions that are basically big if statements that dispatch a given Norg.Kinds.Kind towards what's called a strategy in Norg.jl. Then the native dispatch system can take the hand and dispatch towards the right method. This allows making the code type-stable for the compiler and improves greatly performances.

Tokenization

The first step for parsing Norg documents is transforming the input string into a more friendly array of token. A Norg.Tokens.Token labels a chunk of text according to the significance the parser could give it. For example there are token kinds for line endings, words, whitespaces, the * character... Note that a token can span several characters. This is the case for words, but also for whitespaces.

Parsing

The second step consist in turning the array of tokens into an Abstract Syntax Tree (AST). To do so, Norg.jl relies on two functions: Norg.Match.match_norg and Norg.Parser.parse_norg. The role of the former is to match a sequence of tokens to a parsing strategy, while the latter does the actual parsing. For example, while parsing a paragraph, if Norg.Match.match_norg encounters two tokens of kind LineEnding, then it returns a closing match of kind Paragraph. It is then up to parse_norg to properly close the current paragraph.

Code generation

The third and last step consist in generating code output from the AST. Norg.jl defines several code generation targets in the Norg.Codegen module. Code generation is fairly simple, as it simply walks the AST and turn each node into the correct output node. For example, a level one heading would be turned into an HTML <h1> node when generating code for the HTMLTarget target.

+How parsing works · Norg.jl
Edit on GitHub

Norg internals

This page describes the internals of Norg.jl and how it parses .norg files.

There are three main steps for turning Norg files into HTML (since it's the only supported target for now).

  1. Tokenizing (identifying the different chunks of code)
  2. Parsing (create an Abstract Syntax Tree, AST)
  3. Code generation (turning the AST into HTML)

Notes on using Julia's dispatch system

Earlier Norg.jl would rely on Julia's type system, but that made the code type-unstable. That's why I refactored it using a kind of enumeration to label each token and node of the AST. I did not invent anything here, it comes straight from JuliaSyntax.jl super cool ideas. See Norg.Kinds.

That does not mean that the native type system is not used. Rather, there are some dispatch functions that are basically big if statements that dispatch a given Norg.Kinds.Kind towards what's called a strategy in Norg.jl. Then the native dispatch system can take the hand and dispatch towards the right method. This allows making the code type-stable for the compiler and improves greatly performances.

Tokenization

The first step for parsing Norg documents is transforming the input string into a more friendly array of token. A Norg.Tokens.Token labels a chunk of text according to the significance the parser could give it. For example there are token kinds for line endings, words, whitespaces, the * character... Note that a token can span several characters. This is the case for words, but also for whitespaces.

Parsing

The second step consist in turning the array of tokens into an Abstract Syntax Tree (AST). To do so, Norg.jl relies on two functions: Norg.Match.match_norg and Norg.Parser.parse_norg. The role of the former is to match a sequence of tokens to a parsing strategy, while the latter does the actual parsing. For example, while parsing a paragraph, if Norg.Match.match_norg encounters two tokens of kind LineEnding, then it returns a closing match of kind Paragraph. It is then up to parse_norg to properly close the current paragraph.

Code generation

The third and last step consist in generating code output from the AST. Norg.jl defines several code generation targets in the Norg.Codegen module. Code generation is fairly simple, as it simply walks the AST and turn each node into the correct output node. For example, a level one heading would be turned into an HTML <h1> node when generating code for the HTMLTarget target.

diff --git a/dev/internals/kinds/index.html b/dev/internals/kinds/index.html index a832130..e6b6bf1 100644 --- a/dev/internals/kinds/index.html +++ b/dev/internals/kinds/index.html @@ -1,3 +1,3 @@ -Kinds · Norg.jl
Edit on GitHub

Kinds

Norg.Kinds — Module

To provide a type-stable parser, we handle types ourselves. This is directly inspired by JuliaSyntax.jl. See here

You can see kinds as an advanced Enum type that allows some kind of grouping of values. We use Kinds.Kind to classify the different types of tokens ast nodes.

source
Norg.Kinds.Kind — Type
Kind(name)
-K"name"

This is type tag, used to specify the type of tokens and AST nodes.

source
Norg.Kinds.@K_str — Macro
K"s"

The kind of a token or AST internal node with string "s". For example

  • K">" is the kind of the greater than sign token
source
+Kinds · Norg.jl
Edit on GitHub

Kinds

Norg.Kinds — Module

To provide a type-stable parser, we handle types ourselves. This is directly inspired by JuliaSyntax.jl. See here

You can see kinds as an advanced Enum type that allows some kind of grouping of values. We use Kinds.Kind to classify the different types of tokens ast nodes.

source
Norg.Kinds.Kind — Type
Kind(name)
+K"name"

This is type tag, used to specify the type of tokens and AST nodes.

source
Norg.Kinds.@K_str — Macro
K"s"

The kind of a token or AST internal node with string "s". For example

  • K">" is the kind of the greater than sign token
source
diff --git a/dev/internals/match/index.html b/dev/internals/match/index.html index 7bad677..509f6e4 100644 --- a/dev/internals/match/index.html +++ b/dev/internals/match/index.html @@ -1,2 +1,2 @@ -Match · Norg.jl
Edit on GitHub

Match

Norg.Match.MatchResult — Type

Holds results of Match.match_norg. It has a Kinds.kind, that can be found, can be closing (i.e. closing an attached modifier), continued (as in "ignore this token and continue parsing"). Whether the parser should consume or not the current token is given by the consume field.

source
+Match · Norg.jl
Edit on GitHub

Match

Norg.Match.MatchResult — Type

Holds results of Match.match_norg. It has a Kinds.kind, that can be found, can be closing (i.e. closing an attached modifier), continued (as in "ignore this token and continue parsing"). Whether the parser should consume or not the current token is given by the consume field.

source
diff --git a/dev/internals/parser/index.html b/dev/internals/parser/index.html index 0b97d2a..5b3347e 100644 --- a/dev/internals/parser/index.html +++ b/dev/internals/parser/index.html @@ -1,2 +1,2 @@ -Parser · Norg.jl
Edit on GitHub

Parser

Norg.Parser.parse_norg — Function
parse_norg(strategy, tokens, i)

Try to parse the tokens sequence starting at index i using a given strategy.

source
+Parser · Norg.jl
Edit on GitHub

Parser

Norg.Parser.parse_norg — Function
parse_norg(strategy, tokens, i)

Try to parse the tokens sequence starting at index i using a given strategy.

source
diff --git a/dev/internals/scanners/index.html b/dev/internals/scanners/index.html index 31f8c10..73c2515 100644 --- a/dev/internals/scanners/index.html +++ b/dev/internals/scanners/index.html @@ -1,2 +1,2 @@ -Scanners · Norg.jl
Edit on GitHub

Scanners

Norg.Scanners — Module

Provides the scanners for the tokenizer.

The role of a scanner is to recognize a sequence of characters and to produce a ScanResult.

source
Norg.Scanners.scan — Function
scan(pattern, input)

Scan the given input for the given pattern.

It will produce a Scanners.ScanResult.

If pattern is given, then try to fit the given patter at the start of input. If pattern is :

  • a ScanStrategy subtype : scan with the given strategy (e.g. Word or Whitespace)
  • a Kind : parse for the given kind.
  • an AbstractString : input must startswith pattern.
  • an AbstractArray : call scan on each element of pattern until one matches.
  • a Set{Char} : first character must be included in pattern.
source
+Scanners · Norg.jl
Edit on GitHub

Scanners

Norg.Scanners — Module

Provides the scanners for the tokenizer.

The role of a scanner is to recognize a sequence of characters and to produce a ScanResult.

source
Norg.Scanners.scan — Function
scan(pattern, input)

Scan the given input for the given pattern.

It will produce a Scanners.ScanResult.

If pattern is given, then try to fit the given patter at the start of input. If pattern is :

  • a ScanStrategy subtype : scan with the given strategy (e.g. Word or Whitespace)
  • a Kind : parse for the given kind.
  • an AbstractString : input must startswith pattern.
  • an AbstractArray : call scan on each element of pattern until one matches.
  • a Set{Char} : first character must be included in pattern.
source
diff --git a/dev/internals/tokens/index.html b/dev/internals/tokens/index.html index ea46b6c..1b3fd3c 100644 --- a/dev/internals/tokens/index.html +++ b/dev/internals/tokens/index.html @@ -1,2 +1,2 @@ -Tokens · Norg.jl
Edit on GitHub

Tokens

Tokens

Norg.Tokens.Token — Method
 Token(kind, line, char, value)

Create a Token of kind kind with value value at line and char number char.

source
Norg.Tokens.char — Method
char(x)

Return the character number in the line corresponding to position or token x.

source

Tokenize

+Tokens · Norg.jl
Edit on GitHub

Tokens

Tokens

Norg.Tokens.Token — Method
 Token(kind, line, char, value)

Create a Token of kind kind with value value at line and char number char.

source
Norg.Tokens.char — Method
char(x)

Return the character number in the line corresponding to position or token x.

source

Tokenize

diff --git a/dev/search/index.html b/dev/search/index.html index 258f7b1..830e840 100644 --- a/dev/search/index.html +++ b/dev/search/index.html @@ -1,2 +1,2 @@ -Search · Norg.jl

Loading search...

    +Search · Norg.jl

    Loading search...

      diff --git a/dev/search_index.js b/dev/search_index.js index a012fa8..824d519 100644 --- a/dev/search_index.js +++ b/dev/search_index.js @@ -1,3 +1,3 @@ var documenterSearchIndex = {"docs": -[{"location":"internals/parser/#Parser","page":"Parser","title":"Parser","text":"","category":"section"},{"location":"internals/parser/","page":"Parser","title":"Parser","text":"Modules = [Norg.Parser]","category":"page"},{"location":"internals/parser/","page":"Parser","title":"Parser","text":"Modules = [Norg.Parser]","category":"page"},{"location":"internals/parser/#Norg.Parser","page":"Parser","title":"Norg.Parser","text":"This module defines the Parser.parse_norg function, which builds an AST from a token list.\n\nThe role of Parser.parse_norg is to consume tokens. To do so, it relies on Match.match_norg to take decisions on how to consume tokens.\n\n\n\n\n\n","category":"module"},{"location":"internals/parser/#Norg.Parser.parse_norg","page":"Parser","title":"Norg.Parser.parse_norg","text":"parse_norg(strategy, tokens, i)\n\nTry to parse the tokens sequence starting at index i using a given strategy.\n\n\n\n\n\n","category":"function"},{"location":"internals/parser/#Norg.Parser.parse_norg-Tuple{Vector{Norg.Tokens.Token}}","page":"Parser","title":"Norg.Parser.parse_norg","text":"parse_norg(tokens)\n\nTry to parse the tokens sequence as an AST.NorgDocument starting from the begining of the sequence.\n\n\n\n\n\n","category":"method"},{"location":"internals/parser/#Norg.Parser.parse_norg_dispatch-Tuple{Norg.Kinds.Kind, Vector{Norg.Kinds.Kind}, Vector{Norg.Tokens.Token}, Any}","page":"Parser","title":"Norg.Parser.parse_norg_dispatch","text":"Main dispatch utility.\n\n\n\n\n\n","category":"method"},{"location":"internals/match/#Match","page":"Match","title":"Match","text":"","category":"section"},{"location":"internals/match/","page":"Match","title":"Match","text":"Modules = [Norg.Match]","category":"page"},{"location":"internals/match/","page":"Match","title":"Match","text":"Modules = [Norg.Match]","category":"page"},{"location":"internals/match/#Norg.Match","page":"Match","title":"Norg.Match","text":"This module exports Match.match_norg which matches token sequences to Kinds.Kind AST nodes.\n\n\n\n\n\n","category":"module"},{"location":"internals/match/#Norg.Match.MatchResult","page":"Match","title":"Norg.Match.MatchResult","text":"Holds results of Match.match_norg. It has a Kinds.kind, that can be found, can be closing (i.e. closing an attached modifier), continued (as in \"ignore this token and continue parsing\"). Whether the parser should consume or not the current token is given by the consume field.\n\n\n\n\n\n","category":"type"},{"location":"internals/match/#Norg.Match.match_norg","page":"Match","title":"Norg.Match.match_norg","text":"match_norg([strategy], parents, tokens, i)\n\nFind the appropriate Kinds.Kind for a token when parser is inside a parents block parsing the tokens list at index i.\n\nReturn a Match.MatchResult.\n\n\n\n\n\n","category":"function"},{"location":"internals/codegen/html/#HTMLCodegen","page":"HTMLCodegen","title":"HTMLCodegen","text":"","category":"section"},{"location":"internals/codegen/html/","page":"HTMLCodegen","title":"HTMLCodegen","text":"Modules = [Norg.Codegen.HTMLCodegen]","category":"page"},{"location":"internals/codegen/html/#Norg.Codegen.HTMLCodegen","page":"HTMLCodegen","title":"Norg.Codegen.HTMLCodegen","text":"HTML code generation using HypertextLiteral.jl.\n\n\n\n\n\n","category":"module"},{"location":"internals/codegen/html/#Norg.Codegen.HTMLCodegen.FootnotesLevel","page":"HTMLCodegen","title":"Norg.Codegen.HTMLCodegen.FootnotesLevel","text":"Controls the position where footnotes are rendered. It can be within the lowest heading level i by setting HiFootnotes or at the root of the document or directly as it appears in the Norg document.\n\n\n\n\n\n","category":"type"},{"location":"internals/codegen/html/#Norg.Codegen.HTMLCodegen.HTMLLocationTarget","page":"HTMLCodegen","title":"Norg.Codegen.HTMLCodegen.HTMLLocationTarget","text":"A special target for link location, this ensure type-stability.\n\n\n\n\n\n","category":"type"},{"location":"internals/codegen/html/#Norg.Codegen.HTMLCodegen.HTMLTarget","page":"HTMLCodegen","title":"Norg.Codegen.HTMLCodegen.HTMLTarget","text":"HTML target to feed codegen.\n\n\n\n\n\n","category":"type"},{"location":"internals/scanners/#Scanners","page":"Scanners","title":"Scanners","text":"","category":"section"},{"location":"internals/scanners/","page":"Scanners","title":"Scanners","text":"Modules = [Norg.Scanners]","category":"page"},{"location":"internals/scanners/","page":"Scanners","title":"Scanners","text":"Modules = [Norg.Scanners]","category":"page"},{"location":"internals/scanners/#Norg.Scanners","page":"Scanners","title":"Norg.Scanners","text":"Provides the scanners for the tokenizer.\n\nThe role of a scanner is to recognize a sequence of characters and to produce a ScanResult.\n\n\n\n\n\n","category":"module"},{"location":"internals/scanners/#Norg.Scanners.NORG_LINE_ENDING","page":"Scanners","title":"Norg.Scanners.NORG_LINE_ENDING","text":"All the UTF-8 characters that Norg specifies as a whitespace.\n\n\n\n\n\n","category":"constant"},{"location":"internals/scanners/#Norg.Scanners.NORG_PUNCTUATION","page":"Scanners","title":"Norg.Scanners.NORG_PUNCTUATION","text":"All the UTF-8 characters that are punctuation in Norg specification. See the norg specification\n\n\n\n\n\n","category":"constant"},{"location":"internals/scanners/#Norg.Scanners.TOKENKIND_PARSING_ORDER","page":"Scanners","title":"Norg.Scanners.TOKENKIND_PARSING_ORDER","text":"All the registered Kinds.Kind that Scanners.scan will try when consuming entries.\n\n\n\n\n\n","category":"constant"},{"location":"internals/scanners/#Norg.Scanners.ScanResult","page":"Scanners","title":"Norg.Scanners.ScanResult","text":"Stores the result of a scanning operation. If length is 0 that means that no matching token was found.\n\n\n\n\n\n","category":"type"},{"location":"internals/scanners/#Norg.Scanners.scan","page":"Scanners","title":"Norg.Scanners.scan","text":"scan(pattern, input)\n\nScan the given input for the given pattern.\n\nIt will produce a Scanners.ScanResult.\n\nIf pattern is given, then try to fit the given patter at the start of input. If pattern is :\n\na ScanStrategy subtype : scan with the given strategy (e.g. Word or Whitespace) \na Kind : parse for the given kind.\nan AbstractString : input must startswith pattern.\nan AbstractArray : call scan on each element of pattern until one matches.\na Set{Char} : first character must be included in pattern.\n\n\n\n\n\n","category":"function"},{"location":"internals/scanners/#Norg.Scanners.scan-Tuple{Any}","page":"Scanners","title":"Norg.Scanners.scan","text":"scan(input; line=0, charnum=0)\n\nScan the given input for Scanners.TOKENKIND_PARSING_ORDER until one returns a successful Scanners.ScanResult or throw an error if none succeed.\n\nThis will return a Tokens.Token.\n\n\n\n\n\n","category":"method"},{"location":"internals/codegen/json/#JSONCodegen","page":"JSONCodegen","title":"JSONCodegen","text":"","category":"section"},{"location":"internals/codegen/json/","page":"JSONCodegen","title":"JSONCodegen","text":"Modules = [Norg.Codegen.JSONCodegen]","category":"page"},{"location":"internals/codegen/json/#Norg.Codegen.JSONCodegen","page":"JSONCodegen","title":"Norg.Codegen.JSONCodegen","text":"Pandoc AST code generation. The best reference of Pandoc's AST I could find is here\n\nThe code generated consists in OrderedDicts from OrderedCollections.jl that follow the Pandoc JSON AST API. You can then export using e.g. JSON.jl.\n\n\n\n\n\n","category":"module"},{"location":"internals/codegen/json/#Norg.Codegen.JSONCodegen.JSONTarget","page":"JSONCodegen","title":"Norg.Codegen.JSONCodegen.JSONTarget","text":"JSON target to feed codegen.\n\n\n\n\n\n","category":"type"},{"location":"internals/ast/#AST","page":"AST","title":"AST","text":"","category":"section"},{"location":"internals/ast/","page":"AST","title":"AST","text":"Modules = [Norg.AST]","category":"page"},{"location":"internals/ast/","page":"AST","title":"AST","text":"Modules = [Norg.AST]","category":"page"},{"location":"internals/ast/#Norg.AST","page":"AST","title":"Norg.AST","text":"This module defines the Abstract Syntax Trees (AST) associated with the norg format.\n\n\n\n\n\n","category":"module"},{"location":"internals/ast/#Norg.AST.Node","page":"AST","title":"Norg.AST.Node","text":"An AST Node has a kind (e.g. Bold), can have children Nodes, and refer to tokens in the token array.\n\n\n\n\n\n","category":"type"},{"location":"internals/ast/#Norg.AST.NorgDocument","page":"AST","title":"Norg.AST.NorgDocument","text":"Stores the Abstract Syntax Tree (AST) for a Norg document. It implements the AbstractTrees.jl interface.\n\n\n\n\n\n","category":"type"},{"location":"internals/#Norg-internals","page":"How parsing works","title":"Norg internals","text":"","category":"section"},{"location":"internals/","page":"How parsing works","title":"How parsing works","text":"This page describes the internals of Norg.jl and how it parses .norg files.","category":"page"},{"location":"internals/","page":"How parsing works","title":"How parsing works","text":"There are three main steps for turning Norg files into HTML (since it's the only supported target for now).","category":"page"},{"location":"internals/","page":"How parsing works","title":"How parsing works","text":"Tokenizing (identifying the different chunks of code)\nParsing (create an Abstract Syntax Tree, AST)\nCode generation (turning the AST into HTML)","category":"page"},{"location":"internals/","page":"How parsing works","title":"How parsing works","text":"Pages=[\"internals.md\"]","category":"page"},{"location":"internals/#Notes-on-using-Julia's-dispatch-system","page":"How parsing works","title":"Notes on using Julia's dispatch system","text":"","category":"section"},{"location":"internals/","page":"How parsing works","title":"How parsing works","text":"Earlier Norg.jl would rely on Julia's type system, but that made the code type-unstable. That's why I refactored it using a kind of enumeration to label each token and node of the AST. I did not invent anything here, it comes straight from JuliaSyntax.jl super cool ideas. See Norg.Kinds.","category":"page"},{"location":"internals/","page":"How parsing works","title":"How parsing works","text":"That does not mean that the native type system is not used. Rather, there are some dispatch functions that are basically big if statements that dispatch a given Norg.Kinds.Kind towards what's called a strategy in Norg.jl. Then the native dispatch system can take the hand and dispatch towards the right method. This allows making the code type-stable for the compiler and improves greatly performances.","category":"page"},{"location":"internals/#Tokenization","page":"How parsing works","title":"Tokenization","text":"","category":"section"},{"location":"internals/","page":"How parsing works","title":"How parsing works","text":"The first step for parsing Norg documents is transforming the input string into a more friendly array of token. A Norg.Tokens.Token labels a chunk of text according to the significance the parser could give it. For example there are token kinds for line endings, words, whitespaces, the * character... Note that a token can span several characters. This is the case for words, but also for whitespaces.","category":"page"},{"location":"internals/#Parsing","page":"How parsing works","title":"Parsing","text":"","category":"section"},{"location":"internals/","page":"How parsing works","title":"How parsing works","text":"The second step consist in turning the array of tokens into an Abstract Syntax Tree (AST). To do so, Norg.jl relies on two functions: Norg.Match.match_norg and Norg.Parser.parse_norg. The role of the former is to match a sequence of tokens to a parsing strategy, while the latter does the actual parsing. For example, while parsing a paragraph, if Norg.Match.match_norg encounters two tokens of kind LineEnding, then it returns a closing match of kind Paragraph. It is then up to parse_norg to properly close the current paragraph.","category":"page"},{"location":"internals/#Code-generation","page":"How parsing works","title":"Code generation","text":"","category":"section"},{"location":"internals/","page":"How parsing works","title":"How parsing works","text":"The third and last step consist in generating code output from the AST. Norg.jl defines several code generation targets in the Norg.Codegen module. Code generation is fairly simple, as it simply walks the AST and turn each node into the correct output node. For example, a level one heading would be turned into an HTML

      node when generating code for the HTMLTarget target.","category":"page"},{"location":"1.0-specification/","page":"Specification","title":"Specification","text":"This is an automated rendering of the norg specification using Norg.jl.","category":"page"},{"location":"1.0-specification/#Table-of-contents","page":"Specification","title":"Table of contents","text":"","category":"section"},{"location":"1.0-specification/","page":"Specification","title":"Specification","text":"\n
      \n
      \n

      Norg File Format Specification

      \n

      This file contains the formal file format specification of the Norg syntax version 1.0. This document is written in the Norg format in its original form and, thus, attempts to be self-documenting.

      Please note that this is not a reference implementation - this is an established rule set that should be strictly followed.

      \n
      \n
      \n

      Introduction

      \n

      Before diving into the details we will start with an introduction. The Norg file format was designed as part of the Neorg plugin for Neovim which was started by Vhyrro (@vhyrro) in April 2021. Soon after starting this work, Max Rossmannek (@mrossinek) joined the development team, and, with the help of the Neorg community, the two have shaped the Norg syntax to what it has become today.

      \n

      What is Norg?

      \n

      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.

      \n
      \n\n
      \n
      \n

      Preliminaries

      \n

      First, we define some basic concepts which will be used in this specification.

      \n

      Characters

      \n

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

      \n

      Whitespace

      \n

      A character is considered whitespace if it is any of the following:

      Any combination of the above is also considered whitespace.

      Tabs are not expanded to spaces and since whitespace has no semantic meaning there is no need to define a default tab stop. However, if a parser must (for implementation reasons) define a tab stop, we suggest setting it to 4 spaces.

      \n
      \n
      \n

      Line Endings

      \n

      Line endings in Norg serve as a termination character. They are used e.g. to terminate paragraph segments, paragraphs and other elements like the endings of range-able\n detached modifiers. They are not considered whitespace.

      The following chars are considered line endings:

      • A line feed U+000A

      • A form feed U+000C

      • A carriage return U+000D

      The following line ending combinations are permitted:

      • A single line feed

      • A single carriage return

      • A carriage return immediately followed by a line feed

      \n
      \n
      \n

      Punctuation

      \n

      A character is considered punctuation if it is any of the following:

      • A standard ASCII punctuation character: !"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~

      • Anything in the general Unicode categories Pc, Pd, Pe, Pf, Pi, Po or Ps.

      \n
      \n
      \n

      Escaping

      \n

      A single character can be escaped if it is immediately preceded by a backslash, \\ (U+005C). Any character may be escaped apart from characters within free-form and ranged verbatim segments (see free-form attached modifiers and verbatim ranged tags). For more information about precedence, take a look at the precedence section.

      \n
      \n
      \n

      Regular Characters

      \n

      Any other character not described by the preceding sections is treated as a generic code point/character.

      \n
      \n\n
      \n
      \n

      Words

      \n

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

      \n
      \n
      \n

      Paragraph Segments

      \n

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

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

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

      The exception to the rule is whenever a linkable or attached modifier within the paragraph segment spans more than a single line, in which case the paragraph segment also spans that distance. For example:

      \n    \n           I *am\n   a long paragraph segment!*\n\n    \n
      \n\n
      \n
      \n

      Paragraphs

      \n

      Paragraphs are then formed of consecutive paragraph segments. A paragraph is terminated by:

      Paragaph Break

      A paragraph break is defined as an empty line. In the simplest case that means two consecutive line endings but since Neorg is a free-form markup language, a line which only contains whitespace is also considered empty.

      \n
      \n
      \n

      Detached Modifiers

      \n

      Norg has several detached modifiers. The name originates from their differentiation to the attached modifiers, which will be discussed later.

      All detached modifiers must abide by the following rules:

      • A detached modifier can only occur at the beginning of the line (arbitrary whitespace (but nothing else!) may precede it)

      • A detached modifier must be immediately followed by whitespace or another detached modifier of the same type

      The following table outlines all valid detached modifiers. It also adds various possible properties to each category which will be explained in more detail below. : . : Character : > : Name : > : Categories : _ : * : > : Headings :: >

      • Structural

      • Nestable :: : _ : - : > : Unordered Lists :: >

      • Nestable :: : _ : ~ : > : Ordered Lists :: >

      • Nestable :: : _ : > : > : Quotes :: >

      • Nestable :: : _ : $ : > : Definitions :: >

      • Range-able :: : _ : ^ : > : Footnotes :: >

      • Range-able :: : _ : : : > : Table cells :: >

      • Range-able :: : _ : % : > : Attributes :: >

      • Nestable ::

      \n

      Structural Detached Modifiers

      \n

      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.

      \n

      Headings

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

      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.

      \n
      \n
      \n

      Nestable Detached Modifiers

      \n

      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.

      \n

      Unordered Lists

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

      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.

      \n

      Ordered Lists

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

      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.

      \n

      Quotes

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

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

      \n

      Attributes

      \n
      \n    \n            % attrib1\n    %% attrib2\n    %%% attrib3\n    %%%% attrib4\n    %%%%% attrib5\n    %%%%%% attrib6\n\n    \n
      \n\n
      \n

      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:

      \n    \n            % color\n    +color #FF0000\n    %% red\n    +color #00FF00\n    %% green\n    +color #0000FF\n    %% blue\n\n    This will be /red/(color:red), /green/(color:green) and /blue/(color:blue).\n\n    \n
      \n\n
      \n
      \n

      Limits

      \n

      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.

      \n
      \n
      \n

      Invalid Nestable Detached Modifier Examples

      \n
      \n    \n            >I am not a quote\n\n    some preceding text > I am also not a quote\n\n    >- I am not a valid detached modifier\n\n    > > I am only a level 1 quote\n\n    *\n        I am not a valid heading title.\n\n    \n
      \n\n
      \n
      \n

      Range-able Detached Modifiers

      \n

      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.

      \n

      Definitions

      \n

      Definitions are primarily of use to people who write technical documents. They consist of a term, and then are followed by a definition of that term.

      \n    \n            $ Term\n    Definition content.\n\n    \n
      \n\n
      \n

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

      \n    \n            $$ Term\n    Content of the definition.\n\n    Which scans up to the closing modifier.\n    $$\n\n    \n
      \n\n
      \n
      \n

      Footnotes

      \n

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

      \n    \n            ^ Single Footnote\n    Optional footnote content.\n\n    \n
      \n\n
      \n

      To create longer footnotes, use the ranged footnote syntax instead:

      \n    \n            ^^ Ranged Footnote\n    Content of the footnote.\n\n    Which scans up to the closing modifier.\n    ^^\n\n    \n
      \n\n
      \n
      \n

      Table Cells

      \n

      Table cells are used to, well, build up a table. Here are a few examples of table cells:

      \n    \n            : A1\n      Content of table cell at `A1`.\n    :: A2\n    > Content of table cell at `A2` (in a quote).\n    ::\n\n    \n
      \n

      Their semantics are described in more detail in the semantics document, which we recommend reading if you are interested in the behavior of objects as opposed to how they are defined.

      NOTE In order to make tables more aesthetically pleasing, they're commonly mixed with the intersecting modifier syntax to produce the following:

      \n    \n            : A1 : Content of table cell at `A1`.\n\n    \n
      \n\n
      \n
      \n

      Grouping

      \n

      Both nestable and range-able detached modifiers have a unique quality - when several consecutive modifiers of the same type are encountered (by consecutive we mean NOT separated via a paragraph break), they are treated as one whole object. This is crucial to understand as it is required for the many types of carryover tags to function.

      \n

      Examples

      \n
      \n    \n            The following items naturally group because they are range-able, for example forming a\n    definition list:\n    $ Term 1\n      Definition 1!\n    $ Term 2\n      Definition 2!\n\n    \n
      \n\n
      \n
      \n    \n            Together, these form one whole unordered list:\n    - List item 1\n    - List item 2\n\n    \n
      \n\n
      \n
      \n    \n            - List item in one list\n\n    - This item is in another list, because we used a {$ paragraph break} to split these items\n\n    \n
      \n
      \n

      Delimiting Modifiers

      \n

      In Norg, structural detached modifiers and indent segments may be terminated by a delimiting modifier. This kind of modifier must abide by the following rules:

      • A delimiting modifier can only occur at the beginning of the line (arbitrary whitespace (but nothing else!) may precede it)

      • A delimiting modifier must consist of two or more consecutive modifiers of the same type (a single character cannot be used to avoid false-positives during the typing process; plus a single character can look quite confusing/ugly when used like this...)

      • A delimiting modifier must be followed by an immediate line ending (without any extra whitespace; this disambiguates them from nestable detached modifiers like for example an unordered list item vs. the -- delimiting modifier)

      \n

      Weak Delimiting Modifier

      \n

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

      \n    \n            * Heading level 1\n      Text under first level heading.\n\n    ** Heading level 2\n       Text under second level heading.\n       ---\n\n      Text under first level heading again.\n\n    \n
      \n\n
      \n
      \n

      Strong Delimiting Modifier

      \n

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

      \n    \n            * Heading level 1\n      Text under first level heading.\n\n    ** Heading level 2\n       Text under second level heading.\n       ===\n\n    Text belonging to no heading level (i.e. belonging to the document's root).\n\n    \n
      \n\n
      \n
      \n

      Horizontal Rule

      \n

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

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

      Detached Modifier Extensions

      \n

      Detached modifiers support extensions which must immediately follow the detached modifier (or another extension). Note that detached modifiers must be succeeded with whitespace, therefore by "immediately followed" we mean after the whitespace character in the detached modifier, e.g. - (x) List item(lang:norg).

      The syntax is as follows:

      • An extension starts with a ( char

      • Immediately a special character must follow. This character determines the type of extension.

      • Some extensions can support parameters - if this is the case, the special character must be followed with whitespace after which the parameters (a sequence of words and/or newlines) ensue. Not all extensions support parameters and for good reason. There is no need to attach extra metadata to a done or undone state for instance. Several extensions should be delimited with the contextual `|` delimiter.

      • A | character may be matched, which allows the user to chain many extensions together, e.g. (x|# A)(lang:norg) (done with a priority of A).

      • Finally a ) char closes the extension.

      NOTE: The whole detached modifier extension must be followed by whitespace.

      \n

      TODO Status Extension

      \n

      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:

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

      Advanced Detached Modifier Extensions

      \n

      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.

      \n

      Timestamp Extension

      \n

      The timestamp extension allows you to associate a detached modifier with a date/time. The syntax for a timestamp is as follows: <day>,? <day-of-month> <month> <year> <time> <timezone>

      • The <day> value is reliant on the current locale, but the following alterations of that value are permitted:

        • Full version (e.g. Tuesday, Wednesday)

        • An unambiguous shorthand (a shorthand that can uniquely identify the day), e.g. Tue, We, M (Monday), Frid. Something like T is not allowed, as both Tuesday and Thursday could satisfy the input.

      • The ,? expression means that a , character may optionally exist in that location.

      • The <day-of-month> value is simply a numeric value with at most 3 digits (to disambiguate it from the <year> value).

      • The <month> value is a word-based representation of the current month (i.e. October, January etc.) dependent on the current locale. The same shorthand rules apply as in the <day> value.

      • The <year> value must be a numeric value with at least 4 digits.

      • The <time> value must consist of this format (in regex): \\d{1,2}:\\d{2}(\\.\\d{1,2})?. Some examples would be: 18:00, 5:32, 00:12.32.

      Obviously, you're not required to type the whole syntax out every time. Any of the elements in angled brackets (<>) can be dropped/ignored, but the order of those values may not change! Some examples of valid timestamps include:

      • Sat, 29 Oct 1994 19:43.31 GMT

      • We 12th Jan 2022

      Apart from just being able to supply a timestamp, you are also permitted to provide a range. The syntax is simple, and is contained within the extension:

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

      You can even omit some fields from either one of the sides like so:

      \n    \n             {@ 5th - 20th August 2022}\n\n    \n
      \n

      The matching fields will be automatically completed based on the information of the other half.

      \n
      \n
      \n

      Priority Extension

      \n

      This extension allows you to specify a priority of your detached modifier extension.

      Syntax:

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

      Note that Norg does not specify strict semantics for this detached modifier extension, and as such there is no set-in-stone way to specify priorities. The most common (and recommended) way to specify priorities is to go from A-Z, but many also prefer 0-9 or even named priorities like LOW/MEDIUM/HIGH.

      Neorg's GTD implementation even repurposes the priority for use as contexts, so yes, this detached modifier extension is very versatile.

      \n
      \n
      \n

      Due Date Extension

      \n

      As the name suggests, this extension marks something as "due before x", where x is a timestamp. Especially useful in GTD and other forms of note-taking and time management applications.

      Syntax:

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

      Start Date Extension

      \n

      A counterpart to the due date extension - defines when a task begins, also useful in GTD.

      Syntax:

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

      Detached Modifier Suffix

      \n

      Since nestable detached modifiers can only contain a paragraph this can cause severe limitations because the insertion of e.g. code blocks is not possible. To alleviate this deficiency, the detached modifier suffix exists, which temporarily increases the current indentation level to allow complex nested items within.

      There are two variations of the indent segment, the slide and the indent segment. NOTE After a detached modifier suffix is matched (either : or ::) a line ending must follow instantly.

      \n

      Slide

      \n

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

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

      These complex items may be any non-structural detached modifier, tag or paragraph.

      To terminate a slide, one of two conditions must be met:

      \n

      Examples

      \n
      \n
      Terminating via a Paragraph Break
      \n
      \n    \n              - :\n        This is part of the list item.\n        @code lua\n        print("This is also a part of the list item")\n\n        -- Despite the fact that there is a double newline dividing the `print` statement and this\n        -- comment, it is not a paragraph break, therefore it does not terminate the slide.\n        @end\n        $ Term\n        Here is a definition!\n\n      Now that there is a {$ paragraph break} between this paragraph and the previous item\n      this paragraph no longer belongs to the slide.\n\n    \n
      \n\n
      \n
      \n
      Terminating as Part of a Nestable Detached Modifier
      \n
      \n    \n              -- :\n         Content of the slide.\n      - Because this item is a level lower than the item containing the slide above\n        the slide is terminated.\n\n    \n
      \n\n
      \n\n
      \n
      \n

      Indent Segment

      \n

      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:

      \n    \n            - ::\n      This is some content.\n\n      $ Term\n        Definition.\n    - This is the second item of the list.\n      The indent segment did not need to be terminated.\n\n    - ::\n      This is another list.\n\n      |details\n      *hello* world!\n      |end\n\n      -- This is a nested item in the indent segment\n      -- And so is this.\n\n      But you can still continue your content here.\n      ---\n\n    Since there was no other item of the same type after the indent segment\n    it must be closed with `---` or `===`.\n\n    \n
      \n\n
      \n\n
      \n
      \n

      Tags

      \n

      The main differentiator from simple markup formats and more complex ones is the ability to define data and extensions for the format. Norg allows for you to extend its syntax and define data within clear boundaries - it does this using tags.

      NOTE Tags are the only way that extensions may be made to the format.

      There are 6 different tag types, each with their own way of changing the way text in Norg is interpreted. Before we discuss those, however, we should discuss the syntax rules for tags:

      • A tag is similar to a detached modifier in the sense that it must begin at the beginning of a line with optional whitespace (but nothing else) preceding it.

      • After that you will encounter a special tag character (=, |, @, #, + and .), none of which are attached modifiers (see disambiguating tags and attached modifiers). The special tag character is then immediately followed by text, which becomes the tag name. Said tag name can consist of any regular character and/or - and _.

      • Tags can have their names delimited by a . in order to create a "hierarchy", e.g. document.meta.

      • After a whitespace character any number of parameters on the same line may follow:

        \n    \n            #tag-name.subtag parameter1 parameter2\n\n    \n
        \n

        By default parameters are space-separated. In order to create multi-word parameters, you may escape the space character with a backslash (`).\n |example\n #tag-name.subtag parameter1 with spaces parameter2\n |end\n Parameters may consist of any character (apart from a {*** line endings}[line ending], of course).\n ---\n\n ^ Disambiguating tags and attached modifiers\n If tag characters were attached modifier openers there would be no way to know whether the\n character is an attached modifier opener or a tag opener until the whole line has been parsed;\n in other words, such a scenario would entail a difficult to resolve ambiguity.\n\n Norg provides several inbuilt tag names that are reserved, but their details are not explained\n in this specification - this document strictly covers syntax - see the [semantics document] for a\n list of the built-in tags. There is no restriction in regard to the length of a tag name, nor are\n there any disallowed names that a parser should omit (unless they don't adhere to the above rules\n regarding tag names).\n\n** Ranged Tags\n Ranged tags are a way to express custom information within a range.\n They begin with the traditional tag declaration and are ended with an `end statement.

        The end statement has a simple rule set:

      • Must be at the start of a line, may be preceded by any whitespace (but nothing else)

      • Must use the same prefix as its parent (in the case of standard ranged tags: |; in the case of verbatim tags: @; for macro tags: =)

      • Must immediately be succeeded by a line ending.

      \n

      Macro Tags

      \n

      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\n 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:

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

      It can then be invoked using any of the other tag types, for example the infirm tag:

      \n    \n            This is a recipe for a cake\n    .see https://wikipedia.com/some-cool-cake-recipe\n    \\- let's begin cooking!\n\n    \n
      \n\n
      \n

      After macro expansion, this is what the document would look like:

      \n    \n            This is a recipe for a cake\n    (see {https://wikipedia.com/some-cool-cake-recipe})\n    \\- let's begin cooking!\n\n    \n
      \n

      Which, when reformatted, would look (and render) like so:

      \n    \n            This is a recipe for a cake (see {https://wikipedia.com/some-cool-cake-recipe}) - let's begin\n    cooking!\n\n    \n
      \n
      \n

      Standard Ranged Tags

      \n

      There are times when you may want to create an isolated block of Norg markup. To do this you may use the standard ranged tag, which uses the | character.

      Currently, it is only used for four tags, comment, example, details and group

      • The comment ranged tag is used for long strings of comments (versus the % null attached modifier, which is mostly used for short comments).

      • The example tag is a simple way to show an example of some Norg markup without it being rendered and treated as physical markup (most commonly used throughout this very document to show unrendered examples of Norg syntax).

      • The details tag is a way to hide away markup (just like <details> in HTML).

      • The group tag may be used to group together many elements and apply a global strong carryover tag to each one of them.

      \n

      Examples

      \n

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

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

      \n    \n           Here, I can write `| leading and trailing whitespace (with a ` char)  |` within a verbatim block\n   without accidentally terminating it.\n\n   Here, I can use a literal `$` inside inline math: $| 10$ + 10$ = 20$ |$.\n\n    \n
      \n\n
      \n

      The use of pipes is special because the position of the pipe (i.e. whether it's before or after the attached modifier) can unambiguously tell us whether that symbol is an opening attached modifier or a closing one. It's thanks to this that whitespace is freely allowed within its content.

      Aside from the details described above, free-form attached modifiers have the following properties:

      • Backslashes (`) are treated as verbatim and do not mean an {*** escaping}[escape sequence]\n (see {* precedence}).\n - Despite being called "free-form" they can still only span a single paragraph (see {# attached\n modifier range}).\n\n** Link Modifier\n The link modifier, `:, is a special modifier type - it puts a twist on the original attached modifier rules - in fact, it's the polar opposite.

      As described in the attached modifiers section, attached modifier types may not exist in between words like so:

      \n    \n           abso/freaking/lutely!\n\n    \n
      \n\n
      \n

      It's entirely plausible to want to do this however, which is why the link modifier was devised. With it, you can bridge attached modifiers and regular text together:

      \n    \n           abso:/freaking/:lutely!\n\n    \n
      \n

      It is important to note that link modifiers do not need to occur in pairs. This:

      \n    \n           Ex:*ample* text\n\n    \n
      \n

      Will also result in ample becoming bold. In fact, using a link modifier at the end will not give the desired result (it will be rendered as a regular : char). To understand why keep reading.

      Through the examples above it is evident that there are two link modifier types: one where the link modifier is an opening link modifier (i.e. it appears before an opening attached modifier) and one where it's a closing link modifier (i.e. it appears after a closing attached modifier). This distinction is visible even when they don't occur in pairs.

      In the case that the link modifier is opening (the attached modifier appears on the right):

      • The link modifier may only be preceded by a regular character (or, in other words, may not be preceded by a punctuation character nor by a whitespace character).

      • The link modifier may only be succeeded by an opening attached modifier.

      In the case that the link modifier is closing (the attached modifier appears on the left):

      • The link modifier may only be preceded by a closing attached modifier.

      • The link modifier may only be succeeded by a regular character.

      If the above conditions are not met, then the character should be treated as a literal :.

      \n

      Attached Modifier Extensions

      \n

      Similarly to detached modifier extensions, attached modifier extensions serve as a way to attach metadata to attached modifiers. The metadata that you can attach, however, differs from detached modifier extensions, as they serve different use cases.

      The content of attached modifier extensions consists of a set of references to many attributes. These attributes are delimited by the contextual `|` delimiter. If the attribute is part of a hierarchy (see attributes), you may use the : character to link them together. Some inbuilt attributes are the lang and color hierarchies (a comprehensive list can be found in the semantics document).

      \n

      Examples

      \n
      \n    \n            `print("This is some python")`(lang:python) <- The lang:python attribute highlights the text as python\n    *some green and bold text!*(color:green)    <- some green and bold text\n\n    {* Link location}[this is an important link](important|color:red) <- Highlights the link as big,\n                                                                         bold (important) and red.\n\n    \n
      \n\n
      \n\n
      \n
      \n

      Contextual | Delimiter

      \n

      The pipe (|) character is a really nice character - it can be applied to many problems and expressively represent certain behaviors, specifically delimiting. While also used for standard ranged tags and free-form attached modifiers, the pipe symbol is also used as a delimiter for detached and attached modifier extensions. Even though it's used 3 times for different purposes, the contexts in which they are used in allows for them to be unambiguous. It also keeps intent consistent across the format.

      \n
      \n
      \n

      Intersecting Modifiers

      \n

      Norg is a syntax designed to be used by many - this includes many styles and preferences. Although it's impossible to satisfy everyone, there are some variations of syntax that can be used to "beautify" Norg markup. The intersecting modifier does just that - it's a way to intersect two different paragraph segments (and only paragraph segments) together on the same line.

      The syntax is as follows:

      • First, a whitespace character must be matched

      • Next, the actual modifier (currently only :) must be matched.

      • The token ends with another whitespace character.

      The use case for the intersecting modifier is best illustrated by example:

      \n    \n          $ Term\n    This is a definition of that term.\n\n    \n
      \n

      This is perfectly normal syntax that you would write day to day in Norg. But what if you're more of a fan of one-liners? The : intersecting modifier (currently the only modifier of this type) can be used to do just this:

      \n    \n          $ Term : This is a definition of that term.\n\n    \n
      \n

      This syntax is especially favored for table cells:

      \n    \n          : A1 : Content of the cell at A1\n  : A2 : Content of the cell at A2\n\n    \n
      \n\n
      \n

      The : syntax expands to a newline, which means that after expansion you get:

      \n    \n          : A1\n  Content of the cell at A1\n  : A2\n  Content of the cell at A2\n\n    \n
      \n
      \n

      Linkables

      \n

      Finally, there is one more kind of inline syntax which is the linkables kind. Linkables can link to any element anywhere in the document.

      When resolving links, the first match should always be the only match, starting from the top of the document and heading towards the bottom. This means that if there are two matches, the one at the topmost part of the document should be chosen as the target.

      Linkables are comprised of many segments, and can change meaning depending on the order those segments were defined in.

      Linkables are essentially a more lenient version of the attached modifier syntax. Below are the rules for linkables:

      • An opening modifier may be instantly succeeded with anything but a line ending.

      • A closing modifier may not be preceded by a line ending.

      Below are a few examples of invalid linkables:

      \n    \n          this is not a {\n  * linkable}\n\n  nor is this a [linkable\n  ]\n\n  <\n  this certainly isn't a linkable\n  >\n\n    \n
      \n\n
      \n

      An unclosed linkable may be treated as an error in the resulting syntax tree.

      \n

      /, @ and URLs are not allowed in combination with file locations:

      \n    \n            {:path:/ file} <- invalid\n    {:path:@ timestamp} <- invalid\n    {:path:https://my-url} <- also invalid\n\n    \n
      \n
      \n

      Line Number

      \n

      You can also link to a set line number within the current (or other Norg) file.

      The syntax is as follows:

      \n    \n            Line 1\n    Line 2\n\n    This is a reference to line {2}.\n    This is a reference to line {:file:4} in a different file.\n\n    \n
      \n\n
      \n

      Disambiguating line numbers and URIs is quite simple - URIs do not begin with digits.

      \n

      URL

      \n

      You can define a link to an external resource by simply putting in the URL:

      \n    \n            {https://github.com/nvim-neorg/neorg}\n\n    \n
      \n\n
      \n

      Actions related to schemas like https://, ftp:// etc. (when attempting to open the link) are handled by a lower level component running Norg, e.g. Neorg or the underlying Operating System.

      \n

      Detached Modifier

      \n

      Norg allows you to link to any structural or range-able detached modifier:

      \n    \n            * I am a level 1 heading\n\n    Strict link to a level 1 heading:\n    {* I am a level 1 heading}\n\n    \n
      \n\n
      \n

      The inside of the link location looks just like a detached modifier definition, and that is because it pretty much is. You can substitute the * char for any other structural or range-able detached modifier, except "ranged" versions of said modifiers - those are disallowed within the link syntax. By this we mean that syntax like {$$ Text} is invalid. To link to a ranged definition you would still use {$ Text}, there is no reason to make a distinction between a ranged and non-ranged detached modifier as both have the same meaning, one just allows more content to exist within itself.

      \n

      Custom Detached Modifiers

      \n

      Apart from linking to the detached modifiers outlined above, you can also link to a set of custom modifiers specifically designed for links. These are the # (magic), / (file), @ (timestamp), ? (wiki link) and = (extended) linkable locations.

      \n

      The Magic Char (#)

      \n

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

      \n
      \n
      \n

      The File Linkable (/)

      \n

      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:

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

      As with the path modifier syntax, the file linkable also supports special characters like ~ for the user's home directory and the special $ character to denote the root of the current workspace.

      \n

      Timestamps (@)

      \n

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

      Example:

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

      For developers implementing this behavior: there are no restrictions in which order you parse your files to hop between wiki links, as long as the following conditions are met:

      • The current file is the first file that is searched (this allows for ? to also work as a generic catchall link for all heading levels)

      • All files in the current workspace are parsed/enumerated (including subdirectories)

      \n
      Additional Behaviors With {:file:}
      \n

      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.

      \n
      \n\n

      For a more detailed explanation of the behavior of this link consult the semantics document.

      \n
      \n
      \n

      Inline Linkables

      \n

      Although most linkable items are either structural or range-able, there are also syntax elements in Norg that are inline - these are the #name carryover tag and the inline link target. Both of these can only be linked to through the the magic char.

      \n
      \n
      \n

      Differences Between File Linkables

      \n

      You may have realized that there are many ways to reference a file:

      • {:my/file:}

      • {/ my/file.norg}

      • {file://my/file.norg}

      Why are there this many?

      1. {:my/file:} is strictly to access .norg files and nothing else. More specifically, it's designed to access a resource within a file ({:my/file:* Heading}), with the side effect of being able to also exist in a standalone fashion ({:my/file:}).

      2. {/ my/file.norg} is used to link to a file and a file only (vs {:my/file:* Heading} which links to an element within a file). Although it can link to .norg files, its main use is to link to non-.norg files instead. Using the / syntax also disallows you from accessing items within the file.

      3. {file://my/file.norg} is simply utilizing the file:// schema to access a file. This isn't the recommended way to link to files, but it exists simply because of URI schemas.

      \n
      \n
      \n

      Scoping

      \n

      Within linkables it is possible to narrow down the search of the link via the : scoping modifier. This modifier can exist because under normal circumstances when parsing e.g. the title of a heading a : sequence of characters would be considered an intersecting modifier.

      Below is an example of the scoping modifier in use:

      \n    \n            {* Heading Name : *** Level 3 heading}\n\n    \n
      \n\n
      \n

      The search narrows the search to a Level 3 heading within a level 1 heading called Heading\n Name. This search is descending in terms of nesting, in other words, you cannot do {*** Heading3 : * Heading1}.

      This scoping is not limited to any item type. You are free to perform searches like {$ Definition : $ Nested Definition : ^ Footnote}, which searches for a footnote within a definition called Nested Definition within a definition called Definition.

      \n\n

      When a custom description is required, it must be placed after the link location. This makes sense in terms of writing as you first define where you link to, and then annotate it afterwards:

      \n    \n           Click {* I am a link}[here] to find out more.\n\n    \n
      \n
      \n

      Anchors

      \n

      Norg also has a concept called anchors. These allow you to place a standalone link description inside of text (referred to as an anchor declaration). The target which this anchor links to can then be defined at another place in the document with an anchor definition which is an initial link description followed by a link location. This is especially useful when you want to link to the same target very often, like for example a specific website.

      Below are a few usage examples:

      \n    \n           [Neorg] is a fancy organizational tool for everyone.\n\n   I like shilling [Neorg]{https://github.com/nvim-neorg/neorg} sorry :(\n\n    \n
      \n

      Here, we declare the anchor once at the top, then define the anchor at the very bottom. The [Neorg] declaration points directly to the website, just like the definition does. It's like a copy + paste of the link location without needing to type it out.

      Other than the declaration behavior described above anchors have no other special meaning and/or semantics, and behave just like regular links do. This means they can be used as a substitute for regular links should the user prefer the "description + location" syntax versus the "location + description" syntax.

      Anchors (like links) may also be described by using [...], in which case the syntax looks like this: [anchor name][anchor description].

      \n
      \n\n

      An important thing to note is that since inline link targets are - well - inline, they cannot be directly linked to with a dedicated char in the link syntax. To link to these syntax elements you may only use the magic char.

      Unlike links and anchors, inline link targets may not have a description.

      \n

      Valid/Invalid Examples

      \n
      \n

      Valid Examples

      \n
      \n    \n            {link}\n\n    {* \n    text}\n\n    {* text }\n\n    {* some\n    text   }\n\n    {:link:}\n\n    {:link:20}\n\n    {# link\n       text}\n\n    {* a link\n    to a heading}\n\n    {* text}[content ]\n\n    {* a\n    link to a heading}[with\n    a description]\n\n    [te\n    xt]{# linkable}\n\n    {* Link to {# headings}[heading]}[*markup*]\n\n    \n
      \n\n
      \n
      \n

      Invalid Examples

      \n
      \n    \n            {*text}\n\n    {:file:https://github.com}\n    {:file:/ file.txt}\n    {:file:@ Wednesday 30th Jan}\n\n    {\n    * text}\n\n    {\n        * text\n    }\n\n    {* text\n    }\n\n    { * text}\n\n    {* text}[\n        text\n    ]\n\n    {* text}[text\n    ]\n\n    {* text}[\n    text]\n\n    \n
      \n\n
      \n\n
      \n
      \n

      Standard Library

      \n

      Norg comes loaded with a predetermined set of attributes and macro tags for different layers of the syntax. These are defined in the semantics document.

      \n
      \n
      \n

      Precedence

      \n

      Precedence in Norg is rather simple and intuitive.

      • All non-inline elements have direct precedence over all inline elements.

      • Inline elements with a deterministic start and end have greater priority than those that don't.

      • Verbatim elements have greater priority than non-verbatim elements.

      Here's the full list ordered by decreasing precedence:

      1. Tags (#infecting, +carryover, .infirm, |standard, @verbatim and =macro)

      2. Structural detached modifiers

      3. Nestable detached modifiers and range-able detached modifiers (there is no such case where these could overlap)

      4. Detached modifier extensions

      5. Linkables ({}, [], <>)

      6. Verbatim free-form attached modifiers (||, ||)

      7. The escape character (`)\n ~ Verbatim {# attached modifiers}\n ~ Standard (non-verbatim) {# free-form attached modifiers} (|, `|//| etc.)

      8. Standard (non-verbatim) attached modifiers

      Should any extra precedence problems arise (let us know if you find any) they can be disambiguated through a simple left-to-right precedence approach.

      Note that although e.g. linkables are above standard attached modifiers, this does not mean that standard attached modifiers cannot contain linkables, but in case there is an overlap the linkable will have higher precedence.

      For example, this is valid:

      \n    \n          *{# i am a bold link!}*\n\n    \n
      \n\n
      \n

      However, in this case:

      \n    \n          *am I {* bold?} - no!\n\n    \n
      \n

      The link takes precedence, and no bold is rendered.

      \n

      Layers

      \n

      Norg is built up of layers, or in other words a set of features that a parser/tool can support depending on how much of the specification they'd like to deal with.

      It's recommended to stick to these layers when implementing Norg in your own application (as it's easy to tell end users that an application supports e.g. "layer 2" of the Norg specification), but of course these can't apply to every possible use case. In such case you can use a custom layer and pick and choose what you want to support. Just make sure to let your users know which features you've implemented, so they don't get confused!

      \n

      Layer 1

      \n

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

      \n
      \n
      \n

      Layer 2

      \n

      The second layer outlines the basic structure for a document:

      \n
      \n
      \n

      Layer 3

      \n

      This layer is for documents of medium/high complexity:

      \n
      \n
      \n

      Layer 4

      \n

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

      \n
      \n
      \n

      Layer 5

      \n

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

      \n
      \n\n
      \n

      \n
      \n
        \n
      1. \n

        Optional footnote content.

        \n ↩︎\n
        2. \n
      2. \n

        Content of the footnote.

        Which scans up to the closing modifier.

        \n ↩︎\n
        3. \n
      3. \n

        It should be mentioned that a parser of the Norg format is not required to perform any timestamp analysis further than detecting what set of characters contain a timestamp. The actual interpretation of its internal fields and the interpretation of a range are the responsibility of the semantic analyzer (see also the semantics document).

        \n ↩︎\n
        4. \n\n
      \n
      \n\n
      \n","category":"page"},{"location":"internals/tokens/#Tokens","page":"Tokens","title":"Tokens","text":"","category":"section"},{"location":"internals/tokens/","page":"Tokens","title":"Tokens","text":"Modules = [Norg.Tokens, Norg.Tokenize]","category":"page"},{"location":"internals/tokens/#Tokens-2","page":"Tokens","title":"Tokens","text":"","category":"section"},{"location":"internals/tokens/","page":"Tokens","title":"Tokens","text":"Modules = [Norg.Tokens]","category":"page"},{"location":"internals/tokens/#Norg.Tokens","page":"Tokens","title":"Norg.Tokens","text":"Provides the tokens for the tokenizer.\n\nA Tokens.Token stores its value, a Kinds.Kind and a Tokens.TokenPosition\n\n\n\n\n\n","category":"module"},{"location":"internals/tokens/#Norg.Tokens.Token","page":"Tokens","title":"Norg.Tokens.Token","text":"A Norg Token has a Kinds.kind (i.e. K\"EndLine\"), a position, and a value.\n\nSee also: Tokens.TokenPosition\n\n\n\n\n\n","category":"type"},{"location":"internals/tokens/#Norg.Tokens.Token-NTuple{4, Any}","page":"Tokens","title":"Norg.Tokens.Token","text":" Token(kind, line, char, value)\n\nCreate a Token of kind kind with value value at line and char number char.\n\n\n\n\n\n","category":"method"},{"location":"internals/tokens/#Norg.Tokens.TokenPosition","page":"Tokens","title":"Norg.Tokens.TokenPosition","text":"Stores the position of a token in the input file (line and char).\n\n\n\n\n\n","category":"type"},{"location":"internals/tokens/#Norg.Tokens.char-Tuple{Norg.Tokens.TokenPosition}","page":"Tokens","title":"Norg.Tokens.char","text":"char(x)\n\nReturn the character number in the line corresponding to position or token x.\n\n\n\n\n\n","category":"method"},{"location":"internals/tokens/#Norg.Tokens.line-Tuple{Norg.Tokens.TokenPosition}","page":"Tokens","title":"Norg.Tokens.line","text":"line(x)\n\nReturn the line number corresponding to the position or token x.\n\n\n\n\n\n","category":"method"},{"location":"internals/tokens/#Tokenize","page":"Tokens","title":"Tokenize","text":"","category":"section"},{"location":"internals/tokens/","page":"Tokens","title":"Tokens","text":"Modules = [Norg.Tokenize]","category":"page"},{"location":"internals/tokens/#Norg.Tokenize","page":"Tokens","title":"Norg.Tokenize","text":"Produce Tokens.Token vectors from a string using tokenize.\n\n\n\n\n\n","category":"module"},{"location":"internals/tokens/#Norg.Tokenize.tokenize-Tuple{AbstractString}","page":"Tokens","title":"Norg.Tokenize.tokenize","text":"tokenize(input)\n\nProduce Tokens.Token vectors from an input string.\n\n\n\n\n\n","category":"method"},{"location":"internals/codegen/#Codegen","page":"Codegen","title":"Codegen","text":"","category":"section"},{"location":"internals/codegen/","page":"Codegen","title":"Codegen","text":"Modules = [Norg.Codegen]","category":"page"},{"location":"internals/codegen/","page":"Codegen","title":"Codegen","text":"Modules = [Norg.Codegen]","category":"page"},{"location":"internals/codegen/#Norg.Codegen","page":"Codegen","title":"Norg.Codegen","text":"This module holds all the code generation targets, as well as some generic utilities to help with code generation.\n\n\n\n\n\n","category":"module"},{"location":"internals/codegen/#Norg.Codegen.codegen","page":"Codegen","title":"Norg.Codegen.codegen","text":"codegen(T, ast)\ncodegen(target, ast)\n\nDo code generation for a given AST.NorgDocument to a given target.\n\n\n\n\n\n","category":"function"},{"location":"internals/kinds/#Kinds","page":"Kinds","title":"Kinds","text":"","category":"section"},{"location":"internals/kinds/","page":"Kinds","title":"Kinds","text":"Modules = [Norg.Kinds]","category":"page"},{"location":"internals/kinds/","page":"Kinds","title":"Kinds","text":"Modules = [Norg.Kinds]","category":"page"},{"location":"internals/kinds/#Norg.Kinds","page":"Kinds","title":"Norg.Kinds","text":"To provide a type-stable parser, we handle types ourselves. This is directly inspired by JuliaSyntax.jl. See here\n\nYou can see kinds as an advanced Enum type that allows some kind of grouping of values. We use Kinds.Kind to classify the different types of tokens ast nodes.\n\n\n\n\n\n","category":"module"},{"location":"internals/kinds/#Norg.Kinds._kind_names","page":"Kinds","title":"Norg.Kinds._kind_names","text":"All the defined kind names.\n\n\n\n\n\n","category":"constant"},{"location":"internals/kinds/#Norg.Kinds.Kind","page":"Kinds","title":"Norg.Kinds.Kind","text":"Kind(name)\nK\"name\"\n\nThis is type tag, used to specify the type of tokens and AST nodes.\n\n\n\n\n\n","category":"type"},{"location":"internals/kinds/#Norg.Kinds.kind-Tuple{Norg.Kinds.Kind}","page":"Kinds","title":"Norg.Kinds.kind","text":"kind(x)\n\nReturn the Kind of x.\n\n\n\n\n\n","category":"method"},{"location":"internals/kinds/#Norg.Kinds.@KSet_str-Tuple{Any}","page":"Kinds","title":"Norg.Kinds.@KSet_str","text":"A set of kinds which can be used with the in operator. For example k in KSet\"+ - *\"\n\n\n\n\n\n","category":"macro"},{"location":"internals/kinds/#Norg.Kinds.@K_str-Tuple{Any}","page":"Kinds","title":"Norg.Kinds.@K_str","text":"K\"s\"\n\nThe kind of a token or AST internal node with string \"s\". For example\n\nK\">\" is the kind of the greater than sign token\n\n\n\n\n\n","category":"macro"},{"location":"","page":"Home","title":"Home","text":"CurrentModule = Norg","category":"page"},{"location":"#Norg","page":"Home","title":"Norg","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Documentation for Norg.jl.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Norg.jl is a library to work with the norg file format used in neorg. It currently implements the Layer 2 compatibility.","category":"page"},{"location":"","page":"Home","title":"Home","text":"For a show-case of how the parser performs, please visit the norg specification rendering page. Note that the specification is not layer-2-friendly, so some parts just do not make sense for now.","category":"page"},{"location":"","page":"Home","title":"Home","text":"Pages = [\"index.md\"]","category":"page"},{"location":"#General-usage","page":"Home","title":"General usage","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"There are currently two available code generation targets for Norg.jl: HTML and Pandoc JSON. Given a string to barse s, you can use:","category":"page"},{"location":"","page":"Home","title":"Home","text":"norg(HTMLTarget(), s)","category":"page"},{"location":"","page":"Home","title":"Home","text":"or","category":"page"},{"location":"","page":"Home","title":"Home","text":"norg(JSONTarget(), s)","category":"page"},{"location":"","page":"Home","title":"Home","text":"The sources for the Norg specification are available in an artifact of this package. Thus, you can generate an HTML version of the specification using:","category":"page"},{"location":"","page":"Home","title":"Home","text":"using Norg\n\ns = open(Norg.NORG_SPEC_PATH, \"r\") do f\n read(f, String)\nend;\nopen(\"1.0-specification.html\", \"w\") do f\n write(f, string(norg(HTMLTarget(), s)))\nend","category":"page"},{"location":"","page":"Home","title":"Home","text":"Since Pandoc JSON is also available, you can export to Pandoc JSON and feed it to pandoc:","category":"page"},{"location":"","page":"Home","title":"Home","text":"import JSON\nopen(\"1.0-specification.json\", \"w\") do f\n JSON.print(f, norg(JSONTarget(), s), 2)\nend;","category":"page"},{"location":"","page":"Home","title":"Home","text":"You can then invoke Pandoc as follow:","category":"page"},{"location":"","page":"Home","title":"Home","text":"pandoc -f json -t markdown 1.0-specification.json -o 1.0-specification.md","category":"page"},{"location":"#Advanced-usage","page":"Home","title":"Advanced usage","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"You can also generate an Abstract Syntax Tree (AST) that implements AbstractTrees.jl interface using norg. See also the AST module.","category":"page"},{"location":"","page":"Home","title":"Home","text":"norg(s)","category":"page"},{"location":"#Public-API","page":"Home","title":"Public API","text":"","category":"section"},{"location":"","page":"Home","title":"Home","text":"Modules = [Norg]","category":"page"},{"location":"#Norg.Norg","page":"Home","title":"Norg.Norg","text":"Norg.jl provides a way to parse Neorg files in pure Julia.\n\nIt overloads Base.parse with custom targets. So far the only available target is HTMLTarget.\n\nExample usage :\n\nusing Norg\nnorg(HTMLTarget(), \"Read {https://github.com/nvim-neorg/norg-specs}[the spec !]\")\n\n\n\n\n\n","category":"module"},{"location":"#Norg.NORG_SEMANTICS_PATH","page":"Home","title":"Norg.NORG_SEMANTICS_PATH","text":"Path to the Norg semantics specification.\n\n\n\n\n\n","category":"constant"},{"location":"#Norg.NORG_SPEC_PATH","page":"Home","title":"Norg.NORG_SPEC_PATH","text":"Path to the Norg specification.\n\n\n\n\n\n","category":"constant"},{"location":"#Norg.NORG_SPEC_ROOT","page":"Home","title":"Norg.NORG_SPEC_ROOT","text":"The root directory of the Norg specification.\n\n\n\n\n\n","category":"constant"},{"location":"#Norg.NORG_STDLIB_PATH","page":"Home","title":"Norg.NORG_STDLIB_PATH","text":"Path to the Norg standard library.\n\n\n\n\n\n","category":"constant"},{"location":"#Norg.consume_until-Tuple{Norg.Kinds.Kind, Vector{Norg.Tokens.Token}, Any}","page":"Home","title":"Norg.consume_until","text":"consume_until(k, tokens, i)\nconsume_until((k₁, k₂...), tokens, i)\n\nConsume tokens until a token of kind k is encountered, or final token is reached.\n\n\n\n\n\n","category":"method"},{"location":"#Norg.findtargets!-Tuple{Norg.AST.NorgDocument}","page":"Home","title":"Norg.findtargets!","text":"findtargets!(ast[, node])\n\nIterate over the tree to (re)build the targets attribute of the AST, listing all possible targets for magic links among direct children of node.\n\nIf node is not given, iterate over the whole AST, and empty! the targets attribute of the AST first.\n\n\n\n\n\n","category":"method"},{"location":"#Norg.getchildren-Tuple{Norg.AST.Node, Norg.Kinds.Kind}","page":"Home","title":"Norg.getchildren","text":"getchildren(node, k)\ngetchildren(node, k[, exclude])\n\nReturn all children and grandchildren of kind k. It can also exclude certain nodes from recursion.\n\n\n\n\n\n","category":"method"},{"location":"#Norg.idify-Tuple{Any}","page":"Home","title":"Norg.idify","text":"idify(text)\n\nMake some text suitable for using it as an id in a document.\n\n\n\n\n\n","category":"method"},{"location":"#Norg.norg-Tuple{Any}","page":"Home","title":"Norg.norg","text":"norg([codegentarget, ] s)\n\nParse the input s to an AST. If codegentarget is included, return the result of code generation for the given target.\n\nExamples\n\njulia> norg(\"* Hello world!\")\nNorgDocument\n└─ (K\"Heading1\", 2, 8)\n └─ (K\"ParagraphSegment\", 4, 7)\n ├─ Hello\n ├─\n ├─ world\n └─ !\njulia> norg(HTMLTarget(), \"* Hello world!\")\n

      Hello world!

        \n\n\n\n\n\n","category":"method"},{"location":"#Norg.parse_norg_timestamp-Tuple{Any, Any, Any}","page":"Home","title":"Norg.parse_norg_timestamp","text":"parse_norg_timestamp(tokens, start, stop)\n\nParse a Norg timestamp to Julia DateTime. A timestamp has the following structure:\n\n,?