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](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)
    - [symbol-utils](https://wiki.call-cc.org/eggref/5/symbol-utils)
- 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](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/)
first commit 2022-12-02 16:41:55 -05:00			`# repo2html`

attempt to better conform to m455's styleguide 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!! 2022-12-11 13:20:12 -05:00			`generates static html pages for browsing the contents of a git repository.`
feature: license nav link, optional about nav link 2022-12-09 02:15:03 -05:00
			`## basic usage`

attempt to better conform to m455's styleguide 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!! 2022-12-11 13:20:12 -05:00			`repo2html <destination>`
feature: license nav link, optional about nav link 2022-12-09 02:15:03 -05:00
attempt to better conform to m455's styleguide 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!! 2022-12-11 13:20:12 -05:00			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.
feature: license nav link, optional about nav link 2022-12-09 02:15:03 -05:00
attempt to better conform to m455's styleguide 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!! 2022-12-11 13:20:12 -05:00			`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.
check file existence in source-files-list not cwd added source-files-list to populate-html-template. kindof dislike having so many variables passed to a function but i also kindof dislike global variables; not sure how to make this prettier yet. but this solves the bug i introduced in my last commit where the nav links were broken when used as a githook. 2022-12-09 11:00:07 -05:00
attempt to better conform to m455's styleguide 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!! 2022-12-11 13:20:12 -05:00			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).`
first commit 2022-12-02 16:41:55 -05:00
			`## features`

updated readme - renamed post-receive.sample to post-receive - fixed file permissions on post-receive file 2022-12-04 00:44:52 -05:00			`- static html files`
feature: license nav link, optional about nav link 2022-12-09 02:15:03 -05:00			`- image support`
			`- markdown files are rendered as html`
			`- no resident background process`
first commit 2022-12-02 16:41:55 -05:00
			`## disclaimer`

updated readme - renamed post-receive.sample to post-receive - fixed file permissions on post-receive file 2022-12-04 00:44:52 -05:00			`no one is liable if this software breaks, deletes, corrupts, or ruins anything`
first commit 2022-12-02 16:41:55 -05:00
			`## requirements`

feature: license nav link, optional about nav link 2022-12-09 02:15:03 -05:00			`- [chicken scheme](https://call-cc.org/), and eggs:`
fix md formatting for nested uls 2022-12-09 11:00:08 -05:00			`- [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)`
added new dependency to makefile and readme 2022-12-12 12:37:20 -05:00			`- [symbol-utils](https://wiki.call-cc.org/eggref/5/symbol-utils)`
updated readme - renamed post-receive.sample to post-receive - fixed file permissions on post-receive file 2022-12-04 00:44:52 -05:00			`- git`
docs: updated requirements 2022-12-02 16:54:38 -05:00
simplify main readme by moving "git forge" specifics elsewhere just a suggestion; don't feel obligated to merge. you know technical writing and documentation better than i do! 2022-12-09 11:52:38 -05:00			`### installation`
added a quickstart 2022-12-08 21:20:04 -05:00
simplify main readme by moving "git forge" specifics elsewhere just a suggestion; don't feel obligated to merge. you know technical writing and documentation better than i do! 2022-12-09 11:52:38 -05:00			this compiles the binary `repo2html` and place it in `/usr/local/bin`.
added a quickstart 2022-12-08 21:20:04 -05:00
			`1. ensure you're in the repo2html git repository`
			2. as root, run `make dependencies`
			3. run `make`
simplify main readme by moving "git forge" specifics elsewhere just a suggestion; don't feel obligated to merge. you know technical writing and documentation better than i do! 2022-12-09 11:52:38 -05:00			4. run `make install` as root
added a quickstart 2022-12-08 21:20:04 -05:00
simplify main readme by moving "git forge" specifics elsewhere just a suggestion; don't feel obligated to merge. you know technical writing and documentation better than i do! 2022-12-09 11:52:38 -05:00			`if you wish, you may then uninstall the chicken scheme compiler.`
quick notes and updates added to readme, minor makefile changes 2022-12-07 15:18:27 -05:00
simplify main readme by moving "git forge" specifics elsewhere just a suggestion; don't feel obligated to merge. you know technical writing and documentation better than i do! 2022-12-09 11:52:38 -05:00			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.
first commit 2022-12-02 16:41:55 -05:00
removed some out-of-scope sections 2022-12-06 00:07:43 -05:00			`## how it works`

			`TODO`

first commit 2022-12-02 16:41:55 -05:00			`## todos`

made todos and hopes types more distinguishable from the proceeding phrase 2022-12-08 21:01:31 -05:00			`- 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`
simplify main readme by moving "git forge" specifics elsewhere just a suggestion; don't feel obligated to merge. you know technical writing and documentation better than i do! 2022-12-09 11:52:38 -05:00			`- 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)`
made todos and hopes types more distinguishable from the proceeding phrase 2022-12-08 21:01:31 -05:00			`- feature: clickable line numbers in source files`
simplify main readme by moving "git forge" specifics elsewhere just a suggestion; don't feel obligated to merge. you know technical writing and documentation better than i do! 2022-12-09 11:52:38 -05:00			`- feature: customizable templates`
feature: license nav link, optional about nav link 2022-12-09 02:15:03 -05:00			`- feature: display binary files as output from binary-file analysis tools like hexdump, xxd, dumpelf, elfls, readelf, etc.?`
simplify main readme by moving "git forge" specifics elsewhere just a suggestion; don't feel obligated to merge. you know technical writing and documentation better than i do! 2022-12-09 11:52:38 -05:00			`- feature: syntax highlighting?`
a little footer 2022-12-12 00:31:32 -05:00			`- feature: markdown-render git log text`
feature: license nav link, optional about nav link 2022-12-09 02:15:03 -05:00
			`## 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/)`