changes to README, only renders required menu parts now for faster build time, decreased font-size
This commit is contained in:
Nick Sellen
parent
ae6efdc4a0
commit
8dda4023a5
96
README.md
96
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
|
||||
|
||||
To upload it (assuming your ssh key has been put on the server) you run:
|
||||
It should then be available at [localhost:4000](http://localhost:4000)
|
||||
|
||||
### Import content from drupal
|
||||
|
||||
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… :)
|
||||
|
||||
|
||||
### 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
|
||||
----------------------
|
||||
## 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
|
||||
@ -87,5 +105,29 @@ 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).
|
||||
|
||||
|
||||
|
||||
|
||||
@ -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 %>">
|
||||
<% if entry[:children].any? %>
|
||||
<dl>
|
||||
<%= entry[:children].join %>
|
||||
</dl>
|
||||
<% end %>
|
||||
</dd>
|
||||
HTML
|
||||
|
||||
|
||||
@ -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 @@
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user