kisom / rawk Goto Github PK

                                            _                   
               _      _ __  __ _ __      __| | __     _         
              (_)    | '__|/ _` |\ \ /\ / /| |/ /    (_)             
            _  _     | |  | (_| | \ 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