README.norg

%If you are reading this document on repo's main page, it means that the parser is not yet nearly complete. ;)%

* norg-pandoc
  Custom pandoc reader for {https://github.com/nvim-neorg/norg-specs}[Norg format].

  > *NOTE*:
    This is WIP project. May not work in some edge cases.

** Usage

   @code bash
   pandoc --from=init.lua # more pandoc options
   @end

*** Example: Convert norg file to markdown file

    This is CI code used in this repo to convert Norg README file to Github-Flavored-Markdown

    @code bash
    pandoc --from=init.lua --to=gfm README.norg --output=README.md
    @end

** why?

   There is already a {https://github.com/Simre1/neorg-haskell-parser}[haskell parser] that tried to implement a native pandoc reader, but the project is stalled. Haskell is good language to make custom parser, but there aren't many people who can use it.

   Many of Neorg's features are already written in Lua, and pandoc has built-in support for Lua custom parsers. This project is started to provide full pandoc support as soon as possible.

** Parser Implementation State

   Currently most parts of Layer1~4 are done. The left parts are:

   - (=) *Tables* : It's really hard to implement as parser
   - (=) *Macros* (including all kinds of Tags) : Waiting for macro support in Norg
   - (=) *Complex Links* (links to other Norg files, etc) : Waiting for standard link resolver module

   You can see detailed implement state in {./todo.norg}[todo.norg]

** Contributing

   All contributions are welcome!

   You can test with {https://github.com/lunarmodules/busted}[busted] or {https://github.com/nvim-neotest/neotest-plenary}[neotest-plenary] before making a PR.

   All test files should be named like: `test/*_spec.lua`.