|
| 1 | +## What is Octopress? |
| 2 | + |
| 3 | +Octopress is [Jekyll](https://github.com/mojombo/jekyll) blogging at its finest. |
| 4 | + |
1 | 5 | 1. **Octopress sports a clean responsive theme** written in semantic HTML5, focused on readability and friendliness toward mobile devices.
|
2 | 6 | 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.
|
3 | 7 | 3. **Third party integration is simple** with built-in support for Twitter, Pinboard, Delicious, Disqus Comments, and Google Analytics.
|
4 | 8 | 4. **It's easy to use.** A collection of rake tasks simplifies development and makes deploying a cinch.
|
5 | 9 | 5. **Ships with great plugins** some original and others from the Jekyll community — tested and improved.
|
6 | 10 |
|
7 |
| -## Getting Started |
8 |
| - |
9 |
| -[Create a new repository](https://github.com/repositories/new) for your website then |
10 |
| -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 |
11 |
| -repository is named `your_username.github.com` or `your_organization.github.com`. |
12 |
| - |
13 |
| - mkdir my_octopress_site |
14 |
| - cd my_octopress_site |
15 |
| - git init |
16 |
| - git remote add octopress git://github.com/imathis/octopress.git |
17 |
| - git pull octopress master |
18 |
| - git remote add origin (your repository url) |
19 |
| - git push origin master |
20 |
| - |
21 |
| - # Next, if you're using Github user or organization pages, |
22 |
| - # Create a source branch and push to origin source. |
23 |
| - git branch source |
24 |
| - git push origin source |
25 |
| - |
26 |
| - |
27 |
| -Next, setup an [RVM](http://beginrescueend.com/) and install dependencies. |
28 |
| - |
29 |
| - rvm rvmrc trust |
30 |
| - bundle install |
31 |
| - |
32 |
| - # Install pygments (for syntax highlighing) |
33 |
| - sudo easy_install pip |
34 |
| - sudo pip install pygments |
35 |
| - |
36 |
| -Install the default Octopress theme, |
37 |
| - |
38 |
| - rake install |
39 |
| - |
40 |
| -and you should be all set up to begin blogging with Octopress. |
41 |
| - |
42 |
| -### Generate & Preview |
43 |
| - |
44 |
| - rake generate # Generates your blog into the public directory |
45 |
| - rake watch # Watches files for changes and regenerates your blog |
46 |
| - rake preview # Watches, and mounts a webserver at http://localhost:4000 |
47 |
| - |
48 |
| -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. |
49 |
| - |
50 |
| - cd ~/.pow |
51 |
| - ln -s /path/to/octopress |
52 |
| - cd - |
53 |
| - |
54 |
| -Now that you're setup with POW, you'll just run `rake watch` and load up `http://octopress.dev` instead. |
55 |
| - |
56 |
| -## Writing A Post |
57 |
| - |
58 |
| -Create your first post. |
59 |
| - |
60 |
| - rake new_post["hello world"] |
61 |
| - |
62 |
| -This will put a new post with a name like like `2011-07-3-hello-world.markdown` in the `source/_posts` directory. |
63 |
| -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) |
64 |
| -which tells Jekyll how to processes posts and pages. |
65 |
| - |
66 |
| - --- |
67 |
| - layout: post |
68 |
| - title: "Hello World" |
69 |
| - date: 2011-07-03 5:59 |
70 |
| - comments: true |
71 |
| - categories: |
72 |
| - --- |
73 |
| - |
74 |
| -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 |
75 |
| -should see the new post show up in your blog index. |
76 |
| - |
77 |
| -Octopress does more than this though. Check out [Blogging with Octopress](#include_link) to learn about all the different ways Octopress makes blogging easier. |
78 |
| - |
79 |
| -## Configuring Octopress |
80 |
| - |
81 |
| -I've tried to keep configuring Octopress fairly simple. Here's a list of files for configuring Octopress. |
82 |
| - |
83 |
| - _config.yml # Main config (Jekyll blog settings) |
84 |
| - Rakefile # Config for Rsync deployment |
85 |
| - config.rb # Compass config |
86 |
| - |
87 |
| - sass/custom/_colors.scss # change your blog's color scheme |
88 |
| - sass/custom/_layout.scss # change your blog's layout |
89 |
| - sass/custom/_styles.scss # override your blog's styles |
90 |
| - |
91 |
| -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 |
92 |
| -deployment configurations (if you're going to [deploy with Rsync over SSH](#deploy_with_rsync)). |
93 |
| - |
94 |
| -## Deploying |
95 |
| - |
96 |
| -### Deploying with Rsync via SSH |
97 |
| - |
98 |
| -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. |
99 |
| - |
100 |
| - ssh_user = "user@domain.com" |
101 |
| - document_root = "~/website.com/" |
102 |
| - |
103 |
| -Now if you run `rake deploy` in your terminal, your `public` directory will be synced to your server's document root. |
104 |
| - |
105 |
| -### Deploying to Github Pages |
106 |
| - |
107 |
| -To setup deployment, you'll want to clone your target repository into the `_deploy` directory in your Octopress project. |
108 |
| -If you're using Github project pages, clone the repository for that project, eg `git@github.com:username/project.git`. |
109 |
| -If you're using Github user or organization pages, clone the repository `git@github.com:usernem/username.github.com.git`. |
110 |
| - |
111 |
| - # For Github project pages: |
112 |
| - git clone git@github.com:username/project.git _deploy |
113 |
| - rake config_deploy[gh-pages] |
114 |
| - |
115 |
| - # For Github user/organization pages: |
116 |
| - git clone git@github.com:username/username.github.com _deploy |
117 |
| - rake config_deploy[master] |
118 |
| - |
119 |
| - # Now to deploy, you'll run |
120 |
| - rake deploy |
121 |
| - |
122 |
| -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. |
123 |
| -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. |
124 |
| -Github will queue your site for publishing (which usually occurs instantly or within minutes if it's your first commit). |
125 |
| - |
126 |
| - |
127 |
| -### Deploying to a Subdirectory (Github Project Pages does this) |
128 |
| - |
129 |
| -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. |
130 |
| -You can do this *almost* automatically: |
131 |
| - |
132 |
| - rake set_root_dir[your/path] |
133 |
| - |
134 |
| - # To go back to publishing to the document root |
135 |
| - rake set_root_dir[/] |
136 |
| - |
137 |
| -Then update your `_config.yml` and `Rakefile` as follows: |
138 |
| - |
139 |
| - # _config.yml |
140 |
| - url: http://yoursite.com/your/path |
141 |
| - |
142 |
| - # Rakefile (if deploying with rsync) |
143 |
| - document_root = "~/yoursite.com/your/path" |
144 |
| - |
145 |
| -To manually configure deployment to a subdirectory, you'll change `_config.yml`, `config.rb` and `Rakefile` |
146 |
| - |
147 |
| - # Example for deploying to Octopress's Github Pages |
148 |
| - |
149 |
| - # _config.yml |
150 |
| - destination: public/octopress |
151 |
| - url: http://imathis.github.com/octopress |
152 |
| - subscribe_rss: /octopress/atom.xml |
153 |
| - root: /octopress |
154 |
| - |
155 |
| - # config.rb - for Compass & Sass |
156 |
| - http_path = "/octopress" |
157 |
| - http_images_path = "/octopress/images" |
158 |
| - http_fonts_path = "/octopress/fonts" |
159 |
| - css_dir = "public/octopress/stylesheets" |
160 |
| - |
| 11 | +## Documentation |
161 | 12 |
|
162 |
| - # Rakefile |
163 |
| - public_dir = "public/octopress" |
164 |
| - # If deploying with rsync, update your Rakefile path |
165 |
| - document_root = "~/yoursite.com/your/path" |
| 13 | +Check out [Octopress.org](http://octopress.org/docs) for guides and documentation. |
166 | 14 |
|
167 | 15 | ## License
|
168 | 16 | (The MIT License)
|
|
0 commit comments