Mic92/blog
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

simplified readme. pointing to the wiki for more detail

Browse Source
This commit is contained in:
B Mathis 2009-11-13 12:54:32 -06:00
parent 22a7564f2e
commit 833d64e8e0
1 changed files with 32 additions and 59 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

91
README.markdown
View File

@ -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 - [Rsync](http://samba.anu.edu.au/rsync/) for easy deployment
## Setup ## Setup
#### First, clone Octopress locally. Setup is really simple.
git clone git://github.com/imathis/octopress.git
#### Second, install required gems 1. Download Octopress: <code>git clone git://github.com/imathis/octopress.git</code>
2. Install required gems:
sudo gem install henrik-jekyll sudo gem install henrik-jekyll
sudo gem install compass-edge sudo gem install compass
sudo gem install fssm sudo gem install fssm
sudo gem install serve sudo gem install serve
3. Run <code>rake preview</code> to build the site and preview it in a local webserver.
#### Third You'll want to change some settings, so check out the [Setup & Configurations wiki page](http://wiki.github.com/imathis/octopress/setup-configuration)
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.
## Usage ## 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 - Preview the site locally with the power of Serve.
**rake preview** - Automatically regenerate your blog while you work.
Generates the site, starts the local web server, and opens your browser to show the generated site. - Generate and deploy with a single command.
**rake watch** See the [usage wiki page](http://wiki.github.com/imathis/octopress/usage) to learn more.
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*
## Third Party Integration ## Third Party Integration
### Twitter With search, comments, and analytics, you have no need for a database. This is what makes a statically generated blog possible.
Twitter settings are at the top of _layouts/default.haml
You can also change:
twitter_user: your_twitter_name - Twitter
show_replies: false - Disqus Comments
tweet_count: 3 - Google Custom Search
- Google Analytics
- Delicious Bookmarks
### Disqus Comments 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.
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
full_url: http://yoursite.com ## Octopress Style
disqus_short_name: yourdisqusname - 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 ## License
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. (The MIT License)
### Google Analytics Copyright © 2009 Brandon Mathis
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/).
### Removing Third party integrations 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:
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.
## Style Configuration The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
### 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 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.
The default theme is comprised of Layout, Typography, Theme, and Partials. Octopress also has a library of SASS mixins.
**Layout** #### If you want to be awesome.
Edit the variables at the top of /stylesheets/_layout.sass to configure the primary structural dimensions, including the header, footer, main content, and sidebar. - Proudly display the 'Powered by Octopress' credit in the footer.
- Add your site to the wiki so we can watch the community grow.
**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.