Skip to content

Commit 0455ee7

Browse files
DvogonenDvogonen
committed
A slight modification of the web site.
1 parent d9175d1 commit 0455ee7

File tree

151 files changed

+12907
-8987
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

151 files changed

+12907
-8987
lines changed

‎README.md

+62
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# Maintaining the openTX Web
2+
The openTX web is published and maintained using Jekyll-Bootstrap.
3+
Maintaining it is done primarily be editing markdown wiki pages and issuing Bootstrap commands.
4+
5+
## What is Jekyll-Bootstrap?
6+
Jekyll is the default page parsing and serving engine of Github. Files checked into the opentx.github.io git repository are checked out by Jekyll and parsed into _static_ web pages. These are then served as part of the opentx web.
7+
The advantage of using Jekyll is that some advanced features like comment fields can be maintained without the need of maintaining active web code or a database. The downside is that the format is somewhat limited.
8+
9+
Bootstrap is a layer on top of Jekyll which adds some maintainance features. The result of using Bootstrap is owever always Jekyll formatted pages.
10+
11+
Jekyll-Bootstrap was made for maintaining blogs, which is not really what the openTX website is. The result is that some of the Bootstrap theming mechanism has been bypassed. Do not switch Bootstrap theme! That would break the site.
12+
13+
## Fetch the site
14+
In order to maintain the site, you need to clone the opentx.github.io repository.
15+
Make the changes locally and commit and push them back when you are done.
16+
It is a good idea to install Jekyll-Bootstrap on your local machine, so that you can test the changes.
17+
18+
## Adding a Post
19+
In order to keep the site feeling alive it is important to add information about changes to the site. This information may be regarding a new release, added documentation, site updates etc. The standard way to add information is to create a blog post.
20+
We have chosen to organize the posts by tagging them as either Documents, News or Releases.
21+
Documents and Releases post should contain a link to a document or release as well as some descriptive information .
22+
Create a post by issuing the following ruby command in the root directory of the site:
23+
```text
24+
rake post title="XXX" tags=[XXX]
25+
```
26+
This creates an empty blog post file with all the default formatting of the site in place. In addition to the title, the post is marked with a date.
27+
You will find your new post in the _posts subdirectory. It is possible to update the date. To change the title of the post you have to edit the title variable inside the document.
28+
I you do not like to use Ruby commands, you can insted copy end edit an existing post. Be very carefull about the so called YAML code at the strat of the post. It has to be correct for the Jekyll parser to work. To add a post it is enough to add a file in the _post directory, everything else is automatic.
29+
The post is in wiki markdown format.
30+
Edit the post file to add some content.
31+
Test your changes and commit+push the new files to the remote repository.
32+
The publication is now done automatically by github!
33+
34+
### Make a OpenTX Companion Release Post
35+
All binaries are hosted on googlecode, rather than on github. The reason is that googlecode has better online editing tools, which makes it easier for non-developers to contribute. You find the googlecode repository [here](https://code.google.com/p/opentx/downloads).
36+
Start by adding the file to the OpenTX googlecode repository.
37+
Then add a post in the following format.
38+
```text
39+
rake post title="OpenTX Companion vX.X" tags=[Releases]
40+
```
41+
The post should contain information about what is new in the release and a link to the binary file.
42+
43+
### Make an OpenTX Release Post
44+
OpenTX firmware is available thrugh OpenTX Companion and the binaries are typically not available for download. This means that the release post needs only to contain information about what is new in the release.
45+
```text
46+
rake post title="OpenTX vX.X" tags=[Releases]
47+
```
48+
The post should contain information about what is new in the release.
49+
50+
### Add a Document Post
51+
All binary documents are hosted on googlecode, rather than on github. The reason is that googlecode has better online editing tools, which makes it easier for non-developers to contribute. You find the googlecode repository [here](https://code.google.com/p/opentx/downloads).
52+
Start by adding the document to the OpenTX googlecode repository.
53+
Then add a post in the following format.
54+
```text
55+
rake post title="Document Title" tags=[Documents]
56+
```
57+
The post should contain relevant document information and a link to the document.
58+
59+
## Jekyll-Bootstrap Documentation and help.
60+
For all JekyllBootstrap documentation please see: <http://jekyllbootstrap.com>
61+
The documentation website at <http://jekyllbootstrap.com> is maintained at https://github.com/plusjade/jekyllbootstrap.com
62+
Jekyll-Bootstrap License: [MIT](http://opensource.org/licenses/MIT)

‎Rakefile

+310
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
require "rubygems"
2+
require 'rake'
3+
require 'yaml'
4+
require 'time'
5+
6+
SOURCE = "."
7+
CONFIG = {
8+
'version' => "0.3.0",
9+
'themes' => File.join(SOURCE, "_includes", "themes"),
10+
'layouts' => File.join(SOURCE, "_layouts"),
11+
'posts' => File.join(SOURCE, "_posts"),
12+
'post_ext' => "md",
13+
'theme_package_version' => "0.1.0"
14+
}
15+
16+
# Path configuration helper
17+
module JB
18+
class Path
19+
SOURCE = "."
20+
Paths = {
21+
:layouts => "_layouts",
22+
:themes => "_includes/themes",
23+
:theme_assets => "assets/themes",
24+
:theme_packages => "_theme_packages",
25+
:posts => "_posts"
26+
}
27+
28+
def self.base
29+
SOURCE
30+
end
31+
32+
# build a path relative to configured path settings.
33+
def self.build(path, opts = {})
34+
opts[:root] ||= SOURCE
35+
path = "#{opts[:root]}/#{Paths[path.to_sym]}/#{opts[:node]}".split("/")
36+
path.compact!
37+
File.__send__ :join, path
38+
end
39+
40+
end #Path
41+
end #JB
42+
43+
# Usage: rake post title="A Title" [date="2012-02-09"] [tags=[tag1,tag2]] [category="category"]
44+
desc "Begin a new post in #{CONFIG['posts']}"
45+
task :post do
46+
abort("rake aborted: '#{CONFIG['posts']}' directory not found.") unless FileTest.directory?(CONFIG['posts'])
47+
title = ENV["title"] || "new-post"
48+
tags = ENV["tags"] || "[]"
49+
category = ENV["category"] || ""
50+
slug = title.downcase.strip.gsub(' ', '-').gsub(/[^\w-]/, '')
51+
begin
52+
date = (ENV['date'] ? Time.parse(ENV['date']) : Time.now).strftime('%Y-%m-%d')
53+
rescue => e
54+
puts "Error - date format must be YYYY-MM-DD, please check you typed it correctly!"
55+
exit -1
56+
end
57+
filename = File.join(CONFIG['posts'], "#{date}-#{slug}.#{CONFIG['post_ext']}")
58+
if File.exist?(filename)
59+
abort("rake aborted!") if ask("#{filename} already exists. Do you want to overwrite?", ['y', 'n']) == 'n'
60+
end
61+
62+
puts "Creating new post: #{filename}"
63+
open(filename, 'w') do |post|
64+
post.puts "---"
65+
post.puts "layout: post"
66+
post.puts "title: \"#{title.gsub(/-/,' ')}\""
67+
post.puts 'description: ""'
68+
post.puts "category: \"#{category.gsub(/-/,' ')}\""
69+
post.puts "tags: #{tags}"
70+
post.puts "---"
71+
post.puts "{% include JB/setup %}"
72+
end
73+
end # task :post
74+
75+
# Usage: rake page name="about.html"
76+
# You can also specify a sub-directory path.
77+
# If you don't specify a file extention we create an index.html at the path specified
78+
desc "Create a new page."
79+
task :page do
80+
name = ENV["name"] || "new-page.md"
81+
filename = File.join(SOURCE, "#{name}")
82+
filename = File.join(filename, "index.html") if File.extname(filename) == ""
83+
title = File.basename(filename, File.extname(filename)).gsub(/[\W\_]/, " ").gsub(/\b\w/){$&.upcase}
84+
if File.exist?(filename)
85+
abort("rake aborted!") if ask("#{filename} already exists. Do you want to overwrite?", ['y', 'n']) == 'n'
86+
end
87+
88+
mkdir_p File.dirname(filename)
89+
puts "Creating new page: #{filename}"
90+
open(filename, 'w') do |post|
91+
post.puts "---"
92+
post.puts "layout: page"
93+
post.puts "title: \"#{title}\""
94+
post.puts 'description: ""'
95+
post.puts "---"
96+
post.puts "{% include JB/setup %}"
97+
end
98+
end # task :page
99+
100+
desc "Launch preview environment"
101+
task :preview do
102+
system "jekyll serve -w"
103+
end # task :preview
104+
105+
# Public: Alias - Maintains backwards compatability for theme switching.
106+
task :switch_theme => "theme:switch"
107+
108+
namespace :theme do
109+
110+
# Public: Switch from one theme to another for your blog.
111+
#
112+
# name - String, Required. name of the theme you want to switch to.
113+
# The theme must be installed into your JB framework.
114+
#
115+
# Examples
116+
#
117+
# rake theme:switch name="the-program"
118+
#
119+
# Returns Success/failure messages.
120+
desc "Switch between Jekyll-bootstrap themes."
121+
task :switch do
122+
theme_name = ENV["name"].to_s
123+
theme_path = File.join(CONFIG['themes'], theme_name)
124+
settings_file = File.join(theme_path, "settings.yml")
125+
non_layout_files = ["settings.yml"]
126+
127+
abort("rake aborted: name cannot be blank") if theme_name.empty?
128+
abort("rake aborted: '#{theme_path}' directory not found.") unless FileTest.directory?(theme_path)
129+
abort("rake aborted: '#{CONFIG['layouts']}' directory not found.") unless FileTest.directory?(CONFIG['layouts'])
130+
131+
Dir.glob("#{theme_path}/*") do |filename|
132+
next if non_layout_files.include?(File.basename(filename).downcase)
133+
puts "Generating '#{theme_name}' layout: #{File.basename(filename)}"
134+
135+
open(File.join(CONFIG['layouts'], File.basename(filename)), 'w') do |page|
136+
if File.basename(filename, ".html").downcase == "default"
137+
page.puts "---"
138+
page.puts File.read(settings_file) if File.exist?(settings_file)
139+
page.puts "---"
140+
else
141+
page.puts "---"
142+
page.puts "layout: default"
143+
page.puts "---"
144+
end
145+
page.puts "{% include JB/setup %}"
146+
page.puts "{% include themes/#{theme_name}/#{File.basename(filename)} %}"
147+
end
148+
end
149+
150+
puts "=> Theme successfully switched!"
151+
puts "=> Reload your web-page to check it out =)"
152+
end # task :switch
153+
154+
# Public: Install a theme using the theme packager.
155+
# Version 0.1.0 simple 1:1 file matching.
156+
#
157+
# git - String, Optional path to the git repository of the theme to be installed.
158+
# name - String, Optional name of the theme you want to install.
159+
# Passing name requires that the theme package already exist.
160+
#
161+
# Examples
162+
#
163+
# rake theme:install git="https://github.com/jekyllbootstrap/theme-twitter.git"
164+
# rake theme:install name="cool-theme"
165+
#
166+
# Returns Success/failure messages.
167+
desc "Install theme"
168+
task :install do
169+
if ENV["git"]
170+
manifest = theme_from_git_url(ENV["git"])
171+
name = manifest["name"]
172+
else
173+
name = ENV["name"].to_s.downcase
174+
end
175+
176+
packaged_theme_path = JB::Path.build(:theme_packages, :node => name)
177+
178+
abort("rake aborted!
179+
=> ERROR: 'name' cannot be blank") if name.empty?
180+
abort("rake aborted!
181+
=> ERROR: '#{packaged_theme_path}' directory not found.
182+
=> Installable themes can be added via git. You can find some here: http://github.com/jekyllbootstrap
183+
=> To download+install run: `rake theme:install git='[PUBLIC-CLONE-URL]'`
184+
=> example : rake theme:install git='[email protected]:jekyllbootstrap/theme-the-program.git'
185+
") unless FileTest.directory?(packaged_theme_path)
186+
187+
manifest = verify_manifest(packaged_theme_path)
188+
189+
# Get relative paths to packaged theme files
190+
# Exclude directories as they'll be recursively created. Exclude meta-data files.
191+
packaged_theme_files = []
192+
FileUtils.cd(packaged_theme_path) {
193+
Dir.glob("**/*.*") { |f|
194+
next if ( FileTest.directory?(f) || f =~ /^(manifest|readme|packager)/i )
195+
packaged_theme_files << f
196+
}
197+
}
198+
199+
# Mirror each file into the framework making sure to prompt if already exists.
200+
packaged_theme_files.each do |filename|
201+
file_install_path = File.join(JB::Path.base, filename)
202+
if File.exist? file_install_path and ask("#{file_install_path} already exists. Do you want to overwrite?", ['y', 'n']) == 'n'
203+
next
204+
else
205+
mkdir_p File.dirname(file_install_path)
206+
cp_r File.join(packaged_theme_path, filename), file_install_path
207+
end
208+
end
209+
210+
puts "=> #{name} theme has been installed!"
211+
puts "=> ---"
212+
if ask("=> Want to switch themes now?", ['y', 'n']) == 'y'
213+
system("rake switch_theme name='#{name}'")
214+
end
215+
end
216+
217+
# Public: Package a theme using the theme packager.
218+
# The theme must be structured using valid JB API.
219+
# In other words packaging is essentially the reverse of installing.
220+
#
221+
# name - String, Required name of the theme you want to package.
222+
#
223+
# Examples
224+
#
225+
# rake theme:package name="twitter"
226+
#
227+
# Returns Success/failure messages.
228+
desc "Package theme"
229+
task :package do
230+
name = ENV["name"].to_s.downcase
231+
theme_path = JB::Path.build(:themes, :node => name)
232+
asset_path = JB::Path.build(:theme_assets, :node => name)
233+
234+
abort("rake aborted: name cannot be blank") if name.empty?
235+
abort("rake aborted: '#{theme_path}' directory not found.") unless FileTest.directory?(theme_path)
236+
abort("rake aborted: '#{asset_path}' directory not found.") unless FileTest.directory?(asset_path)
237+
238+
## Mirror theme's template directory (_includes)
239+
packaged_theme_path = JB::Path.build(:themes, :root => JB::Path.build(:theme_packages, :node => name))
240+
mkdir_p packaged_theme_path
241+
cp_r theme_path, packaged_theme_path
242+
243+
## Mirror theme's asset directory
244+
packaged_theme_assets_path = JB::Path.build(:theme_assets, :root => JB::Path.build(:theme_packages, :node => name))
245+
mkdir_p packaged_theme_assets_path
246+
cp_r asset_path, packaged_theme_assets_path
247+
248+
## Log packager version
249+
packager = {"packager" => {"version" => CONFIG["theme_package_version"].to_s } }
250+
open(JB::Path.build(:theme_packages, :node => "#{name}/packager.yml"), "w") do |page|
251+
page.puts packager.to_yaml
252+
end
253+
254+
puts "=> '#{name}' theme is packaged and available at: #{JB::Path.build(:theme_packages, :node => name)}"
255+
end
256+
257+
end # end namespace :theme
258+
259+
# Internal: Download and process a theme from a git url.
260+
# Notice we don't know the name of the theme until we look it up in the manifest.
261+
# So we'll have to change the folder name once we get the name.
262+
#
263+
# url - String, Required url to git repository.
264+
#
265+
# Returns theme manifest hash
266+
def theme_from_git_url(url)
267+
tmp_path = JB::Path.build(:theme_packages, :node => "_tmp")
268+
abort("rake aborted: system call to git clone failed") if !system("git clone #{url} #{tmp_path}")
269+
manifest = verify_manifest(tmp_path)
270+
new_path = JB::Path.build(:theme_packages, :node => manifest["name"])
271+
if File.exist?(new_path) && ask("=> #{new_path} theme package already exists. Override?", ['y', 'n']) == 'n'
272+
remove_dir(tmp_path)
273+
abort("rake aborted: '#{manifest["name"]}' already exists as theme package.")
274+
end
275+
276+
remove_dir(new_path) if File.exist?(new_path)
277+
mv(tmp_path, new_path)
278+
manifest
279+
end
280+
281+
# Internal: Process theme package manifest file.
282+
#
283+
# theme_path - String, Required. File path to theme package.
284+
#
285+
# Returns theme manifest hash
286+
def verify_manifest(theme_path)
287+
manifest_path = File.join(theme_path, "manifest.yml")
288+
manifest_file = File.open( manifest_path )
289+
abort("rake aborted: repo must contain valid manifest.yml") unless File.exist? manifest_file
290+
manifest = YAML.load( manifest_file )
291+
manifest_file.close
292+
manifest
293+
end
294+
295+
def ask(message, valid_options)
296+
if valid_options
297+
answer = get_stdin("#{message} #{valid_options.to_s.gsub(/"/, '').gsub(/, /,'/')} ") while !valid_options.include?(answer)
298+
else
299+
answer = get_stdin(message)
300+
end
301+
answer
302+
end
303+
304+
def get_stdin(message)
305+
print message
306+
STDIN.gets.chomp
307+
end
308+
309+
#Load custom rake scripts
310+
Dir['_rake/*.rake'].each { |r| load r }

‎_config.yml

+3-3
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ author :
2323
# Else if you are pushing to username.github.io, replace with your username.
2424
# Finally if you are pushing to a GitHub project page, include the project name at the end.
2525
#
26-
production_url : http://opentx.github.io
26+
production_url : http://www.open-tx.org
2727

2828
# All Jekyll-Bootstrap specific configurations are namespaced into this hash
2929
#
@@ -69,8 +69,8 @@ JB :
6969
#
7070
archive_path: /archive.html
7171
categories_path : /categories.html
72-
tags_path : /tags.html
73-
atom_path : /atom.xml
72+
tags_path : /archive.html
73+
# atom_path : /atom.xml
7474
rss_path : /rss.xml
7575

7676
# Settings for comments helper

0 commit comments

Comments
 (0)