git-site-gen/README.md

git-site-gen

• Tool used to generate a static website from information availble in a git project dir. See: https://spwbk.site/git.

  • Also provides some tools for managing your git server.

• Inspired by the much better/full-featured https://git.suckless.org.

• Not sure if this will be widely useful, mostly written for learning purposes.

Design Goals

• General purpose/easy to use
• Easy to hack/customize
• Small library dependency footprint

Features

DONE:

• Generate top level index with links to all projects
• Generate project specific index with links to git log/diffs and file content of repo
• Extremely basic markdown parser (only supports headings and non nested bullets

TODO:

• Code needs to be more robust / handle failure cases
• Diff highlighting for log
• Line numbers for file browsing
• README.md markdown renderer/parser / display in project index
• (Stretch Goal) HTML based syntax highlighting for files
• Support detection of misconfig of config file

Framework Plans

• gsg -- Perl script to generate the site, uses modules below
• Gsg::Gather.pm -- module to assemble data structures from git trees that need to be obtained as part of generating the site
• Gsg::Html.pm -- probably a bad name, used for writing HTML files and/or editing text in other data structures with html content
• Gsg::MdParse.pm -- module for parsing markdown. Likely a fools errand to be writing this myself but I'd like to try
• Gsg::ConfigParse.pm -- module to parse gsg config, might be overkill to have it's own module
• gsg.config -- Config file that gsg reads to inform behavior (git repos dir, what to include/exclude, etc)

Deps/Compatibility

• Linux only (will probably work on BSD?)
• Shellex.pm ( https://spwbk.site/git/projects/perl-shellex.git/index.html )
• git
• Perl Log4Perl (packaged by most Linux distros)
• Perl GetOpt (packaged by most Linux distros)
• Assumes git directories are suffixed with ".git"

How to use

1. Clone this repo and run the install script ( must have also cloned/installed aforementioned Shellex dep )
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
3. Run ./gsg

Contributions/Issues/Bugs

Reach out to me at via email at pm dot me, spesk@. If it turns out that people actually want to use this I'll move it to another git host that provides more features for a collaborative workflow.

License

GPLv3 - see LICENSE.md