From df0918b2ee8162803faf1803851190f20aa3970b Mon Sep 17 00:00:00 2001 From: Brandon Mathis Date: Mon, 1 Aug 2011 17:38:25 -0400 Subject: [PATCH] improve docs for theming --- source/docs/configuring/index.markdown | 2 +- source/docs/theming/_template.markdown | 64 +++++++++++++++++++++++--- 2 files changed, 59 insertions(+), 7 deletions(-) diff --git a/source/docs/configuring/index.markdown b/source/docs/configuring/index.markdown index dbb6fc0..2202a86 100644 --- a/source/docs/configuring/index.markdown +++ b/source/docs/configuring/index.markdown @@ -65,7 +65,7 @@ If you want to change the way permalinks are written for your blog posts, see [J to use the WEBrick server, but for any other web service you have to add support for the redirect. Instead, Octopress uses the `root` config and offers a rake task `set_root_dir[/some/directory]` which moves the output directory into a subdirectory and updates configurations. [(see Deploying Octopress)](/docs/deploying). -### 3rd Party Settings +

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. - **Twitter** - Setup a sidebar twitter feed, follow button, and tweet button (for sharing posts and pages). diff --git a/source/docs/theming/_template.markdown b/source/docs/theming/_template.markdown index 28ddad6..74ee2c9 100644 --- a/source/docs/theming/_template.markdown +++ b/source/docs/theming/_template.markdown @@ -1,4 +1,4 @@ -The key source directories are as follows: +Shortly after the 2.0 release Octopress added the `source/_includes/custom` directory. If you don't have this, you'll want to [update](/docs/updating) because it's really nice. source/ _includes/ # Main layout partials @@ -7,10 +7,62 @@ The key source directories are as follows: post/ # post metadata, sharing & comment partials _layouts/ # layouts for pages, posts & category archives -It's pretty likely you'll create pages and want to add them to the main navigation partial. In the latest (version 2.1) To do that +### Changing the sidebar +Octopress integrates with some [3rd party services](/docs/configuring/#third_party) like Twitter, Pinboard and Delicious which appear in the sidebar. +In the `_config.yml` you can rearrange these, create custom sidebars for each layout, and add your own sidebar sections. -Beyond that, I don't expect there to be a great need to change the markup very much, since the HTML is flexible and semantic and most common -customizations be taken care of [with configuration](/docs/configuring). +{% codeblock Sidebar configuration (_config.yml) %} +default_asides: [asides/recent_posts.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html] +# blog_index_asides: +# post_asides: +# page_asides: +{% endcodeblock %} -If you study the layouts and partials, you'll see that there's a lot of conditional markup. Logic in the view is lamentable, but a necessary -side effect of simple static site generation. +If you want to add a section to your sidebar, create a new file in `source/_includes/custom/asides/`. +Since many people probably want to add an About Me section, there's already an `about.html` file in there waiting to be added. Here's a look. + +{% codeblock About Me (source/_includes/custom/asides/about.html) %} +{% render_partial ../.themes/classic/source/_includes/custom/asides/about.html raw %} +{% endcodeblock %} + +Whenever you add a section to the sidebar, follow this pattern, with a `
` block and an `

` for a title. To add it to the sidebar, edit the `_config.yml` and add it to the list of asides. + +{% codeblock Sidebar configuration (_config.yml) %} +default_asides: [asides/recent_posts.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html] +blog_index_asides: [custom/asides/about.html, asides/recent_posts.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html] +post_asides: [custom/asides/about.html, asides/recent_posts.html, asides/twitter.html, asides/delicious.html, asides/pinboard.html] +# page_asides: +{% endcodeblock %} + +In the configuration above I've added the about page to the blog index and post pages. Since `page_asides` isn't being set, it will inherit from the default list. + +### Changing the <HEAD> + +If you want to add to the ``take a look at `/source/_includes/custom/head.html`. + +{% codeblock <HEAD> (source/_includes/custom/head.html) %} +{% render_partial ../.themes/classic/source/_includes/custom/head.html raw %} +{% endcodeblock %} + +Here you can easily change or remove the [Google Webfonts](http://google.com/webfonts), insert javascripts, etc. + +### Changing the Navigation + +As soon as you add pages to your site, you'll want to put them in the main navigation. The links come from `/source/_includes/custom/navigation.html` which looks like this: + +{% codeblock Navigation (source/_includes/custom/navigation.html) %} +{% render_partial ../.themes/classic/source/_includes/custom/navigation.html raw %} +{% endcodeblock %} + +The `href` for each link begins with `{% raw %}{{ root_url }}{% endraw %}` (this helps Octopress write urls differently if a site is deployed to a subdirectory). +If you're deploying your site to a subdirectory like `yoursite.com/octopress` you'll want to add this to any links you add. + +### Changing the Footer + +You can customize the footer in `source/_includes/custom/footer.html` which looks like this: + +{% codeblock Footer (source/_includes/custom/footer.html) %} +{% render_partial ../.themes/classic/source/_includes/custom/footer.html raw %} +{% endcodeblock %} + +Change this however you like, but if you're cool, you'll leave the Octopress link in there.