X-Git-Url: http://shamusworld.gotdns.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=README.md;h=dadce20797258e5265483636324640963430f53f;hb=26d592b95119669e5121a4f34862ded1e9a6915e;hp=013724e38bdc31b1110088b20349cf53c15e8142;hpb=ae6efdc4a0dd1825a30a1b95b70d6a5f799713a9;p=ardour-manual-diverged diff --git a/README.md b/README.md index 013724e..dadce20 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,28 @@ -The Ardour Manual -=================== +# The Ardour Manual -This is the project that generates the static ardour manual website available at http://manual.ardour.org. -The site is built using ruby (I use 1.9.3) and [Jekyll]](https://github.com/mojombo/jekyll) (a ruby gem). You should be able to just install ruby and then `gem install jekyll`. There are no other dependencies. +This is the project that generates the static ardour manual website available at [manual.ardour.org](http://manual.ardour.org). -To generate the site and run it up locally you can do something like: +The site is built using ruby (I use 1.9[.3]) and [liquid](http://liquidmarkup.org/), a ruby gem. - git clone - cd ardour-manual - ruby export.rb - jekyll --server - -To upload it (assuming your ssh key has been put on the server) you run: - - ./upload.sh +### Get the code + git clone ardour-manual + cd ardour-manual -Strucuture of the content ----------------------- +## Structure of the content There are 2 different types of content: -- special manual content + +- special `_manual` content - normal content -Special manual content ----------------------- +### Special `_manual` content This is content that ends up as part of the tree on the left. -The _raw_ content is in `_manual` directory and has a naming convention as follows: +The _raw_ content is in `_manual/` directory and has a naming convention as follows: # content for a page at http://manual.ardour.org// @@ -38,7 +30,7 @@ The _raw_ content is in `_manual` directory and has a naming convention as follo ^ ^ ^ | | | | | extension is removed later - | | + | | | ends up as part of URL | only used for ordering @@ -54,30 +46,31 @@ The _raw_ content is in `_manual` directory and has a naming convention as follo So, for example: - this file appears at - ------------ ------------ - 01_main.html /main/ +| this file | appears at url | +|--------------------------------------------------------| +| _manual/01_main.html | /main/ | +| _manual/01_main/01_subpage.html | /main/subpage/ | - 01_main/01_subpage.html /main/subpage/ - -Normal content ----------------------- +### Normal content This is anything else, css files, images, fixed pages, layouts. This content lives in the `source` directory. +If you added `source/images/horse.png` is would be available at the url `/images/horse.png` after publishing it. + +Content processing is applied to normal content if it has the correct header as described below. -Content processing ----------------------- + +## Content processing Three types of content can have special processing done. -- `.html` files -- `.md` files -- `.textile` files +- `.html` liquid/HTML files +- `.md` markdown files +- `.textile` textile files -All special files should also have a special header at the top too: +All files to be processed should also have a special header at the top too: --- layout: default @@ -87,5 +80,73 @@ All special files should also have a special header at the top too:

My Actual Content

+The `title` field will end up as an `h1` in the right panel. The `menu_title` is what is used in the menu tree on the left (if not preset it will default to using `title`). + +### `.html` files + +These are almost normal html, but extended with [Liquid templates](http://liquidmarkup.org/). There are a couple of special tags created for this project. + +- `{% tree %}` is what shows the manual structure in the left column +- `{% children %}` shows the immediate list of children for a page + + +## More Advanced Stuff + +You probably don't want or need to do any of this, but here are some +notes just in case you decide to anyway. + +### Run it locally + +You may want the manual available on a machine that doesn't have constant +internet access. You will need `git`, `ruby`, and the ruby gem `liquid` installed. + +1. Download code and build manual + + ``` + git clone ardour-manual + cd ardour-manual + cp -r source _site + ruby ./build.rb + chmod -R a+rx _site + ``` + +2. open `ardour-manual/_site/index.html` in your favorite web browser + + If this page doesn't open and function correctly, follow these optional steps to serve up the page with nginx. + +3. Install [nginx](http://wiki.nginx.org/Install) +4. Configure nginx server block in `/etc/nginx/sites-available/default` + + ``` + server { + listen 80; + server_name localhost; + + root ...path_to_.../ardour-manual/_site; + index index.html; + } + ``` + +5. Restart nginx server + + service nginx restart + +6. The manual will now be available at http://localhost + +### manual.rb plugin + +Much of the functionality comes from `_plugins/manual.rb` - it takes the _manual format_ (contained in `_manual/`) and mushes it around a bit into a tmp directory. + +This is to enable the directory tree to be understood, child page lists to be constructed, clean URLs, and the correct ordering of pages maintained. + +### Clean URLs + +To allow the clean URLs (no `.html` extension) _and_ to support simple hosting (no `.htaccess` or apache configuration required) each page ends up in it's own directory with an `index.html` page for the content. + +E.g. `02_main/05_more/02_blah.html` after all processing is complete would end up in `_site/main/more/blah/index.html`. + +The page format contained in the `_manual/` directory is different to the final rendered output (see special `_manual` content above) to make it simple to create content (you don't need to think about the `index.html` files). + + + - \ No newline at end of file