Shamusworld >> Repos - ardour-manual-diverged/blob - 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 [liquid](http://liquidmarkup.org/), a ruby gem.
   8
   9 ### Get the code
  10
  11     git clone <repo-url> ardour-manual
  12     cd ardour-manual
  13
  14 ## Structure of the content
  15
  16 There are 2 different types of content:
  17
  18 - special `_manual` content
  19 - normal content
  20
  21 ### Special `_manual` content
  22
  23 This is content that ends up as part of the tree on the left.
  24
  25 The _raw_ content is in `_manual/` directory and has a naming convention as follows:
  26
  27     # content for a page at http://manual.ardour.org/<slug>/
  28
  29     <ordering>_<slug>.<html|md|textile>
  30        ^          ^     ^
  31        |          |     |
  32        |          |   extension is removed later
  33        |          |
  34        |     ends up as part of URL
  35        |
  36      only used for ordering
  37
  38
  39     # a folder for subcontent is like this
  40
  41     <ordering>_<slug>/
  42
  43     # more things can then go in here for http://manual.ardour.org/<slug>/<slug2>/
  44
  45     <ordering>_<slug>/<ordering2>_<slug2>.html
  46
  47 So, for example:
  48
  49
  50 | this file                        | appears at url      |
  51 |--------------------------------------------------------|
  52 | _manual/01_main.html             | /main/              |
  53 | _manual/01_main/01_subpage.html  | /main/subpage/      |
  54
  55
  56 ### Normal content
  57
  58 This is anything else, css files, images, fixed pages, layouts. This content lives in the `source` directory.
  59
  60 If you added `source/images/horse.png` is would be available at the url `/images/horse.png` after publishing it.
  61
  62 Content processing is applied to normal content if it has the correct header as described below.
  63
  64
  65 ## Content processing
  66
  67 Three types of content can have special processing done.
  68
  69 - `.html` liquid/HTML files
  70 - `.md` markdown files (NOPE!)
  71 - `.textile` textile files (NOPE!)
  72
  73 All files to be processed should also have a special header at the top too:
  74
  75     ---
  76     layout: default
  77     title: Some Very Wordy and Expressive Title
  78     menu_title: Some Title
  79     ---
  80
  81     <p>My Actual Content</p>
  82
  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`).
  84
  85 ### `.html` files
  86
  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.
  88
  89 - `{% tree %}` is what shows the manual structure in the left column
  90 - `{% children %}` shows the immediate list of children for a page
  91
  92
  93 ## More Advanced Stuff
  94
  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.
  97
  98 ### Run it locally
  99
 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.
 102
 103 1. Download code and build manual
 104
 105   ```
 106   git clone <repo-url> ardour-manual
 107   cd ardour-manual
 108   cp -r source _site
 109   ruby ./build.rb
 110   chmod -R a+rx _site
 111   ```
 112
 113 2. open `ardour-manual/_site/index.html` in your favorite web browser
 114
 115   If this page doesn't open and function correctly, follow these optional steps to serve up the page with nginx.
 116   N.B.: Step 2 will *never* work; you *must* install nginx if you want to see it!
 117
 118 3. Install [nginx](http://wiki.nginx.org/Install)
 119 4. Configure nginx server block in `/etc/nginx/sites-available/default`
 120
 121   ```
 122   server {
 123       listen 80;
 124       server_name localhost;
 125
 126       root ...path_to_.../ardour-manual/_site;
 127       index index.html;
 128   }
 129   ```
 130
 131 5. Restart nginx server
 132
 133         service nginx restart
 134
 135 6. The manual will now be available at http://localhost
 136
 137 ### manual.rb plugin
 138
 139 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
 141 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.
 142
 143 ### Clean URLs
 144
 145 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
 147 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
 149 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).
 150
 151 ### New Stuff
 152
 153 The above will have to be revised eventually, but for now, here's what's what:
 154
 155 1. All content lives in master-doc.txt and in include/ .
 156
 157 2. A little C helper program needs to be built and run. To build it, do:
 158
 159         gcc munge.cpp -o munge -lstdc++ -g
 160
 161 3. Run the 'doit' script:
 162
 163         ./doit
 164
 165 4. Now _site/ should contain the correct built site. Have fun! ;-)
 166
 167