org2html - An Org-Mode files converter for cgit

The org2html script brings support for Org-Mode formatted about files to cgit. For more informations on cgit’s about filters, see the cgitrc(5) manual.

Installation

Dependencies

The script depends on the sha256sum command and Emacs 28+ (the true minimum version depends on the minimum version needed for your Org files).

No Emacs configuration is needed (the script uses Emacs’ -Q flag anyway). Should yould need to execute code blocks before export, use local variables to set org-confirm-babel-evaluate to nil:

# ...
# At the end of the document (those *must* be the last lines)

* COMMENT Local Variables
Local Variables:
org-confirm-babel-evaluate: nil
End:

No, the script does not set this variable to nil on export, and you should not modify it to do so. This behavior is utterly unsafe, and thus will not be implemented.

Install procedure

To install, clone the repo:

git clone https://github.com/amartos/cgit-org2html org2html

Then modify the about-filter script to use org2html for Org files.

The modifications of cgit’s about-formatting.sh would be (substitute the script’s path for the real one):

 #...
 case "${EXTENSION}" in
+    .org) path/to/org2html; ;;
     #...
 esac

To also render tree’s blobs in CGit, see this gist.

Output

Conversion

The script only outputs the body of the converted HTML files, thus ignores any #+HTML_HEAD and similar attributes affecting other parts of the HTML file than the body itself.

Page conversion/load speed

The first time you visit the about page, and every time the corresponding file changes, the conversion may take some time (at least a few seconds) depending on your system. Org-Mode is indeed a huge library to load, even alone, and the document compilation may take additional time.

As a workaround, the script uses a cache system (hence the sha256sum dependency) to improve speed for each visit after the last compilation – if the file did not change in the meantime. The cache files are located at $CGIT_CACHE/org2html.

CSS support

The CSS defaults are listed in the css/org2html.css file (scss files are available if you want to easily modify it).

The script locates the CSS file at $CGIT_APPDIR/css/org2html.css as a default. To change the path, you can set either the CGIT_APPDIR variable to point to the rootdir of the application, or ORG2HTML_CSS_PATH to lead directly to the CSS file’s real path.

The code and example blocks use the lang lang-NAME classes (NAME being the language identifier), allowing the use of syntax-highlighting libraries as prism or highlight.js.

Roadmap

[X] support for Org about pages rendering
[X] generate default CSS through SCSS
[X] better cache handling for edge cases
[X] better handle syntax highlighting
[ ] use more and better SCSS variables and less hardcoded CSS values
[ ] define better CSS defaults
[ ] handle org files not designed for HTML export (eg. designed for heavy LaTeX uses)

amartos / cgit-org2html