rage against web frameworks - posix shell static site generator
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
debian
site
test
.gitignore
CHANGELOG
Makefile
README
config.sh
license.txt
rawk
rawk.1
rawkrc.5
tutorial.txt

README

                                            _                   
               _      _ __  __ _ __      __| | __     _         
              (_)    | '__|/ _` |\ \ /\ / /| |/ /    (_)             
            _  _     | |  | (_| | \ V  V / |   <      _  _ 
           (_)(_)    |_|   \__,_|  \_/\_/  |_|\_\    (_)(_)
                                                                     


.:[ rage against web frameworks! ]:.

rawk: a markdown-based web framework using only unix commandline tools
license: public domain

design goals:
    1. simplicity: very customisable but works nearly straight out of the box
    2. posix-compliant tools: uses only strict posix compliant syntax for the 
    unix command line tools it uses (i.e. sh and sed)
    3. no gui required
    4. lynx-friendly


installation
    1. ./config.sh or PREFIX=${HOME} ./config.sh
    2. make 
    3. make sure a markdown parser is installed / available

    alternatively, on debian systems, install the packages from
    https://apt.kyleisom.net/.

quick notes:
    * rawk looks for rawkrc in the current directory
    * rawk expects at a minimum a path to a tree of markdown files
    * rawk also looks for a second argument which is the output directory
    * if no output directory rawk will use $PWD/$(basename $1).build
    * rawk looks for smu by default as a markdown parser - change as necessary.
      smu is available at http://s01.de/~tox/index.cgi/proj_smu.
    * rawk identifies markdown files by the extension .md

quick start (the way i do it):
    1. create a directory for your site, ex. brokenlcd.net

    2. create a directory inside that to hold the actual site source, i.e. 
    brokenlcd.

    right now, my site directory looks like:

    kyle@sterling [ ~/src ] $ ls
    brokenlcd.net/
    kyle@sterling [ ~/src ] $ ls brokenlcd.net/
    brokenlcd/

    3. copy the sample makefile, templates, and rawkrc from 
    $PREFIX/share/rawk/site to your site directory, i.e.:

    kyle@sterling [ ~/src ] $ ls brokenlcd.net/
    brokenlcd/  templates/      Makefile    rawkrc


    4. edit rawkrc, changing SITE_TITLE and SITE_SUBTITLE to match your site. 
    if you want to use a different markdown interpreter, set MDPARSER 
    appropriately. 

    5. edit the Makefile to rename the SITE and rsync details (for uploading
    the site).

    6. make && make install

customisations
    * the header template should / can contain the following vars:
        ${title}        # site title
        ${subtitle}     # site subtitle
        ${root_link}    # the site root (use in an href)
        ${date}         # unix time stamp (i.e. $(date))
    * you can point rawkrc at your own header / footer templates and stylesheet
    in rawkrc
    * you can change the site root to use for links in the variable SITE_ROOT
    the default is SITE_ROOT="/" so the root links are <a href="/index.html">
    * you are encouraged to tweak the source so it does precisely what you wish
    * setting the variable uname_comment to anything prints the interpreter,
    and `uname -rms` to the body as a comment

links
    $PREFIX/share/rawk/
    http://www.brokenlcd.net/code/rawk.html
    http://www.network-science.de/ascii/     # ASCII art generator