README.md in octopress-3.0.0.rc.26 vs README.md in octopress-3.0.0.rc.27
- old
+ new
@@ -1,10 +1,10 @@
# Octopress
Octopress is an obsessively designed toolkit for writing and deploying Jekyll blogs. Pretty sweet, huh?
-<!--[](http://badge.fury.io/rb/octopress)-->
+[](http://badge.fury.io/rb/octopress)
[](https://travis-ci.org/octopress/octopress)
## Installation
Add this line to your application's Gemfile:
@@ -17,36 +17,225 @@
Or install it yourself as:
$ gem install octopress --pre
-## Basic Usage
+## Octopress Commands
-Here are the commands for Octopress.
+Here are the subcommands for Octopress.
-| Option | Description |
-|:--------------------------------|:----------------------------------------------|
-| `octopress init <PATH>` | Adds Octopress scaffolding to your site |
-| `octopress new <PATH>` | Like `jekyll new` + `octopress init` |
-| `octopress new post <TITLE>` | Add a new post to your site |
-| `octopress new page <PATH>` | Add a new page to your site |
-| `octopress new draft <TITLE>` | Add a new draft post to your site |
-| `octopress publish <PATH>` | Publish a draft from _drafts to _posts |
-| `octopress unpublish <POST>` | Convert a post into a draft |
-| `octopress isolate <POST>` | Isolate one or more posts for a faster build |
-| `octopress integrate` | Restores all posts, reverting isolation. |
+```
+init <PATH> # Adds Octopress scaffolding to your site
+new <PATH> # Like `jekyll new` + `octopress init`
+new post <TITLE> # Add a new post to your site
+new page <PATH> # Add a new page to your site
+new draft <TITLE> # Add a new draft post to your site
+publish <POST> # Publish a draft from _drafts to _posts
+unpublish <POST> # Search for a post and convert it into a draft
+isolate [POST] # Stash all posts but the one you're workign on for a faster build
+integrate # Restores all posts, doing the opposite of the isolate command
+```
-Run `octopress [command] --help` to learn more about any command and see its options.
+Run `octopress --help` to list sub commands and `octopress <subcommand> --help` to learn more about any subcommand and see its options.
-### Deployment
+### Init
-You can deploy your Octopress or Jekyll blog via git, rsync or Amazon S3. The deployment system ships with the [octopress-deploy][] gem which extends the Octopress CLI with the `deploy` command.
+```sh
+$ octopress init <PATH> [options]
+```
-[octopress-deploy]: https://github.com/octopress/deploy
+This will copy Octopress's scaffolding into the specified directory. Use the `--force` option to overwrite existing files. The scaffolding is pretty simple:
+```
+_templates/
+ draft
+ post
+ page
+```
+
+### New Post
+
+This automates the creation of a new post.
+
+```sh
+$ octopress new post "My Title"
+```
+
+This will create a new file at `_posts/YYYY-MM-DD-my-title.markdown` with the following YAML front-matter already added.
+
+```
+layout: post
+title: "My Title"
+date: YYYY-MM-DDTHH:MM:SS-00:00
+```
+
+#### Command options
+
+| Option | Description |
+|:---------------------|:----------------------------------------|
+| `--template PATH` | Use a template from <path> |
+| `--date DATE` | The date for the post. Should be parseable by [Time#parse](http://ruby-doc.org/stdlib-2.1.0/libdoc/time/rdoc/Time.html#method-i-parse) |
+| `--slug SLUG` | Slug for the new post. |
+| `--dir DIR` | Create post at _posts/DIR/. |
+| `--force` | Overwrite existing file. |
+
+### New Page
+
+Creating a new page is easy, you can use the default file name extension (.html), pass a specific extension, or end with a `/` to create
+an index.html document.
+
+```
+$ octopress new page some-page # ./some-page.html
+$ octopress new page about.md # ./about.md
+$ octopress new page docs/ # ./docs/index.html
+```
+
+If you are working with collections, you might add a page like this:
+
+```
+$ octopress new page _legal/terms # ./_legal/terms.html
+```
+
+After the page is created, Octopress will tell you how to configure this new collection.
+
+
+#### Command options
+
+| Option | Description |
+|:---------------------|:----------------------------------------|
+| `--template PATH` | Use a template from <path> |
+| `--title TITLE` | The title of the new page |
+| `--date DATE` | The date for the page. Should be parseable by [Time#parse](http://ruby-doc.org/stdlib-2.1.0/libdoc/time/rdoc/Time.html#method-i-parse) |
+| `--force` | Overwrite existing file. |
+
+Note: The default page template doesn't expect a date. If you want to add dates
+to your pages, consider adding `date: {{ date }}` to the default template
+`_templates/page`, or create a new template to use for dated pages. Otherwise,
+you will have the `--date` option to add a date to a page.
+
+### New Draft
+
+This will create a new post in your `_drafts` directory.
+
+```sh
+$ octopress new draft "My Title"
+```
+
+| Option | Description |
+|:-------------------|:------------------------------------------|
+| `--template PATH` | Use a template from <path> |
+| `--date DATE` | The date for the draft. Should be parseable by [Time#parse](http://ruby-doc.org/stdlib-2.1.0/libdoc/time/rdoc/Time.html#method-i-parse) (defaults to Time.now) |
+| `--slug SLUG` | The slug for the new post. |
+| `--force` | Overwrite exsiting file. |
+
+### Publish a draft
+
+Use the `publish` command to publish a draft to the `_posts` folder. This will also rename the file with the proper date format.
+
+```sh
+$ octopress publish _drafts/some-cool-post.md
+$ octopress publish cool
+```
+In the first example, a draft is published using the path. The publish command can also search for a post by filename. The second command
+would work the same as the first. If other drafts match your search, you will be prompted to select them from a menu. This is often much
+faster than typing out the full path.
+
+| Option | Description |
+|:-------------------|:------------------------------------------|
+| `--date DATE` | The date for the post. Should be parseable by [Time#parse](http://ruby-doc.org/stdlib-2.1.0/libdoc/time/rdoc/Time.html#method-i-parse) |
+| `--slug SLUG` | Change the slug for the new post. |
+| `--dir DIR` | Create post at _posts/DIR/. |
+| `--force` | Overwrite existing file. |
+
+When publishing a draft, the new post will use the draft's date. Pass the option `--date now` to the publish command to set the new post date from your system clock. As usual, you can pass any compatible date string as well.
+
+### Unpublish a post
+
+Use the `unpublish` command to move a post to the `_drafts` directory, renaming the file according to the drafts convention.
+
+```sh
+$ octopress unpublish _posts/2015-01-10-some-post.md
+$ octopress unpublish some post
+```
+
+Just like the publish command, you can either pass a path or a search string to match the file name. If more than one match is found, you
+will be prompted to select from a menu of posts.
+
+### Templates for Posts and pages
+
+Octopress post and page templates look like this.
+
+```
+---
+layout: {{ layout }}
+title: {{ title }}
+---
+```
+
+Dates get automatically added to a template for posts, and for pages if a --date option is set.
+
+You can add to the YAML front matter, add content below and even even use liquid tags and filters from your site's plugins. There are
+a handful of local variables you can use when working with templates.
+
+| Variable | Description |
+|:-------------------|:------------------------------------------|
+| `date` | The date (if set) or Time.now.iso8601 |
+| `title` | The title of the page (if set) |
+| `slug` | The title in slug form |
+| `ymd` | The date string, YYYY/MM/DD format |
+| `year` | The date's year |
+| `month` | The date's month, MM |
+| `day` | The date's day, DD |
+
+By default Octopress has templates for pages, posts and drafts. You can change them or create new ones for different types of content.
+To create linkposts template, add a file at `_templates/linkpost` and use it with a new post like this:
+
+```sh
+$ octopress new post --template _templates/linkpost
+```
+
+File name extensions are unnecessary since they're just plain text anyway.
+
+## Isolate
+
+The `isolate` command will allow you to stash posts in `_posts/_exile` where they will be ignored by Jekyll during the build process.
+Run `octopress integrate` to restore all exiled posts. This can be helpful if you have a very large site and you want to quickly preview a build
+for a single post or page.
+
+```sh
+$ octopress isolate # Move all posts
+$ octopress isolate _posts/2014-10-11-kittens.md # Move post at path
+$ octopress isolate kittens # Move post matching search
+```
+
+In the third example, if multiple posts match the search a prompt will ask you to select a post from a menu.
+
+## Configuration
+
+Octopress reads its configurations from `_config.yml`. Here's what the configuration looks like by default.
+
+```yaml
+# Default extension for new posts and pages
+post_ext: markdown
+page_ext: html
+
+# Default templates for posts and pages
+# Found in _templates/
+post_layout: post
+page_layout: page
+
+# Format titles with titlecase?
+titlecase: true
+
+# Change default template file (in _templates/)
+post_template: post
+page_template: page
+draft_template: draft
+```
+
## Contributing
-1. Fork it
+1. Fork it ( https://github.com/octopress/octopress/fork )
2. Create your feature branch (`git checkout -b my-new-feature`)
3. Commit your changes (`git commit -am 'Add some feature'`)
4. Push to the branch (`git push origin my-new-feature`)
5. Create new Pull Request