/neorg-pandoc

Neorg pandoc extension.

Primary LanguageHaskellMIT LicenseMIT

Neorg Haskell Parser

Reimplementation of the parser with the Neorg markup specification. It will be able to transform .norg files to the pandoc AST and subsequently to the plethora of formats that pandoc supports.

Create an issue if you find unexpected behavior!

Help me to find all edge cases of the parser. If you find a parsing error, you can create an issue with the Parsing / Generation error template.

Parser Implementation State

I will focus on the first three layers for now. Layers 4 and 5 are on hold for now.

  • Layer 1
  • Layer 2
  • Layer 3

Pandoc Implementation State

  • Layer 1
  • Layer 2
  • Layer 3
  • PDF creation

Installation

Using a precompiled binary

I have added a compiled binary for linux in the releases section of github, which should work on most x86 linux systems.

Building from Source

You will need ghc and cabal. Then you can build the project with:

cabal build neorg-pandoc

You can run the tests with:

cabal run neorg-test

Usage

After having aquired a binary of neorg-pandoc, you can use it to transform Neorg files into Pandoc json documents. You have two ways of feeding your norg document to neorg-pandoc:

  1. -f file.norg: neorg-pandoc will read file.norg and print a pandoc json to stdout
  2. -i: neorg-pandoc will read stdin and print a pandoc json to stdout

Errors are thrown on stderr.

An example usage might be:

./neorg-pandoc-linux86 -f testing/test.norg | pandoc -f json -o testing/out.pdf

Here, I have used the neorg-pandoc-linux86 binary to transform my norg file into the pandoc json format. The result is piped into pandoc to create a pdf. The -f json argument tells pandoc that the input is a json file and -o testing/out.pdf is the location of the pdf file. It is also possible to transform your norg file into other formats; for example to markdown by replacing -o testing/out.pdf with -o testing/out.md. For further options refer to the pandoc documentation.

How to Contribute

  1. Fix one of the issues
  2. Find parsing errors and create issues for them using the parsing error template

Testing Pipeline

I have set up a Github Action pipeline which runs the tests for neorg. So you do not need to worry much that you break something, since it will be detected most of the time.

There are two kinds of tests:

  • parser-tests: Small snippets are parsed and the resulting AST is validated
  • norg-markdown-equal-test: Norg and Markdown files are parsed and the resulting Pandoc AST is checked for equality