From 833d64e8e00326505b210fa82e21e9a8de5ea08c Mon Sep 17 00:00:00 2001 From: B Mathis Date: Fri, 13 Nov 2009 12:54:32 -0600 Subject: [PATCH] simplified readme. pointing to the wiki for more detail --- README.markdown | 91 +++++++++++++++++-------------------------------- 1 file changed, 32 insertions(+), 59 deletions(-) diff --git a/README.markdown b/README.markdown index 22789a1..d8011f1 100644 --- a/README.markdown +++ b/README.markdown @@ -19,81 +19,54 @@ Octopress gives developers a well designed starting point for a Jekyll blog. It' - [Rsync](http://samba.anu.edu.au/rsync/) for easy deployment ## Setup -#### First, clone Octopress locally. - git clone git://github.com/imathis/octopress.git -#### Second, install required gems +Setup is really simple. + +1. Download Octopress: git clone git://github.com/imathis/octopress.git +2. Install required gems: sudo gem install henrik-jekyll - sudo gem install compass-edge + sudo gem install compass sudo gem install fssm sudo gem install serve +3. Run rake preview to build the site and preview it in a local webserver. -#### Third -1. Edit the top of the Rakefile settings to match your web hosting info. -2. Customize the top of the atom.haml and _layout/default.haml. +You'll want to change some settings, so check out the [Setup & Configurations wiki page](http://wiki.github.com/imathis/octopress/setup-configuration) ## 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. +Octopress is almost like a front-end for Jekyll. It provides some really handy rake tasks and automation to make blogging as simple as possible. With Octopress you can: -### Common Rake tasks -**rake preview** -Generates the site, starts the local web server, and opens your browser to show the generated site. +- Preview the site locally with the power of Serve. +- Automatically regenerate your blog while you work. +- Generate and deploy with a single command. -**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* +See the [usage wiki page](http://wiki.github.com/imathis/octopress/usage) to learn more. ## Third Party Integration -### Twitter -Twitter settings are at the top of _layouts/default.haml -You can also change: +With search, comments, and analytics, you have no need for a database. This is what makes a statically generated blog possible. - twitter_user: your_twitter_name - show_replies: false - tweet_count: 3 +- Twitter +- Disqus Comments +- Google Custom Search +- Google Analytics +- Delicious Bookmarks -### Disqus Comments -Octopress has built in support for the Disqus commenting system, using the "universal code" installation method. First register your site at [http://disqus.com/comments/register/](http://disqus.com/comments/register/) Then, edit the settings at the top of _layouts/default.haml +If you already have an account with these services, you can get set up within seconds. [Check out the wiki](http://wiki.github.com/imathis/octopress/third-party-integration) to learn how to setup or remove these services. - full_url: http://yoursite.com - disqus_short_name: yourdisqusname +## Octopress Style +- Stylesheets use [SASS](http://sass-lang.com) and [Compass](http://compass-style.org) +- They're broken up into Layout, Typography, Theme (colors), and Partials +- Checkout [the wiki](http://wiki.github.com/imathis/octopress/style-customization) for help with customization. -### Google Custom Search -First setup a custom search for your site at [http://google.com/cse/](http://google.com/cse/) then add your google\_custom\_search\_id to the YAML block in the default layout. +## License +(The MIT License) -### Google Analytics -The analytics tracking scripts are already integrated into Octopress, all you have to do is register your site at [http://google.com/analytics/](http://google.com/analytics/). +Copyright © 2009 Brandon Mathis -### Removing Third party integrations -All third party integration is conditionally included. All you have to do is remove the variable from the layout and you're done. If you like, you can also remove the include blocks from the default layout. +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: -## 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. +The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. -### Customizing the default theme -The default theme is comprised of Layout, Typography, Theme, and Partials. Octopress also has a library of SASS mixins. +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. -**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*. - -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. - -**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. - -**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. - -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 +#### If you want to be awesome. +- Proudly display the 'Powered by Octopress' credit in the footer. +- Add your site to the wiki so we can watch the community grow. \ No newline at end of file