_layouts | ||
_manual | ||
source | ||
_config.yml | ||
.gitignore | ||
build.rb | ||
import.rb | ||
README.md | ||
STYLE_GUIDE | ||
upload.sh |
The Ardour Manual
This is the project that generates the static ardour manual website available at manual.ardour.org.
The site is built using ruby (I use 1.9[.3]) and liquid, a ruby gem.
Get the code
git clone <repo-url> ardour-manual
cd ardour-manual
Structure of the content
There are 2 different types of content:
- special
_manual
content - normal 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:
# content for a page at http://manual.ardour.org/<slug>/
<ordering>_<slug>.<html|md|textile>
^ ^ ^
| | |
| | extension is removed later
| |
| ends up as part of URL
|
only used for ordering
# a folder for subcontent is like this
<ordering>_<slug>/
# more things can then go in here for http://manual.ardour.org/<slug>/<slug2>/
<ordering>_<slug>/<ordering2>_<slug2>.html
So, for example:
| this file | appears at url | |--------------------------------------------------------| | _manual/01_main.html | /main/ | | _manual/01_main/01_subpage.html | /main/subpage/ |
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
Three types of content can have special processing done.
.html
liquid/HTML files.md
markdown files.textile
textile files
All files to be processed should also have a special header at the top too:
---
layout: default
title: Some Very Wordy and Expressive Title
menu_title: Some Title
---
<p>My Actual Content</p>
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. 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.
- Download code and build manual
git clone <repo-url> ardour-manual
cd ardour-manual
cp -r source _site
ruby ./build.rb
chmod -R a+rx _site
- 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.
- Install nginx
- 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;
}
-
Restart nginx server
service nginx restart
-
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).