tutorial.txt

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
----------------------
1. you need a markdown parser installed. see the readme for the link for smu,
the markdown parser i use.

2. 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.

3. 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
--------------------------
1. 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. 

2. 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`. 

3. 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
-----------------------------
1. 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
------------------------------
1. this step is quite optional but **strongly** recommended.

2. you should use whatever version control system you are happy with. i like
git, some other good scms are mercurial and fossil.

3. 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
-------------------
1. all the site content goes in $site

2. all .md files will be converted to .html - index.md -> index.html, 
about.md -> about.html, etc...

3. 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.

4. 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
-------------------------
1. now it's time to use that makefile you edited in step 2.

2. from inside $project (where the makefile should be), issuing `make` or
`make site` should 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.

3. `make install` to rsync your site to RHOST.

4. `make clean` to 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".