5 This is the project that generates the static ardour manual website available at [manual.ardour.org](http://manual.ardour.org).
7 The site is built using ruby (I use 1.9[.3]) and [liquid](http://liquidmarkup.org/), a ruby gem.
11 git clone <repo-url> ardour-manual
14 ## Structure of the content
16 There are 2 different types of content:
18 - special `_manual` content
21 ### Special `_manual` content
23 This is content that ends up as part of the tree on the left.
25 The _raw_ content is in `_manual/` directory and has a naming convention as follows:
27 # content for a page at http://manual.ardour.org/<slug>/
29 <ordering>_<slug>.<html|md|textile>
32 | | extension is removed later
34 | ends up as part of URL
36 only used for ordering
39 # a folder for subcontent is like this
43 # more things can then go in here for http://manual.ardour.org/<slug>/<slug2>/
45 <ordering>_<slug>/<ordering2>_<slug2>.html
50 | this file | appears at url |
51 |--------------------------------------------------------|
52 | _manual/01_main.html | /main/ |
53 | _manual/01_main/01_subpage.html | /main/subpage/ |
58 This is anything else, css files, images, fixed pages, layouts. This content lives in the `source` directory.
60 If you added `source/images/horse.png` is would be available at the url `/images/horse.png` after publishing it.
62 Content processing is applied to normal content if it has the correct header as described below.
67 Three types of content can have special processing done.
69 - `.html` liquid/HTML files
70 - `.md` markdown files
71 - `.textile` textile files
73 All files to be processed should also have a special header at the top too:
77 title: Some Very Wordy and Expressive Title
78 menu_title: Some Title
81 <p>My Actual Content</p>
83 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`).
87 These are almost normal html, but extended with [Liquid templates](http://liquidmarkup.org/). There are a couple of special tags created for this project.
89 - `{% tree %}` is what shows the manual structure in the left column
90 - `{% children %}` shows the immediate list of children for a page
93 ## More Advanced Stuff
95 You probably don't want or need to do any of this, but here are some
96 notes just in case you decide to anyway.
100 You may want the manual available on a machine that doesn't have constant
101 internet access. You will need `git`, `ruby`, and the ruby gem `liquid` installed.
103 1. Download code and build manual
106 git clone <repo-url> ardour-manual
113 2. open `ardour-manual/_site/index.html` in your favorite web browser
115 If this page doesn't open and function correctly, follow these optional steps to serve up the page with nginx.
117 3. Install [nginx](http://wiki.nginx.org/Install)
118 4. Configure nginx server block in `/etc/nginx/sites-available/default`
123 server_name localhost;
125 root ...path_to_.../ardour-manual/_site;
130 5. Restart nginx server
132 service nginx restart
134 6. The manual will now be available at http://localhost
138 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.
140 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.
144 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.
146 E.g. `02_main/05_more/02_blah.html` after all processing is complete would end up in `_site/main/more/blah/index.html`.
148 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).