From 7ce9908d5b99dcc360edfb3d15ab02eed8fc1b0b Mon Sep 17 00:00:00 2001 From: Brandon Mathis Date: Fri, 22 Jul 2011 00:56:03 -0400 Subject: [PATCH] updated configuration docs --- source/docs/configuring/index.markdown | 66 ++++++++++++++++---------- 1 file changed, 42 insertions(+), 24 deletions(-) diff --git a/source/docs/configuring/index.markdown b/source/docs/configuring/index.markdown index 690baa8..a5c686d 100644 --- a/source/docs/configuring/index.markdown +++ b/source/docs/configuring/index.markdown @@ -8,44 +8,62 @@ footer: false [« Previous, Deploying Octopress](/docs/deploy) -I've tried to keep configuring Octopress fairly simple and Octopress keeps most configurations in two places, the `Rakefile` and the `_config.yml`. +I've tried to keep configuring Octopress fairly simple and you'll probably only ever change the `Rakefile` and the `_config.yml`. Here's a list of files for configuring Octopress. - _config.yml # Main config (Jekyll's settings) - Rakefile # Configs for deployment - config.rb # Compass config - config.ru # Rack config +{% codeblock %} +_config.yml # Main config (Jekyll's settings) +Rakefile # Configs for deployment +config.rb # Compass config +config.ru # Rack config +{% endcodeblock %} Configurations in the `Rakefile` are mostly related to deployment and you probably won't have to touch them unless you're using rsync. ## Blog Configuration In the `_config.yml` there are three sections for configuring your Octopress Blog. +**Spoiler:** You'll probably only change `url`, `title`, `subtitle` and `author` and enable some 3rd party services. ### Main Configs -- **url** - Your blog's full published url. This lets Octopress automatically rewrite relative urls to absolute urls for the RSS feed. -- **title** - Your blog's title is used in the header and title tag for your pages. -- **subtitle** - A further description for your blog. This appears beneath the Main header. -- **author** - Your name (for RSS, Copyright, and metadata) If this is a multi-author blog, you can set author in the yaml front matter of each blog post instead. -- **simple_search** - Queries entered in the search form, are constructed as a site search query eg. `search phrase site:yoursite.com`. Here you can set the search engine it uses (defaults to Google). -- **subscribe_rss** - Enter a url for your blog's RSS feed Defaults to `/atom.xml` an ATOM feed generated by Octopress -- **subscribe_email** - Enter a url for your blog's email subscription link (if you have one). Octopress does not provide this. -- **email** - (Optional) fills in the email property of the RSS feed. +{% codeblock %} +url: # For rewriting URLs for RSS, etc +title: # Used in the header and title tags + +subtitle: # A description used in the header +author: # Your name, for RSS, Copyright, Metadata +simple_search: # Search engine for simple site search +subscribe_rss: # URL for your blog's feed, defauts to /atom.xml +subscribe_email: # URL to subscribe by email (service required) +email: # Email address for the RSS feed if you want it. +{% endcodeblock %} + +**Note:** If your site is a multi-author blog, you may want to set this config's `author` to the name of your +company or project, and add author metadata to posts and pages to give proper attribution for those works. ### Jekyll & Plugins -If you're not familiar with Jekyll, you should probably have a look at the [configuration docs](https://github.com/mojombo/jekyll/wiki/Configuration) +These configurations are used by Jekyll and Plugins. If you're not familiar with Jekyll, you should probably have a look at the [configuration docs](https://github.com/mojombo/jekyll/wiki/Configuration) which lists more options that aren't covered here. -- **root** - Leave this blank unless you're deploying to a subdirectory. For more info see [Deploying Octopress](/setup/deploy/) -- **port** - Specify a port for Jekyll's built in webbrick server. -- **permalink** - See [Jekyll's permalink docs](https://github.com/mojombo/jekyll/wiki/Permalinks) if you want to change the way permalinks are written for your blog posts. -- **source** - The source directory for your blog, no need to change this. -- **destination** - The folder where the generated blog files will be written. -- **plugins** - The plugins directory. -- **markdown** - Choose your Markdown processor (rdiscount or kramdown). -- **pygments** - Enable or disable pygments syntax highlighting. -- **paginate** - Set the number of posts per page in your blog index. -- **recent_posts** - Set the number of recent posts to appear in the sidebar section. +{% codeblock %} +root: # Mapping for relative urls (default: /) +port: # Port to mount Jekyll's webbrick server +permalink: # Permalink structure for blog posts +source: # Directory for site source files +destination: # Directory for generated site files +plugins: # Directory for Jekyll plugins +code_dir: # Directory for code snippets (for include_code plugin) +category_dir: # Directory for generated blog category pages +pygments: # Toggle pygments syntax highlighting +paginate: # Posts per page on the blog index +recent_posts: # Number of recent posts to appear in the sidebar +{% endcodeblock %} + +If you want to change the way permalinks are written for your blog posts, see [Jekyll's permalink docs](https://github.com/mojombo/jekyll/wiki/Permalinks). + +**Note:** Jekyll has a `baseurl` config which adds a redirect for Jekyll's webbrick server for shallow subdirectory support. +Octopress uses the `root` configuration and offers a rake task `set_root_dir[/some/directory]` to update configs and move exported files to the subdirectory [(see Deploying Octopress)](/docs/deploying). +In other words, don't use `baseurl` use `root`. ### 3rd Party Settings These third party integrations are already set up for you. Simply fill in the configurations and they'll be added to your site.