josegonzalez / Ruby Cimino
Labels
Cimino: Jekyll Blogging Like a Boss
Cimino is a powerful, Jekyll-based distribution full of burrito-eating and badassery. It combines some of the most useful plugins and contributions from the Jekyll community with some ridiculous ninja-hacks to turn Jekyll into an easy to use and easy to extend blogging platform. Because we all love platforms.
Still pretty experimental. If something in this readme doesn't work as promised, oops?
Requirements
- Ruby 1.9.3.
- Python 2.7 for syntax highlighting via Pygments. Unnecessary if using default coderay highlighter
- Patience
Installation
Pre-installation
- Install Ruby 1.9.3 via your favorite installation method. Included are
.rbenv-version
and.rvmrc
files which may help speed up switching between Ruby versions. - Install Python 2.7. This comes default on Ubuntu 11.10, and is easily installable on OS X. You'll also want pip to install Python requirements. Unnecessary if using default coderay highlighter.
Cimino Installation
# Clone cimino into a working area
cd path/to/your/working/area
git clone git://github.com/josegonzalez/cimino.git
# Install all of cimino's requirements
cd cimino
pip install -r requirements.txt # Unnecessary if using default coderay/rainbow highlighter
bundle install
# Set cimino up the bomb
rake setup
Usage
Whenever you run rake setup
from the cimino
directory, the rake task will attempt to do the following:
- Setup all temporary directories
- Create your source directory with the apropriate directories
- Ask you for some configuration information
- Setup a custom
_config.yml
in your source directory - Cache your configuration information for upgrades
Cimino includes a .gitignore
file which ignores any created directories, such as _site
, _tmp
, and source
. This means you can make your source
directory a git repository by doing the following:
cd path/to/your/cimino_install
cd source
git init
git add .
git commit -m "Initial commit"
Updating Cimino is quite simple. Simply issue a git pull origin master
in your Cimino installation directory and run rake update
. This will ensure your _config.yml
file is up to date. It will also warn you that your Cimino theme is out of date if you happened to override a core theme in your source
directory.
Themes
Themes are central to how Cimino works. Cimino hates not being able to customize his blog, so he has the ability to switch between various themes at will. Not only does Cimino come with a few core themes out of the box, but it is also possible to include your own themes within your source
directory.
Theming is simple. Normally you have _includes
and _layouts
directories and a slew of other template files in your source
directory. This gets a bit messy when updating your blog, so Cimino has the ability to move all these files into a custom theme folder that lives in _themes
. You'll notice that Cimino himself comes with a few themes, each of which can choose to implement or not various features. Most themes are interchangeable, but you may have a specific need for your own blog, so feel free to throw away what is unnecessary.
When customizing your Cimino installation, feel free to either create a new theme in source/_themes
, or copy an existing theme from _themes
to source/_themes
. In doing so, you allow Cimino to be cleanly updated at a later date without merge conflicts or silly, potentially error-prone file movements.
Themes typically have the following folders and files:
`-- source/
`-- _themes/
`-- theme_name/
|-- _includes/
|-- _layouts/
| |-- default.html
| |-- page.html
| `-- post.html
|-- css/
|-- images/
|-- js/
|-- 404.html
|-- favicon.ico
|-- humans.txt
|-- robots.txt
`-- sitemap.xml
You can copy many of these files from the classic
theme, or you can choose to omit them. If you are extending an existing theme, Cimino is smart enough to try and get the themefile from it's Core whenever you omit it. Simply name your theme the same as one in the core and Cimino will do the rest.
You're also allowed to implement as many of the custom plugin layouts as necessary, or add any other theme-specific pages. Feel free to explore themes included with Cimino if you are confused as to what goes and what does not go in a theme.
Plugins
Because Cimino LOVES to mess around with cool stuff, he includes many useful plugins and Jekyll extensions. If you find something super #dagital you want Cimino to know about, feel free to issue a pull request with the plugin in hand.
All included plugins have been attributed to their original creators where possible. If you feel slighted in any way and would like your work removed, feel free to let me know and we'll split half of all the money Cimino makes off of your hard work ;)
Converters
For the time being, these converters do NOT work on anything in _layouts
. This is a limitation in Jekyll which I hope to hack fix.
-
coffee
: Converts.coffee
files to.js
-
haml
: Converts.haml
files to.html
-
sass
: Converts.sass
and.scss
files to.css
-
styl
: Converts.styl
files to.css
-
upcase
: Converts.upcase
files to uppercase
Extensions
-
iterator
: Add an iterator for posts into the categories and tags properties of thesite
object. You can use this to automatically generate a tag cloud and a category page listing. e.g. Tag Cloud on Sidebar -
liquid_exception_handler
: When creating there is a liquid exception, this will suppress the exception during jekyll's generation step. DANGEROUS -
post_filter
: Allows filtering of Post methods, AOSP style -
themes
: Add theme support to Jekyll
Filters
-
extended_filters
date_to_month
date_to_month_abbr
date_to_utc
html_truncatewords
preview
markdownify
Generators
-
archive
: creates archive pages byyear
,year/month
, andyear/month/day
. Automatically generate archive pages for dates like 2010/, 2010/01/, and 2010/01/12 using files in _layouts to specify what each page will look like. e.g. Posts for January 2010 -
atom
: creates anatom.xml
feed -
generic_index
: creates generic index pages, liketag
andcategory
pages. Automatically generate index pages for each of the site.configindex_pages
. Currently iterates over collections already in the site, meaning all you need to do to have index pages for tags and categories is add them to theindex_pages
site.config
key. Creates specific collection pages from layouts in _layouts to specify what each page will look like. e.g. CakePHP. Also creates a listing of all of a particular collection. e.g. Categories. If the yaml maps to a booleantrue
, related collection items will appear inpage.related
-
post_type
: Allows you to create generic post type landing pages and sub-pages, likeportfolios
orgalleries
. Allows the creation of a series of posts based on a type. Useful if you want to create a portfolio or gallery from an_post_types/gallery
or_post_types/portfolio
directory. -
sitemap
: creates asitemap.xml
file
Tags
-
backtick
: Allow placing codeblocks within three ```, github-style -
highlight
: Write highlights with semantic HTML5 -
quote
: Allows the usage of blockquotes with attribution within your application by doing:{% blockquote John Hancock %} Content {% endblockquote %}
Also adds support for pullquotes:
{% pullquote John Hancock %}
Content
{% endpullquote %}
-
rainbow
: Wraps codeblocks inrainbow
compliant html tags -
raw
: Raw tag for jekyll. Keeps liquid from parsing text betweeen {% raw %} and {% endraw %} -
render_time
: Samplerender_time
tag
Utilities
-
highlight_code
: Remove need for built-in Pygments syntax highlighting in favor of ruby gem implementations of syntax highlighting -
template_wrapper
: This is useful for preventing Markdown and Textile from being too aggressive and incorrectly parsing in-line HTML.
Todo
Include plugins within themesMore themesAdd the ability to comment and share posts/pagesCleanup plugin documentation- Tests for plugins
Add template for_config.yml
Split up Rakefile into separate tasks- Include common deployment scenarios - Github, Heroku, Amazon,
Rsync - Steal more stuff from Octopress and other distributions
-
Sleep#willnotfix Unknown bug fixes
License
License valid for all new code, design/html that isn't directly attributable to a known source, hacks on hacks, and things generally written by me. Serp-a-derp, please don't sue me.
MIT
Copyright (c) 2012 Jose Diaz-Gonzalez
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.