]> Shamusworld >> Repos - ardour-manual/blob - README.md
changes to README, only renders required menu parts now for faster build time, decrea...
[ardour-manual] / README.md
1
2 # The Ardour Manual
3
4
5 This is the project that generates the static ardour manual website available at [manual.ardour.org](http://manual.ardour.org).
6
7 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` to get it up and running.
8
9 `import.rb` (which gets the content from drupal) requires the `nokogiri` gem, but there are no other dependencies for the jekyll part (just the things required by jekyll itself).
10
11 ### Get the code
12
13     git clone <repo-url>
14     cd ardour-manual
15     
16 ### Run it locally
17
18 This will generate the final html and start a local webserver.
19
20     jekyll --server
21     
22 It should then be available at [localhost:4000](http://localhost:4000)
23     
24 ### Import content from drupal
25
26 This will pull the content from the [ardour drupal manual](http://ardour.org/manual/ardour3) and turn it into the format used in `_manual/`. You shouldn't really need to run this.
27     
28     ruby import.rb
29     
30 It's quite slow… :)
31
32
33 ### Upload static site to live server
34
35 Once the content has been built (using jekyll) you can put it live with this (assuming your ssh key has been put on the server):
36
37     ./upload.sh
38
39 ## Strucuture of the content
40
41 There are 2 different types of content:
42
43 - special `_manual` content
44 - normal content
45
46 ### Special `_manual` content
47
48 This is content that ends up as part of the tree on the left.
49
50 The _raw_ content is in `_manual/` directory and has a naming convention as follows:
51
52     # content for a page at http://manual.ardour.org/<slug>/
53
54     <ordering>_<slug>.<html|md|textile>
55        ^          ^     ^
56        |          |     |
57        |          |   extension is removed later
58        |          |        
59        |     ends up as part of URL
60        |
61      only used for ordering
62
63
64     # a folder for subcontent is like this
65
66     <ordering>_<slug>/
67
68     # more things can then go in here for http://manual.ardour.org/<slug>/<slug2>/
69
70     <ordering>_<slug>/<ordering2>_<slug2>.html
71
72 So, for example:
73
74
75 | this file                        | appears at url      |
76 |--------------------------------------------------------|
77 | _manual/01_main.html             | /main/              |
78 | _manual/01_main/01_subpage.html  | /main/subpage/      |
79
80
81 ### Normal content
82
83 This is anything else, css files, images, fixed pages, layouts. This content lives in the `source` directory.
84
85 If you added `source/images/horse.png` is would be available at the url `/images/horse.png` after publishing it.
86
87 Content processing is applied to normal content if it has the correct header as described below.
88
89
90 ## Content processing
91
92 Three types of content can have special processing done.
93
94 - `.html` liquid/HTML files
95 - `.md` markdown files
96 - `.textile` textile files
97
98 All files to be processed should also have a special header at the top too:
99
100     ---
101     layout: default
102     title: Some Very Wordy and Expressive Title
103     menu_title: Some Title
104     ---
105
106     <p>My Actual Content</p>
107     
108 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`).
109     
110 ### `.html` files
111
112 These are almost normal html, but extended with [Liquid templates](http://liquidmarkup.org/). There are a couple of special tags created for this project.
113
114 - `{% tree %}` is what shows the manual structure in the left column
115 - `{% children %}` shows the immediate list of children for a page
116
117 ## manual.rb plugin
118
119 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 before letting jekyll do it's normal thing. It's all hooked into the jekyll command so no special actions are required.
120
121 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.
122
123 ### Clean URLs
124
125 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.
126
127 E.g. `02_main/05_more/02_blah.html` after all processing is complete would end up in `_site/main/more/blah/index.html`.
128
129 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). 
130
131
132
133