repo2html/README.md

repo2html

generates static html pages for browsing the contents of a git repository.

basic usage

repo2html <destination>

run from a git repository, this command populates the directory <destination> with html files that provide a web-browsable view of the contents of repository.

note: changes must be at least committed before they will appear in the html output. more precisely: the html output represents the state of the HEAD commit, not that of the current work-tree.

you may also cause this html directory to be automatically updated upon every git push, by invoking repo2html from a git hook. we describe how to use this technique to build a static git forge.

features

• static html files
• image support
• markdown files are rendered as html
• no resident background process

disclaimer

no one is liable if this software breaks, deletes, corrupts, or ruins anything

requirements

• chicken scheme, and eggs:
  • utf8
  • lowdown
  • sxml-transforms
  • clojurian
• git

installation

this compiles the binary repo2html and place it in /usr/local/bin.

1. ensure you're in the repo2html git repository
2. as root, run make dependencies
3. run make
4. run make install as root

if you wish, you may then uninstall the chicken scheme compiler.

if you prefer, the file main.scm may be used as the repo2html executable instead of compiling a binary file, but it will be slower, and requires that the chicken scheme interpreter remain installed on your system.

how it works

TODO

todos

• documentation: convert a lot of the stuff i (m455) made in the readme into an e2e tutorial
• documenation: scope the readme audience to folks who kind of know what they're doing with servers
• documentation/feature: use post-update rather than post-receive hook for simplicity
• documentation: also describe use with post-commit hook
• feature: multi-page or collapse-able files list
• feature: branches and releases (tags)
• feature: clickable line numbers in source files
• feature: customizable templates
• feature: display binary files as output from binary-file analysis tools like hexdump, xxd, dumpelf, elfls, readelf, etc.?
• feature: syntax highlighting?
• feature: markdown-render git log text

license: agpl-3.0+

Copyright 2022 Jesse Laprade. This software is released under the terms of the GNU Affero General Public License, version 3 or any later version.

alternatives

• stagit
• depp
• git-arr