Edit on GitHub

Norg

Documentation for Norg.jl.

Norg.jl is a library to work with the norg file format used in neorg. It currently implements the Layer 2 compatibility.

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.

General usage

There are currently two available code generation targets for Norg.jl: HTML and Pandoc JSON. Given a string to barse s, you can use:

norg(HTMLTarget(), s)

or

norg(JSONTarget(), s)

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:

using Norg

s = open(Norg.NORG_SPEC_PATH, "r") do f
    read(f, String)
end;
open("1.0-specification.html", "w") do f
    write(f, string(norg(HTMLTarget(), s)))
end

Since Pandoc JSON is also available, you can export to Pandoc JSON and feed it to pandoc:

import JSON
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.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)
      ├─ Hello
      ├─
      ├─ 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
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 — 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)
      ├─ Norg
      ├─
      ├─ Header
      ├─
      ├─ 1
      ├─
      └─ Example
source

Inner API

The inner API is documented in the Norg internals page.