brokenlcd's guide to setting up sites with rawk
this is not the only way to do this, it's just how i do it.
step 0: pre-requisites
you need a markdown parser installed. see the readme for the link for smu, the markdown parser i use.
rawk should be installed to your system path. for the sake of this tutorial, we'll assume that rawk is installed in /usr/local (i.e. the script is at /usr/local/bin/rawk). this should be done with the include makefile, which will copy over site templates.
i assume you have a working webserver - i won't cover apache or lighttpd or nginx or whatever web server you're using or how to get dns set up.
step 1: preparing the site
first you should create a project directory. i name mine with the domain name, i.e. rawk.brokenlcd.net. for the same of this document, we'll call this directory $project. now cd $project.
create a directory in $project to contain the site src. we'll call this $site. for example, mkdir rawk_site. you can add a quick $site/index.md to test the site:
echo it works > $site/index.md.
copy over the skeleton files:
cp -r /usr/local/share/rawk/site/* .these files should be in $project. in $project/ you should have $site, Makefile, rawkrc, and templates. in this example,
step 2: initial configuration
- edit the Makefile:
changing SITE to contain the folder $site. for this site it would be SITE=rawk_site.
change RHOST to point to where you will upload the site to. it will be similar to the line in the makefile. make sure you have a trailing slash!
2. edit rawkrc. for now, you just have to edit site_title and site_subtitle.
step 3: set up version control
this step is quite optional but strongly recommended.
you should use whatever version control system you are happy with. i like git, some other good scms are mercurial and fossil.
it is strongly recommended that you only track changes to $site. the makefile will generate $site.build; this should be ignored.
step 4: add content
all the site content goes in $site
all .md files will be converted to .html - index.md -> index.html, about.md -> about.html, etc...
rawk copies everything over to build directory but doesn't touch anything but markdown files. this means anything in $site will be pushed to your site.
when creating links to other pages in your markdown files, be sure to use page.html instead of page.md.
step 5: build and publish
now it's time to use that makefile you edited in step 2.
from inside $project (where the makefile should be), issuing
make siteshould build your site. if you list the directory after the make, you should see a $site.build directory. this contains a static html version of $site.
make installto rsync your site to RHOST.
make cleanto remove the build directory.
step 6: enjoy
your site should be up and running now. you are free to focus on content and not on a framework.
if you run across bugs, would like to contribute patches back, or have ideas for improvement, you can check out the sourcefourge page in the links section of where can i get rawk.