| example | feat: Support inline Latex for Math expressions | |
| LICENSES | doc: Add contributing info, improved license and readme | |
| misc | build: Release 0.1.0 | |
| src/hyperorg | feat: Support inline Latex for Math expressions | |
| tests | feat: Support inline Latex for Math expressions | |
| .gitignore | feat: Support inline Latex for Math expressions | |
| CHANGELOG.md | feat: Support inline Latex for Math expressions | |
| CONTRIBUTING.md | doc: Branching model and comparison to similar tools | |
| pyproject.toml | feat: Support inline Latex for Math expressions | |
| README.md | doc: Readme update about donations | |
Hyperorg - An Org to HTML converter
Hyperorg converts files from GNU Emacs's Org Mode and Org-roam into HTML format. The resulted HTML files are intended for serverless local use. The creation of Hyperorg was driven by the experience that there is no known solution available to reliably handle the ID-Links in Org-roam v2 nodes. See the example and read the sections about benefits compared to similar tools and usage for further details.
Status of the project
It is active and in constant development implementing new features and fixing bugs. See milestones about what is coming and the changelog about what has been. Don't hesitate to voice your wishes and opinions by utilizing the issue section.
January 2026
The Team
The initial developer and sole maintainer is buhtz.
Donations are collected via Liberapay and Ko-fi, but going to him as a person, not a specific project, though much of the support also benefits this project.
Technologies & Standards
- Python 3
orgparse- W3C conform HTML5 & CSS
- Semantic Versioning, Common Changelog and Conventional Commits
- REUSE Software and SPDX (ISO/IEC 5962:2021) specifications
Table of contents
- Installation
- Usage
- Benefits compared to similar tools
- How to ask questions, report bugs or suggest new features?
- Donations
- Contributing
- Example
Installation
There are two ways to install this application: For users and for developers contributing to the application's development.
Regular installation for users
See the Releases section or run the following command to install the latest stable release from upstream repository:
$ pipx install https://codeberg.org/buhtz/hyperorg/archive/v0.1.0.zip
If pipx is not available on your system check your GNU/Linux distributions
package repository or install it from PyPi (pip install pipx).
Hyperorg is not yet available in a GNU Linux distribution and there are no plans to release it on PyPi.
Editable installation for developers to contribute
First of all fork/clone/copy the repository to your local machine.
$ git clone https://codeberg.org/hyperorg/buhtzology.git
$ cd hyperorg
Use a virtual environment and the extra [develop].
# Create the environment
$ python3 -m venv .venv
# Activate the environment
$ source .venv/bin/activate
# Install
$ pip3 install --editable .[develop]
When you are finished with your working session, don't forget to deactivate the environment.
$ deactivate
Usage
$ hyperorg ~/orgfolder ~/htmlfolder
This will take all *.org files in the folder ~/orgfolder and store them
converted to HTML in ~/htmlfolder. Open the index.html file in the
output folder to see the result.
These are all available options:
usage: hyperorg [-h] [--hardlinks] [-s] [-v] [-d] [--version] inputdir outputdir
positional arguments:
inputdir Source directory with org-files.
outputdir Destination directory for html-files.
optional arguments:
-h, --help show this help message and exit
--hardlinks Use hardlinks instead of symlinks for images and other attachments in the input directory.
-s, --show Open result in default browser.
-v, --verbose Give detailed information.
-d, --debug Debug output.
--version show program's version number and exit
Benefits compared to similar tools
- Functions out of the box, no configuration needed.
- Operates as a standalone application, eliminating the requirement for Emacs.
- Fairly resilient when dealing with parser issues.
- Fairly resilient managing dead and problematic links which are a common phenomenon when working with a constantly evolving Zettelkasten or personal wiki.
- Generates a comprehensive index of all nodes.
- Adhers to World Wide Web Consortium (W3C) standards for HTML5 and CSS
(
<!DOCTYPE html>).
The reason alternative tools may not meet these criteria could also stem from the author of Hyperorg encountering difficulties in comprehending or managing these functionalities, as well as their documentation. However, this does not necessarily imply that alternative tools do not actually provide these functions.
How to ask questions, report bugs or suggest new features?
The project is in its nascent stage and currently has a modest user base. Any issues, questions, or discussions can be directed to the Issues section. In addition reporting bugs and requesting features, this section accommodates all inquiries and conversations related to the project's development and usage.
Donations
Please see team section.
Contributing
Please see CONTRIBUTING for details about how to contribute to the project.
The following communities have supported this project with contributions to discussions, tips, other valuable contributions and also inspirations.
- The communities around Emacs, Org-roam, Org-mode and ox-hugo.
- Regex101
- StackOverflow
- debianforum.de
Example
On the left side of this screenshot, an Emac's window displaying an Org buffer can be seen, while on the right side, the same content is prestend in HTML format. Example Screenshot
Here you can observe the identical content presented in both raw Org and HTML formats.
| Org | HTML |
|---|---|
|
|