diff --git a/README.md b/README.md index 013724e3..22bd080e 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,53 @@ -The Ardour Manual -=================== +# The Ardour Manual -This is the project that generates the static ardour manual website available at http://manual.ardour.org. -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. +This is the project that generates the static ardour manual website available at [manual.ardour.org](http://manual.ardour.org). -To generate the site and run it up locally you can do something like: +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. + +`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). + +### Get the code git clone cd ardour-manual - ruby export.rb + +### Run it locally + +This will generate the final html and start a local webserver. + jekyll --server + +It should then be available at [localhost:4000](http://localhost:4000) + +### Import content from drupal -To upload it (assuming your ssh key has been put on the server) you run: - - ./upload.sh +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. + + ruby import.rb + +It's quite slow… :) -Strucuture of the content ----------------------- +### Upload static site to live server + +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): + + ./upload.sh + +## Strucuture of the content There are 2 different types of content: -- special manual content + +- special `_manual` content - normal content -Special manual 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: +The _raw_ content is in `_manual/` directory and has a naming convention as follows: # content for a page at http://manual.ardour.org// @@ -54,30 +71,31 @@ The _raw_ content is in `_manual` directory and has a naming convention as follo So, for example: - this file appears at - ------------ ------------ - 01_main.html /main/ - - 01_main/01_subpage.html /main/subpage/ +| this file | appears at url | +|--------------------------------------------------------| +| _manual/01_main.html | /main/ | +| _manual/01_main/01_subpage.html | /main/subpage/ | -Normal content ----------------------- +### 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 ----------------------- +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` files -- `.md` files -- `.textile` files +- `.html` liquid/HTML files +- `.md` markdown files +- `.textile` textile files -All special files should also have a special header at the top too: +All files to be processed should also have a special header at the top too: --- layout: default @@ -86,6 +104,30 @@ All special files should also have a special header at the top too: ---

My Actual Content

+ +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](http://liquidmarkup.org/). 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 + +## 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 before letting jekyll do it's normal thing. It's all hooked into the jekyll command so no special actions are required. + +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). + \ No newline at end of file diff --git a/_plugins/manual.rb b/_plugins/manual.rb index cde76c4b..4b43cc63 100644 --- a/_plugins/manual.rb +++ b/_plugins/manual.rb @@ -63,7 +63,7 @@ module Manual end block_given? ? block.call(h) : h - end + end.compact end def self.extract_data(filename) @@ -182,15 +182,19 @@ module Manual url_a = url.split('/').reject(&:empty?) + depth = url_a.length is_current, position, level = *process_hierarchy(current_a, url_a) + # this massively speeds up build time by not including the whole menu tree for each page + next if depth > 1 && current_a[0] != url_a[0] + css_classes = [] css_classes << 'active' if is_current css_classes << position.to_s if position css_classes << "#{position}-#{level}" if position && level css_classes << 'other' unless is_current || position || level - css_classes << "level-#{url_a.length}" + css_classes << "level-#{depth}" css_classes = css_classes.join(' ') if entry[:type] == 'directory' @@ -200,9 +204,11 @@ module Manual <%= entry[:menu_title] %>
-
- <%= entry[:children].join %> -
+ <% if entry[:children].any? %> +
+ <%= entry[:children].join %> +
+ <% end %>
HTML diff --git a/export.rb b/import.rb similarity index 100% rename from export.rb rename to import.rb diff --git a/source/css/app.css b/source/css/app.css index 946cf521..747ecbe3 100644 --- a/source/css/app.css +++ b/source/css/app.css @@ -56,8 +56,8 @@ #content li, #content dt, #content dd { - font-size: 18px; - line-height: 32px; + font-size: 16px; + line-height: 28px; } @@ -102,20 +102,20 @@ #content h2 { margin: 30px 0 20px 0; padding-bottom: 5px; - font-size: 24px; + font-size: 22px; border-bottom: 2px solid #ddd; } #content h3 { margin: 20px 0 10px 0; padding-bottom: 5px; - font-size: 22px; + font-size: 20px; border-bottom: 1px solid #eee; } #content h4 { - font-size: 23px; + font-size: 18px; margin: 20px 0 10px 0; padding-bottom: 10px; border-bottom: 1px solid #eee; @@ -314,3 +314,4 @@ +