- Python 100%
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.
March 2025
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
Currently, development of Hyperorg is driven by one individual in their spare time. The infrastructure being used does not incur any costs for this project. Consequently, small donations do not significantly contribute to the project's progress. To financially compensate the developer's time, donations would need to be at a level that is currently not anticipated. Therefore, it is recommended to financially support projects and software that are relevant and essential for the infrastructure and further development of Hyperorg.
- Codeberg for hosting that project. They use Forgejo on their servers and are involved in its development.
- Debian GNU/Linux
- GNU Emacs can indirect be supported via donating to the Free Software Foundation.
- Org-mode
- Org-roam currently accept donations only via Microsoft GitHub Sponsors.
- Regex101.com (see Donate button in the top right)
- Any other project or institution relevant for Free and Open-Source Software (FOSS).
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 |
|---|---|
|
|