jekyll-wikibox

A guerilla wiki for hackers based on plaintext files (markdown, textile, taskpaper) transformed into static html by jekyll. The default theme is inspired by sublime text editor.

• Features or what is it about?
  • Functional Features
  • Appearance
• Usage or how can I exploit it?
  • Live Demo
  • Installation
  • Local Deployment
  • Web Deployment
  • Magic Tricks
  • Customization
  • Themes
• Project Planning or how can I hack it?
  • Important Files
  • Project Structure
  • Theme Development
• References or how does it work?
  • Core Technologies
  • Related Technologies
  • Markup Languages
  • Higher-Level Languages
  • Feature Inspirations
  • Design Inspirations
  • Design Frameworks

Features

Functional Features

• multiple boxes/repositories (blogs) for notes (markdown, textile)
• sort by date created

Appearance

• Folding Text Theme
• iOS Linen Theme
• Paint Bucket Theme
• Sublime Text Theme

Usage

Live Demo

• Available via branch gh-pages (github pages)
  http://dataduke.github.com/jekyll-wikibox (to be done)

Installation

1. install ruby
2. install jekyll $ sudo gem install jekyll
3. fork/clone/check out this github project $ git clone git://github.com/dataduke/jekyll-wikibox.git

Local Deployment

1. change to $ cd ~/github/jekyll-wiki
2. run $ jekyll --server
3. open http://localhost:4000/

Web Deployment

• GitHub Hosting: Please refer to github pages help.
• Other web hoster: Please refer to jekyll wiki/help.

Magic Tricks

• Interactive Wallpaper: desktopr.app (Mac OS X )
• Individual App: fluid.app (Mac OS X ), fake.app (Mac OS X )

Customization

./_config.yml           # configuration
./_themes/themename     # themes; move all files/folders contained in a theme to root folder (and override)

Hacking Layouts with Parameters

The files ./index.html and ./box000/index.html define the index pages. There (ex: ./box004/index.html), the choosen layout (in YAML frontmatter, ex: index-posts-1) and a parameter list for the choosen layout (as content, ex: box004) have to be defined:

---
layout: index-posts-1
title: Box 4
navigation: true
navtitle: Box 4
navpos: 5 
---
box004 showday

Inside the choosen layout file (ex: ./_layouts/index-posts-1.html) the parameter list is refereed to by the liquid template variable content in line 3 and 5:

{% for post in site.posts %}
  {% capture b %}{{ post.box }}{% endcapture %}
  {% if content contains b %}
    <!-- do something with every post with YAML frontmatter of "box: box004" -->
    {% if content contains "showday" %}
      <!-- do something with dates, like display day -->
      Day : {{ post.date | date:"%A" }
    {% endif}
  {% endif %}
{% endfor %}

Themes

Folding Text README

iOS Linen README

Paint Bucket README

Sublime Text README

Project Planning

Important Files

./README.md                       # contains general information
./CHANGELOG.md                    # contains version history
./BACKLOG.md                      # contains initial feature backlog (backup/reminder)
./JEKYLL-WIKIBOX.taskpaper        # contains planned features and current backlog

Project Structure

.
|-- .info                         # can be ignored; used for project information only
|-- .temp                         # can be ignored; used at development for backup of important files
|-- _includes                     # used for building index pages
|   |-- main-index-sidebar.md
|   |-- main-index-box-N.md
|   |-- box-N-index-sidebar.md
|   |-- box-N-index.md
|-- _layouts
|   |-- default.html
|   |-- post.html
|-- _themes             
|-- _site                         # not checked in; created by jekyll as deployment directory
|-- _plugins 
|   |-- additional-feature-X
|-- assets                        # for layout dependencies only
|   |-- css
|       |-- style.css
|   |-- img
|   |-- js
|   |-- favicon.ico
|-- box000                        # box001-005; more boxes can be added/renamed/deleted
|   |-- _posts
|   |   |-- 2013-01-01-hello-world.markdown    # .md or .textile or .taskpaper
|   |   |-- 2013-01-01-hello-world             # folder for post attachments
|   |       |-- attachment-1.jpg
|   |       |-- attachment-2.pdf
|   |-- atom.xml
|   |-- index.html
|-- _config.yml
|-- index.html
|-- atom.xml

Theme Development

Best Practices and Conventions:

1. Markdown Editing: Build a basic theme.css by styling a simple markdown text file (with the help of Marked.app this is superfast). Typically this stylesheet includes the styling of body fonts, headings (h1-h4), links, lists, sourcecode, blockquotes, definitions, tables, columns, dividers (hr) etc. This file can be used for general text editing, post previewing, printing etc. (Your basic theme.css should/could be print and mobile friendly.)

2. Desktop Browsing: Now create a theme-ext.css (or theme-web.css). This file will extend your basic theme.css to style navigation and external media elements. It should include the styling for header, navigation (bars, breadcrumb), footer, index (page body content), embedded media, etc. and maybe overwrite theme.css with a different background etc. For desktop browsing load both created stylesheets: theme.css, which renders your post texts, and theme-ext.css for nice navigation.

3. Mobile Browsing: If your basic theme.css doesn't satisfy the mobile browsing experience. Build a separate, custom and minimal theme-mobile.css without any dependencies on theme.css or theme-extensions.css.

4. Throw everything away and just use bootstrap! Just kidding.

References

Acknowledgments

To all jekyll builders.

Core Technologies

• ruby
• jekyll, Stackoverflow

Related Technologies

• jekyll-asset-pipeline, blogpost
• jekkll-asset_bundler
• jekyll-bootstrap
• multi-blog-jekyll
• github pages, help
• octopress
• ruhoh

Markup Languages

• markdown by John Gruber
• multimarkdown by Fletcher Penny
• github flavored markdown by GitHub
• textile by Dean Allan
• taskpaper by Jesse Grosjea

Higher-Level Languages

• YAML: data serialization;
• liquid github-repo github-wiki guide: template engine;
• {{ mustache }}, js-github-repo: tag expansion;
• Sass: CSS3 abstraction; .scss or .sass;
• Haml, doc: HTML abstraction; .html.haml;
• less, github-repo: CSS3 extension for dynamic behaviour (variables etc.);
• liquid, help, github-repo, wiki: template system;
• ERuby, erb: Ruby templating; .erb, .html.erb, .xml.erb;
• CoffeeScript: JavaScript abstraction;

Feature Inspirations

• PoIC (Pile of Index Cards), Wiki, Blog

Design Inspirations

• Sublime Text Theme, Sublime Text Editor, Soda-Dark.sublime-theme, Monokai-Soda.tmtheme

Design Frameworks

• jQuery UI
• Twitter Bootstrap, github-repo