changes to README, only renders required menu parts now for faster build time, decreased font-size

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 <repo-url>
     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/<slug>/
 
@@ -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:
     ---
 
     <p>My Actual Content</p>
+    
+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). 
+
 
 
     

_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
                       <a name="<%= entry[:url] %>" href="<%= entry[:url] %>"><%= entry[:menu_title] %></a>
                   </dt>
                   <dd class="<%= css_classes %>">
-                      <dl>
-                          <%= entry[:children].join %> 
-                      </dl>
+                      <% if  entry[:children].any? %>
+                        <dl>
+                            <%= entry[:children].join %> 
+                        </dl>
+                      <% end  %>
                   </dd>
               HTML
 

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 @@
 
 
 
+