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 [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 ## Structure of the content
  17
  18 There are 2 different types of content:
  19
  20 - special `_manual` content
  21 - normal content
  22
  23 ### Special `_manual` content
  24
  25 This is content that ends up as part of the tree on the left.
  26
  27 The _raw_ content is in `_manual/` directory and has a naming convention as follows:
  28
  29     # content for a page at http://manual.ardour.org/<slug>/
  30
  31     <ordering>_<slug>.<html|md|textile>
  32        ^          ^     ^
  33        |          |     |
  34        |          |   extension is removed later
  35        |          |
  36        |     ends up as part of URL
  37        |
  38      only used for ordering
  39
  40
  41     # a folder for subcontent is like this
  42
  43     <ordering>_<slug>/
  44
  45     # more things can then go in here for http://manual.ardour.org/<slug>/<slug2>/
  46
  47     <ordering>_<slug>/<ordering2>_<slug2>.html
  48
  49 So, for example:
  50
  51
  52 | this file                        | appears at url      |
  53 |--------------------------------------------------------|
  54 | _manual/01_main.html             | /main/              |
  55 | _manual/01_main/01_subpage.html  | /main/subpage/      |
  56
  57
  58 ### Normal content
  59
  60 This is anything else, css files, images, fixed pages, layouts. This content lives in the `source` directory.
  61
  62 If you added `source/images/horse.png` is would be available at the url `/images/horse.png` after publishing it.
  63
  64 Content processing is applied to normal content if it has the correct header as described below.
  65
  66
  67 ## Content processing
  68
  69 Three types of content can have special processing done.
  70
  71 - `.html` liquid/HTML files
  72 - `.md` markdown files
  73 - `.textile` textile files
  74
  75 All files to be processed should also have a special header at the top too:
  76
  77     ---
  78     layout: default
  79     title: Some Very Wordy and Expressive Title
  80     menu_title: Some Title
  81     ---
  82
  83     <p>My Actual Content</p>
  84
  85 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`).
  86
  87 ### `.html` files
  88
  89 These are almost normal html, but extended with [Liquid templates](http://liquidmarkup.org/). There are a couple of special tags created for this project.
  90
  91 - `{% tree %}` is what shows the manual structure in the left column
  92 - `{% children %}` shows the immediate list of children for a page
  93
  94
  95 ## More Advanced Stuff
  96
  97 You probably don't want or need to do any of this, but here are some
  98 notes just in case you decide to anyway.
  99
 100 ### Run it locally
 101
 102 This will generate the final html and start a local webserver.
 103
 104     jekyll --server
 105
 106 It should then be available at [localhost:4000](http://localhost:4000)
 107
 108 ### Import content from drupal
 109
 110 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.
 111
 112     ruby import.rb
 113
 114 It's quite slow… :)
 115
 116
 117 ### Upload static site to live server
 118
 119 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):
 120
 121     ./upload.sh
 122
 123 ### manual.rb plugin
 124
 125 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.
 126
 127 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.
 128
 129 ### Clean URLs
 130
 131 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.
 132
 133 E.g. `02_main/05_more/02_blah.html` after all processing is complete would end up in `_site/main/more/blah/index.html`.
 134
 135 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).
 136
 137
 138
 139