a916af24aa
m455, i lost the advice you gave me previously, detailing conventions you'd like to conform to when writing documentation for this project. i tried to make some changes here that conform to what pieces i remember but probably got some of it wrong. would you mind reiterating your recommendations in an email or text file for me? thanks!!
77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# 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](build-a-git-forge.md.html).
|
|
|
|
## 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](https://call-cc.org/), and eggs:
|
|
- [utf8](https://wiki.call-cc.org/eggref/5/utf8)
|
|
- [lowdown](https://wiki.call-cc.org/eggref/5/lowdown)
|
|
- [sxml-transforms](https://wiki.call-cc.org/eggref/5/sxml-transforms)
|
|
- [clojurian](https://wiki.call-cc.org/eggref/5/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?
|
|
- **bug**: markdown-render and/or html-escape git log text
|
|
|
|
## license: agpl-3.0+
|
|
|
|
Copyright 2022 [Jesse Laprade](https://m455.casa).
|
|
This software is released under the terms of the [GNU Affero General Public License](https://www.gnu.org/licenses/agpl.html), version 3 or any later version.
|
|
|
|
## alternatives
|
|
|
|
- [stagit](https://codemadness.org/git/stagit/file/README.html)
|
|
- [depp](https://git.8pit.net/depp.git/)
|
|
- [git-arr](https://blitiri.com.ar/p/git-arr/)
|