README.markdown
765c15be
 1. **Octopress sports a clean responsive theme** written in semantic HTML5, focused on readability and friendliness toward mobile devices.
 2. **Code blogging is easy and beautiful.** Embed code (with [Solarized](http://ethanschoonover.com/solarized) styling) in your posts from gists or from your filesystem.
21813059
 3. **Third party integration is simple** with built-in support for Twitter, Pinboard, Delicious, Disqus Comments, and Google Analytics.
 4. **It's easy to use.** A collection of rake tasks simplifies development and makes deploying a cinch.
ef3ff431
 5. **Ships with great plugins** some original and others from the Jekyll community — tested and improved.
21813059
 
a128d499
 ## Getting Started
21813059
 
a128d499
 [Create a new repository](https://github.com/repositories/new) for your website then
 open up a terminal and follow along. If you plan to host your site on [Github Pages](http://pages.github.com) for a user or organization, make sure the
 repository is named `your_username.github.com` or `your_organization.github.com`.
21813059
 
a128d499
     mkdir my_octopress_site
     cd my_octopress_site
     git init
21813059
     git remote add octopress git://github.com/imathis/octopress.git
a128d499
     git pull octopress master
     git remote add origin (your repository url)
     git push origin master
21813059
 
eba8e7f5
     # Next, if you're using Github user or organization pages,
     # Create a source branch and push to origin source.
     git branch source
a128d499
     git push origin source
21813059
 
a128d499
 
ef3ff431
 Next, setup an [RVM](http://beginrescueend.com/) and install dependencies.
a128d499
 
     rvm rvmrc trust
21813059
     bundle install
 
     # Install pygments (for syntax highlighing)
     sudo easy_install pip
     sudo pip install pygments
 
     # Install the default Octopress theme
     rake install
 
a128d499
 ### Generating Your Blog
 
     rake generate   # Generates your blog into the public directory
     rake watch      # Watches files for changes and regenerates your blog
eba8e7f5
     rake preview    # Watches, and mounts a webserver at http://localhost:4000
a128d499
 
 Jekyll's built in webbrick server is handy, but if you're a [POW](http://pow.cx) user, you can set it up to work with Octopress like this.
 
     cd ~/.pow
     ln -s /path/to/octopress
     cd -
 
eba8e7f5
 Now that you're setup with POW, you'll just run `rake watch` and load up `http://octopress.dev` instead.
a128d499
 
 ## Writing A Post
 
eba8e7f5
 Create your first post.
21813059
 
     rake post['hello world']
 
eba8e7f5
 This will put a new post in source/_posts with a name like like `2011-07-3-hello-world.markdown` in the `source/_posts` directory.
21813059
 Open that file in your favorite text editor and you'll see a block of [yaml front matter](https://github.com/mojombo/jekyll/wiki/yaml-front-matter)
 which tells Jekyll how to processes posts and pages.
 
     ---
     title: Hello World
eba8e7f5
     date: 2011-07-03 5:59
21813059
     layout: post
     ---
 
eba8e7f5
 Now beneath the yaml block, go ahead and type up a sample post, or use some [inspired filler](http://baconipsum.com/). If you're running the watcher, save and refresh your browser and you
a128d499
 should see the new post show up in your blog index.
21813059
 
eba8e7f5
 Octopress does more than this though. Check out [Blogging with Octopress](#include_link) to learn about all the different ways Octopress makes blogging easier.
5d61b463
 
a128d499
 ## Configuring Octopress
21813059
 
a128d499
 I've tried to keep configuring Octopress fairly simple. Here's a list of files for configuring Octopress.
21813059
 
a128d499
     _config.yml       # Main config (Jekyll blog settings)
     Rakefile          # Config for Rsync deployment
     config.rb         # Compass config
21813059
 
a128d499
     sass/custom/_colors.scss      # change your blog's color scheme
     sass/custom/_layout.scss      # change your blog's layout
     sass/custom/_styles.scss      # override your blog's styles
21813059
 
a128d499
 Octopress keeps it's main configurations in two places, the `Rakefile` and the `_config.yml`. You probably won't have to change anything in the rakefile except the
 deployment configurations (if you're going to [deploy with Rsync over SSH](#deploy_with_rsync)).
 
 ## Deploying
 
 ### Deploying with Rsync via SSH
21813059
 
a128d499
 Add your server configurations to the `Rakefile` under Rsync deploy config. To deploy with Rsync, be sure your public key is listed in your server's `~/.ssh/authorized_keys` file.
21813059
 
a128d499
     ssh_user      = "user@domain.com"
     document_root = "~/website.com/"
21813059
 
a128d499
 Now if you run `rake deploy` in your terminal, your `public` directory will be synced to your server's document root.
21813059
 
a128d499
 ### Deploying to Github Pages
21813059
 
a128d499
 To setup deployment, you'll want to clone your target repository into the `_deploy` directory in your Octopress project.
 If you're using Github project pages, clone the repository for that project, eg `git@github.com:username/project.git`.
 If you're using Github user or organization pages, clone the repository `git@github.com:usernem/username.github.com.git`.
21813059
 
a128d499
     # For Github project pages:
     git clone git@github.com:username/project.git _deploy
eba8e7f5
     rake config_deploy[gh-pages]
21813059
 
a128d499
     # For Github user/organization pages:
     git clone git@github.com:username/username.github.com _deploy
eba8e7f5
     rake config_deploy[master]
21813059
 
a128d499
     # Now to deploy, you'll run
eba8e7f5
     rake deploy
21813059
 
eba8e7f5
 The `config_deploy` rake task takes a branch name as an argument and creates a [new empty branch](http://book.git-scm.com/5_creating_new_empty_branches.html), and adds an initial commit.
 This prepares your branch for easy deployment. The `rake deploy` task copies the generated blog from the `public` directory to the `_deploy` directory, adds new files, removes old files, sets a commit message, and pushes to Github.
 Github will queue your site for publishing (which usually occurs instantly or within minutes if it's your first commit).
1b484123
 
f81bdbc1
 
1f9b596b
 ### Deploying to a Subdirectory (Github Project Pages does this)
f81bdbc1
 
1f9b596b
 If you're deploying to a subdirectory on your site, or if you're using Github's project pages, make sure you set up your urls correctly in your configs.
ccda3a56
 You can do this *almost* automatically:
1f9b596b
 
     rake set_root_dir[your/path]
 
     # To go back to publishing to the document root
     rake set_root_dir[/]
 
 Then update your `_config.yml` and `Rakefile` as follows:
 
ccda3a56
     # _config.yml
1f9b596b
     url: http://yoursite.com/your/path
 
ccda3a56
     # Rakefile (if deploying with rsync)
1f9b596b
     document_root = "~/yoursite.com/your/path"
 
 To manually configure deployment to a subdirectory, you'll change `_config.yml`, `config.rb` and `Rakefile`
 
     # Example for deploying to Octopress's Github Pages
 
     # _config.yml
f81bdbc1
     destination: public/octopress
     url: http://imathis.github.com/octopress
     subscribe_rss: /octopress/atom.xml
     root: /octopress
 
1f9b596b
     # config.rb - for Compass & Sass
f81bdbc1
     http_path = "/octopress"
1f9b596b
     http_images_path = "/octopress/images"
     http_fonts_path = "/octopress/fonts"
     css_dir = "public/octopress/stylesheets"
 
f81bdbc1
 
     # Rakefile
     public_dir = "public/octopress"
1f9b596b
     # If deploying with rsync, update your Rakefile path
     document_root = "~/yoursite.com/your/path"
f81bdbc1
 
833d64e8
 ## License
 (The MIT License)
1b484123
 
ccda3a56
 Copyright © 2009-2011 Brandon Mathis
cc8985df
 
833d64e8
 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:
cc8985df
 
833d64e8
 The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
cc8985df
 
833d64e8
 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.
cc8985df
 
833d64e8
 #### If you want to be awesome.
 - Proudly display the 'Powered by Octopress' credit in the footer.
4db81a9e
 - Add your site to the wiki so we can watch the community grow.