[[https://github.com/cnglen/windancer/actions/workflows/ci.yml][https://github.com/cnglen/windancer/actions/workflows/ci.yml/badge.svg?branch=main]]

A toolkit for *parsing* and *rendering* [[http://orgmode.org/][orgmode]] built entirely in [[https://rust-lang.org/][Rust]]. | [[file:README_zh.org][中文]]

[[file:docs/windancer_demo.gif]]

See [[https://www.youtube.com/watch?v=ycmglF9i1R8][the ~50 seconds video]] for SSG output.

* Features

- A pure /RUST/ org-mode *parser* following [[https://orgmode.org/worg/org-syntax.html][Org Syntax specification]].
- A static site generator(*SSG*) that turns a directory of org files into a complete HTML website.
  - Optinal *anonymous discussion* is provided via [[https://github.com/cnglen/tinydis][tinydis]]
- Single binary: easy to isntall and run on Linux and Windows.


** Todo

- [-] better documenation
- [ ] themes customization
- [ ] search by keyword
- [ ] org-roam for knowledge

  

* Usage

** Quick start

Please see the detailed [[#installation][installation instructions for your platform]].

With ~windancer~ installed, a static site can be generated from the input directory. The following example use [[https://github.com/cnglen/windancer/tree/main/examples/blog/note][examples/blog/note]] as input directory, which has the following structure:

#+begin_src plain
examples/blog/                   <-- root directory, which contains the INPUT DIRECTORY and an optional static/templates directory
├── config.toml
├── note                         <-- INPUT DIRECTORY which contains org-mode files
│   ├── editor
│   │   ├── emacs.org
│   │   └── vi.org
│   ├── life
│   │   ├── life.org             <-- the same name as the parent directory, will generate index.html
│   │   ├── music.org
│   │   ├── running.org
│   │   └── todo.org
│   └── note.org                 <-- the same name as the parent directory, will generate index.html
├── static                       <-- optional 
│   └── robots.txt
└── templates                    <-- optional
    └── site_footer.tera.html
#+end_src

Let's build the static site:

#+begin_src bash
windancer -i examples/blog/note/ -o /tmp/blog.site  
#+end_src

The following output directory will be generated, which can be served by one HTTP server, e.g, =python -m http.server -d /tmp/blog.site=

#+begin_src plain
/tmp/blog.site                   <-- root directory, which has the matched structure of the INPUT directory
├── default.css
├── editor
│   ├── emacs.html
│   └── vi.html
├── encre.css
├── index.htlm                   <-- from note.org
├── life
│   ├── index.html               <-- from life.org
│   ├── music.html
│   ├── running.html
│   └── todo.html
└── robots.txt
#+end_src


** Installation
:PROPERTIES:
:CUSTOM_ID: installation
:END:

Pre-built binaries for Linux and Windows are provided on the [[https://github.com/cnglen/windancer/releases][Github release page]].

*** From source

To build from source, [[https://rust-lang.org/][Rust and Cargo]] need to be installed. Then, from
a terminal, you can run the following commands to install the ~windancer~
binary into =~/.cargo/bin/=. It will take about 5 minutes.

#+begin_src bash
  cargo install --locked --git https://github.com/cnglen/windancer
  windancer --version
#+end_src


** Configuration

See [[file:examples/blog/note/][note]] and [[https://github.com/cnglen/windancer/blob/main/config/default.toml][default.toml]]


* FAQ

** Q: Are all org-mode syntax supported?

See [[file:docs/status.org][status]]

** Q: Why implement org-mode parsing in Rust?

Emacs comes with built-in org-mode support, including its own parser. However, customization or exporting to other tools can be cumbersome. Since I’m not familiar with Emacs Lisp, I chose to implement the parsing logic in Rust instead.

There are plenty of SSG tools for Markdown, but native org-mode support is rare. The usual approach is to convert org-mode to Markdown, but this often yields imperfect output.

That’s why windancer is created—to parse org-mode directly and render it as an HTML site. Pdf book/slide export may be added in the future.


* Contribute

Building an org-mode parser and renderer is a lengthy process, as every syntactic construct needs to be implemented and tested. I've already devoted more than half a year to it, and I'm still at it—often working late into the night ...

If you find windancer helpful in your development work, you can donate to support my development work. Any amount is welcome, even if it's just a cola.

You can support my work on [[https://ko-fi.com/cnglen][ko-fi]]. After donating, your nickname and message will be displayed on the [[file:docs/donor.org][donor list]].

Another way to help is to report bugs, or suggest new features in [[https://github.com/cnglen/windancer/issues][issues]]