1 # git-site-gen AKA gsg #
2 * Tool used to generate a bare bones, pure HTML static website from information availble in a git project dir. See: <https://spwbk.site/git>.
3 * Inspired by the much better/full-featured cgit.
4 * See gsgd for git hooks based calls to gsgd: <https://spwbk.site/git/projects/gsgd.git/index.html>
5 * Not sure if this will be widely useful, mostly written for learning purposes.
6
7 ## Design Goals ##
8 * General purpose/easy to use
9 * Easy to hack/customize
10 * Small library dependency footprint
11
12 ## Features ##
13 DONE:
14 * Generate top level index with links to all projects
15 * Generate project specific index with links to git log/diffs and file content of repo
16 * Extremely basic markdown parser (only supports headings, non nested bullets, backticks code blocks, links and strikethru)
17 * Line numbers for file browsing
18 * Diff highlighting for log
19 * Show git:// address for cloning (configurable via config file)
20 * Support detection of misconfig of config file (pretty basic at this stage)
21 * Detects binary files
22 * Show last time site was generated in top level index
23 * Links to view raw files (cannot be used with cURL as pages are rendered as HTML)
24
25 TODO:
26 * User-agent detection for `curl http://link | bash` use cases (stretch)
27 * Code needs to be more robust / handle failure cases
28 * Need to recurse git home, right now will only pull dirs in root of git home
29 * README.md markdown renderer/parser / display in project index (Partially implemented)
30 * HTML based syntax highlighting for files
31 * File history
32 * Display/browse branches
33 * More efficient/faster detection of binary files
34
35 ## Layout ##
36 * gsg -- Perl script to generate the site, uses modules below
37 * Gsg::Gather.pm -- module to assemble data structures from git trees that need to be obtained as part of generating the site
38 * Gsg::Html.pm -- probably a bad name, used for writing HTML files and/or editing text in other data structures with html content
39 * Gsg::MdParse.pm -- module for parsing markdown. Likely a fools errand to be writing this myself but I'd like to try
40 * Gsg::ConfigParse.pm -- module to parse gsg config, might be overkill to have it's own module
41 * gsg.config -- Config file that gsg reads to inform behavior (git repos dir, what to include/exclude, etc)
42
43 ## Deps/Compatibility ##
44 * Linux only (will probably work on BSD?)
45 * Shellex.pm ( <https://spwbk.site/git/projects/perl-shellex.git/index.html> )
46 * git
47 * Perl Log4Perl (packaged by most Linux distros)
48 * Assumes git directories are suffixed with ".git"
49
50 ## How to use ##
51 1. Clone this repo and run the install script ( must have also cloned/installed aforementioned Shellex dep )
52 2. Edit the config file with your desired params or create one and pass it in with `gsg --config-file $path_to_config` , delete any that you are not using
53 3. Run ./gsg
54
55 ## Contributions/Issues/Bugs ##
56 Reach out to me at via email at pm dot me, spesk@.
57 If it turns out that people actually want to use this I'll move it to another git host
58 that provides more features for a collaborative workflow.
59
60 ## License ##
61 GPLv3 - see LICENSE.md