Skip to content

Latest commit

 

History

History
229 lines (167 loc) · 9.68 KB

README.md

File metadata and controls

229 lines (167 loc) · 9.68 KB
Raw

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

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

Folding Text

iOS Linen README

iOS Linen

Paint Bucket README

Paint Bucket

Sublime Text README

Sublime Text

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

Related Technologies

Markup Languages

Higher-Level Languages

Feature Inspirations

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

Design Inspirations

Design Frameworks