Norg.jl is a library to parse the norg file format used in NeoVim's neorg.
This is heavily work in progress, so expect breaking changes. Meanwhile, I'd be really happy if you could try Norg.jl and tell me if you find unexpected behaviours.
The package is registered.
]add NorgIf you want the latest dev version:
]add https://github.com/Klafyvel/Norg.jlFor now layer 3 compatibility is implemented in the parser, and there is code generation for html and pandoc JSON targets. There is no semantic analysis yet, which for example means that links to line number or using the # target syntax are poorly handled in code generation.
julia> using Norg
julia> s = """
Hi ! I am a Norg document. For now only /basic/ *markup* is !implemented!.
That should not prevent you from *,!nesting!, ^the^ /good/ `stuff`*
You can of course make paragraphs, you -nerd- /beautiful/ nerd.
We also can use links : {https://example.com}
But it's easier to read if you use a link description, as in this link towards {https://klafyvel.me}[my *website*] !
""";
julia> norg(HTMLTarget(), s)
# pretty HTML prints there, but have a look at its rendering below
julia> norg"Neorg also has a string macro that can be used in Pluto"Hi ! I am a Norg document. For now only
basic
markup is
implemented.
That should not prevent you from *
nesting
the
good
stuff*
You can of course make paragraphs, you
nerd
beautiful nerd.
We also can use links : https://example.com
But it's easier to read if you use a link description, as in this link towards my website !
Note that you can parse the entire Norg specification just like that:
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)))
endNorg.jl is also capable of outputing Pandoc JSON, allowing you to feed your Norg files 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 - (x) Layer 1 support
- (x) Layer 2 support
- (x) Layer 3 Support
- (-) Layer 4 support
-- (x) Standard Ranged Tags
-- ( ) Table cells
-- (x) Free-form attached modifiers
-- ( ) Intersection modifiers
-- ( ) Attached modifier extensions
-- (x) Inline mathematics and variable attached modifiers
#waiting.for Layer 4 support
- ( ) Layer 5 support
-- ( ) Interpretation/Execution of macro tags
-- ( ) Semantic understanding/execution of carryover tags
-- ( ) Evaluation of `@code` blocs for the NIP language (if they are marked with `#eval`)
#waiting.for Layer 4 support
- ( ) FileIO.jl integration
- ( ) Various code generation
-- (-) HTML
--- (x) Layer 1 support
--- (x) Layer 2 support
--- (x) Layer 3 support
--- (-) Layer 4 support
--- ( ) Layer 5 support
-- ( ) Markdown
--- ( ) Layer 1 support
--- ( ) Layer 2 support
--- ( ) Layer 3 support
--- ( ) Layer 4 support
--- ( ) Layer 5 support
-- (-) Pandoc JSON
--- (x) Layer 1 support
--- (x) Layer 2 support
--- (x) Layer 3 support
--- (-) Layer 4 support
--- ( ) Layer 5 support
-- ( ) Julia Terminal display using julia's nice features such as `printstyled` and others.
--- ( ) Layer 1 support
--- ( ) Layer 2 support
--- ( ) Layer 3 support
--- ( ) Layer 4 support
--- ( ) Layer 5 support
-- ( ) Norg
--- ( ) Layer 1 support
--- ( ) Layer 2 support
--- ( ) Layer 3 support
--- ( ) Layer 4 support
--- ( ) Layer 5 support
#waiting.for Layer 4 support
- ( ) Consume pandoc JSON to create a Norg AST.
#waiting.for Layer 4 support
- ( ) Export CLI utility
#contexts someday
- ( ) Allow Franklin.jl to use Norg file format, because NeoVim+Julia = <3
#contexts someday
- ( ) Documenter.jl plugin
There are three main steps for turning Norg files into HTML (since it's the only supported target for now).
- Tokenizing (identifying the different chunks of code)
- Parsing (create an Abstract Syntax Tree, AST)
- Code generation (turning the AST into HTML)
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.
- neorg-dashboard, a simple filewatcher and renderer of norg in julia.