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 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`. There are no other dependencies.
   8
   9 To generate the site and run it up locally you can do something like:
  10
  11     git clone <repo-url>
  12     cd ardour-manual
  13     ruby export.rb
  14     jekyll --server
  15
  16 To upload it (assuming your ssh key has been put on the server) you run:
  17
  18    ./upload.sh
  19
  20
  21 Strucuture of the content
  22 ----------------------
  23
  24 There are 2 different types of content:
  25 - special manual content
  26 - normal content
  27
  28 Special manual content
  29 ----------------------
  30
  31 This is content that ends up as part of the tree on the left.
  32
  33 The _raw_ content is in `_manual` directory and has a naming convention as follows:
  34
  35     # content for a page at http://manual.ardour.org/<slug>/
  36
  37     <ordering>_<slug>.<html|md|textile>
  38        ^          ^     ^
  39        |          |     |
  40        |          |   extension is removed later
  41        |          |
  42        |     ends up as part of URL
  43        |
  44      only used for ordering
  45
  46
  47     # a folder for subcontent is like this
  48
  49     <ordering>_<slug>/
  50
  51     # more things can then go in here for http://manual.ardour.org/<slug>/<slug2>/
  52
  53     <ordering>_<slug>/<ordering2>_<slug2>.html
  54
  55 So, for example:
  56
  57     this file                  appears at
  58     ------------               ------------
  59
  60     01_main.html               /main/
  61
  62     01_main/01_subpage.html    /main/subpage/
  63
  64
  65 Normal content
  66 ----------------------
  67
  68 This is anything else, css files, images, fixed pages, layouts. This content lives in the `source` directory.
  69
  70
  71 Content processing
  72 ----------------------
  73
  74 Three types of content can have special processing done.
  75
  76 - `.html` files
  77 - `.md` files
  78 - `.textile` files
  79
  80 All special files should also have a special header at the top too:
  81
  82     ---
  83     layout: default
  84     title: Some Very Wordy and Expressive Title
  85     menu_title: Some Title
  86     ---
  87
  88     <p>My Actual Content</p>
  89
  90
  91