From 1b484123ac1f742b0ab4be0c310abb9d3088eedf Mon Sep 17 00:00:00 2001 From: B Mathis Date: Sun, 1 Nov 2009 00:17:17 -0500 Subject: updated readme to explain configuration, usage, and customization --- README.markdown | 50 +++++++++++++++---- source/debug/typography.haml | 116 ------------------------------------------- source/test/typography.haml | 116 +++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 156 insertions(+), 126 deletions(-) delete mode 100644 source/debug/typography.haml create mode 100644 source/test/typography.haml diff --git a/README.markdown b/README.markdown index a671be87..a67c0c81 100644 --- a/README.markdown +++ b/README.markdown @@ -1,6 +1,11 @@ # What is Octopress? Octopress gives developers a well designed starting point for a Jekyll blog. It's easy to configure and easy to deploy. Sweet huh? +#### Octopress comes with +1. A nice easy to configure theme that focuses on readability. +2. Built in support for Twitter, Delicious, and Disqus Comments. +3. Rake tasks that make development fast, and deployment easy. + ## Why? 1. Building a Jekyll blog from scratch is a lot of work. 2. Jekyll doesn't have default layouts or themes. @@ -8,10 +13,10 @@ Octopress gives developers a well designed starting point for a Jekyll blog. It' ## Octopress is made of - [Jekyll](http://github.com/henrik/jekyll) a blog aware static site generator (Henrik's fork adds [HAML](http://haml-lang.com) support) -- [Compass](http://compass-style.org) an awesome [SASS](http://sass-lang.com) framework. -- [FSSM](http://github.com/ttilley/fssm/tree/master) + a rake task, automatically regenerates the blog as you work. +- [Compass](http://compass-style.org) an awesome [SASS](http://sass-lang.com) framework +- [FSSM](http://github.com/ttilley/fssm/tree/master) + a rake task, automatically regenerates the blog as you work - [Serve](http://github.com/jlong/serve) for live previews of the site while in development -- [Rsync](http://samba.anu.edu.au/rsync/) for easy deployment. +- [Rsync](http://samba.anu.edu.au/rsync/) for easy deployment ## Setup #### First, clone Octopress locally. @@ -24,18 +29,43 @@ Octopress gives developers a well designed starting point for a Jekyll blog. It' #### Third 1. Edit the top of the Rakefile settings to match your web hosting info. -2. Edit the top of the atom.haml and _layout/default.haml +2. Edit the top of the atom.haml and _layout/default.haml. ## Usage You should really read over the [Jekyll wiki](http://wiki.github.com/mojombo/jekyll) because most of your work will be using Jekyll. Beyond that Octopress is mostly some rake tasks, HAML, and SASS/Compass that has been meticulously crafted for ease of use and modification. -### Rake tasks -rake preview: Generates the site, starts the local web server, and opens your browser to show the generated site. +### Common Rake tasks +**rake preview**: Generates the site, starts the local web server, and opens your browser to show the generated site. + +**rake watch**: Watches the source for changes and regenerates the site every time you save a file. You'll forget your working with a static site. + +**rake deploy**: Generates the site and then uses rsync (based on your configurations in the Rakefile) to synchronize with your web host. In order to use rsync you'll need shell access to your host, and you'll probably want to use your public key for authentication. + +**rake stop_serve**: Kills the local web server process. + +*There are more but these are the ones you'll use the most. Read the Rakefile if you want to learn more* + +## Style Configuration +### What you need to know +Octopress's stylesheets are written in [SASS](http://sass-lang.com). If you haven't learned SASS, you should. It's the future. Octopress also uses [Compass](http://compass-style.org) which is a framework for SASS and contains a great library of SASS mixins which make it trivial to write complicated CSS. This is also the future. + +### Customizing the default theme +The default theme is comprised of Layout, Typography, Theme, and Partials. Octopress also has a library of mixins that act like SASS helpers for styling tasks. + +#### Layout +Edit the variables at the top of /stylesheets/_layout.sass to configure the primary structural dimensions, including the header, footer, main content, and sidebar. + +#### Typography +Octopress puts a strong focus on readability and borrows some concepts from the [better web readability project](http://code.google.com/p/better-web-readability-project/). As a result the base font size is 16px. Don't worry though, if you don't like that, you can simply change the variable !base\_font\_size at the top of /stylesheets/_typography.sass and all of the other typographic math (heading sizes, line-heights, margins, etc) will be resized to suit automatically. + +If you want to add or modify site-wide typography, this is the file to do it in. If your changes are specific to a small section or feature of your site, you should probably add that under *Partials*. -rake watch: Watches the source for changes and regenerates the site every time you save a file. You'll forget your working with a static site. +Octopress ships with a typography test page /test/typography.html that lets you preview the default typographic styles, and see how your changes affect them. -rake deploy: Generates the site and then uses rsync (based on your configurations in the Rakefile) to synchronize with your web host. In order to use rsync you'll need shell access to your host, and you'll probably want to use your public key for authentication. +#### Theme +Every color used in Octopress is assigned to a variable in _theme.sass, so you can change them to suit your tastes without having to dig through a bunch of files to find the color your looking for. Also the colors variables are grouped by their location in the site layout to make them easier to find. -rake stop_serve: Kills the local web server process. +#### Partials +These are the styles for subsections of the site. They're located in /stylesheets/partials and each subsection has it's own file. Here you'll find styles for the sidebar, blog posts, syntax highlighting, and specific page elements that don't belong in the base layout files. -*There are more but these are the ones you'll use the most. Read the Rakefile if you want to learn more* \ No newline at end of file +Octopress ships with a syntax highlighting test page /test/syntax.html that lets you preview the default syntax highlighting styles, and see how your changes affect them. \ No newline at end of file diff --git a/source/debug/typography.haml b/source/debug/typography.haml deleted file mode 100644 index f7e7b17b..00000000 --- a/source/debug/typography.haml +++ /dev/null @@ -1,116 +0,0 @@ ---- -layout: default -title: Typography Debug ---- - -%h1 Level 01 Heading -%h2 Level 02 Heading -%h3 Level 03 Heading -%h4 Level 04 Heading -%h5 Level 05 Heading -%h6 Level 06 Heading - -%p - Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Fusce sodales ligula sed urna. Aliquam posuere arcu - viverra erat. Pellentesque et enim dapibus ante facilisis bibendum. Nam congue dapibus urna. Vestibulum consequat - arcu at magna. Nunc faucibus mollis lacus. Nulla tempor luctus tellus. Donec blandit lobortis pede. Vestibulum - vel pede ut urna eleifend lacinia. -%p - Maecenas ligula nibh, imperdiet at, interdum eget, sagittis eu, enim. Vivamus vel urna. Donec fringilla - ullamcorper sem. In risus arcu, pellentesque cursus, faucibus cursus, consequat quis, est. Aliquam id erat. - Aliquam arcu. Phasellus vulputate. Integer sem diam, mattis vel, viverra ullamcorper, ultricies quis, nisl. Sed - sollicitudin quam ut nisi. Vivamus velit sapien, volutpat eu, faucibus id, nonummy id, urna. -%p - Take it2 to the power of3 - Praesent iaculis pellentesque est. Nulla facilisi. Etiam fringilla vehicula orci. Aliquam fermentum ipsum id - nulla. Aliquam interdum laoreet leo. Cras accumsan. Nam pharetra diam id nunc. Integer blandit tellus vulputate - felis. Cras aliquam, eros in euismod aliquam, enim nisl mollis metus, quis fringilla ipsum diam ut pede. Mauris a - libero ac velit interdum pulvinar. Nunc ipsum mauris, semper rhoncus, feugiat ut, egestas id, diam. Nullam - porttitor condimentum risus. Vivamus nec enim eget nisi commodo euismod. Ut turpis. Nullam malesuada rutrum - neque. Nam sodales porta elit. Mauris mollis nisl vel augue. - -%p - And we were like Woah, and he was like Woah, and they were like WOAH! - -%p - %abbr(title="For The Win!") FTW! -%p - -%h3 Unordered lists -%ul - %li Lorem ipsum dolor sit amet - %li Consectetur adipisicing elit - %li Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua - %li Ut enim ad minim veniam - -%h3 Ordered lists -%ol - %li Consectetur adipisicing elit - %li Sed do eiusmod tempor incididunt ut labore - %li Et dolore magna aliqua - -%h3 Blockquotes -%blockquote - %p - Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore - magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo - consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. - Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. - -%h3 Tables -%table - %caption - Jimi Hendrix - albums - %thead - %tr - %th Album - %th Year - %th Price - %tfoot - %tr - %td Album - %td Year - %td Price - %tbody - %tr - %td Are You Experienced - %td 1967 - %td $10.00 - %tr - %td Axis: Bold as Love - %td 1967 - %td $12.00 - %tr - %td Electric Ladyland - %td 1968 - %td $10.00 - %tr - %td Band of Gypsys - %td 1970 - %td $12.00 -%p - %a(href="#")Link - %br/ - %strong <strong> - %br/ - %del <del> deleted - %br/ - %dfn <dfn> dfn - %br/ - %em <em> emphasis - %br/ - -%pre - %code - <html> - <head> - </head> - <body> - <div class = "main"> <div> - </body> - </html> - -%tt - <tt> - Pellentesque tempor, dui ut ultrices viverra, neque urna blandit nisi, id accumsan dolor est vitae risus. -%hr \ No newline at end of file diff --git a/source/test/typography.haml b/source/test/typography.haml new file mode 100644 index 00000000..f7e7b17b --- /dev/null +++ b/source/test/typography.haml @@ -0,0 +1,116 @@ +--- +layout: default +title: Typography Debug +--- + +%h1 Level 01 Heading +%h2 Level 02 Heading +%h3 Level 03 Heading +%h4 Level 04 Heading +%h5 Level 05 Heading +%h6 Level 06 Heading + +%p + Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Fusce sodales ligula sed urna. Aliquam posuere arcu + viverra erat. Pellentesque et enim dapibus ante facilisis bibendum. Nam congue dapibus urna. Vestibulum consequat + arcu at magna. Nunc faucibus mollis lacus. Nulla tempor luctus tellus. Donec blandit lobortis pede. Vestibulum + vel pede ut urna eleifend lacinia. +%p + Maecenas ligula nibh, imperdiet at, interdum eget, sagittis eu, enim. Vivamus vel urna. Donec fringilla + ullamcorper sem. In risus arcu, pellentesque cursus, faucibus cursus, consequat quis, est. Aliquam id erat. + Aliquam arcu. Phasellus vulputate. Integer sem diam, mattis vel, viverra ullamcorper, ultricies quis, nisl. Sed + sollicitudin quam ut nisi. Vivamus velit sapien, volutpat eu, faucibus id, nonummy id, urna. +%p + Take it2 to the power of3 + Praesent iaculis pellentesque est. Nulla facilisi. Etiam fringilla vehicula orci. Aliquam fermentum ipsum id + nulla. Aliquam interdum laoreet leo. Cras accumsan. Nam pharetra diam id nunc. Integer blandit tellus vulputate + felis. Cras aliquam, eros in euismod aliquam, enim nisl mollis metus, quis fringilla ipsum diam ut pede. Mauris a + libero ac velit interdum pulvinar. Nunc ipsum mauris, semper rhoncus, feugiat ut, egestas id, diam. Nullam + porttitor condimentum risus. Vivamus nec enim eget nisi commodo euismod. Ut turpis. Nullam malesuada rutrum + neque. Nam sodales porta elit. Mauris mollis nisl vel augue. + +%p + And we were like Woah, and he was like Woah, and they were like WOAH! + +%p + %abbr(title="For The Win!") FTW! +%p + +%h3 Unordered lists +%ul + %li Lorem ipsum dolor sit amet + %li Consectetur adipisicing elit + %li Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua + %li Ut enim ad minim veniam + +%h3 Ordered lists +%ol + %li Consectetur adipisicing elit + %li Sed do eiusmod tempor incididunt ut labore + %li Et dolore magna aliqua + +%h3 Blockquotes +%blockquote + %p + Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore + magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo + consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. + Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. + +%h3 Tables +%table + %caption + Jimi Hendrix - albums + %thead + %tr + %th Album + %th Year + %th Price + %tfoot + %tr + %td Album + %td Year + %td Price + %tbody + %tr + %td Are You Experienced + %td 1967 + %td $10.00 + %tr + %td Axis: Bold as Love + %td 1967 + %td $12.00 + %tr + %td Electric Ladyland + %td 1968 + %td $10.00 + %tr + %td Band of Gypsys + %td 1970 + %td $12.00 +%p + %a(href="#")Link + %br/ + %strong <strong> + %br/ + %del <del> deleted + %br/ + %dfn <dfn> dfn + %br/ + %em <em> emphasis + %br/ + +%pre + %code + <html> + <head> + </head> + <body> + <div class = "main"> <div> + </body> + </html> + +%tt + <tt> + Pellentesque tempor, dui ut ultrices viverra, neque urna blandit nisi, id accumsan dolor est vitae risus. +%hr \ No newline at end of file -- cgit v1.2.1