diff --git a/source/docs/blogging/code/index.markdown b/source/docs/blogging/code/index.markdown index 7c99583..abd70a5 100644 --- a/source/docs/blogging/code/index.markdown +++ b/source/docs/blogging/code/index.markdown @@ -36,3 +36,6 @@ Check out the [test page](/docs/blogging/code/test) to see the results. ## Inline Code Blocks {% render_partial docs/plugins/codeblock/index.markdown %} + +Also, see [Blogging with Plugins](/docs/blogging/plugins) and [The Octopress plugins page](/docs/plugins) + diff --git a/source/docs/blogging/index.markdown b/source/docs/blogging/index.markdown index 85ba4ff..2927149 100644 --- a/source/docs/blogging/index.markdown +++ b/source/docs/blogging/index.markdown @@ -7,6 +7,8 @@ comments: false footer: false --- +[« Previous, Updating Octopress](/docs/updating) + Octopress offers some rake tasks to create post and pages preloaded with metadata and according to Jekyll's naming conventions. ## Blog Posts @@ -86,4 +88,4 @@ Jekyll's built in WEBrick server is handy, but if you're a [POW](http://pow.cx) Now that you're setup with POW, you'll just run `rake watch` and load up `http://octopress.dev` instead. -[Next, Sharing Code Snippets »](/docs/blogging/code) +Also, see [Sharing Code Snippets](/docs/blogging/code) and [Blogging with Plugins](/docs/blogging/plugins) diff --git a/source/docs/blogging/plugins/index.markdown b/source/docs/blogging/plugins/index.markdown index 7a2eb7e..b7487f3 100644 --- a/source/docs/blogging/plugins/index.markdown +++ b/source/docs/blogging/plugins/index.markdown @@ -9,12 +9,11 @@ footer: false There are [other plugins](/docs/plugins) for octopress, but here's an overview of the ones you'll be likely to use while blogging. This is mainly a description and demo, so be sure to follow the links beneath each section for examples and documentation. -## Excerpt Filter +## HTML5 Video Tag +This plugin makes it easy to insert mp4 encoded HTML5 videos in a post. Octopress ships with javascripts which +detect mp4 video support ([using Modernizr](http://modernizr.com)) and automatically offer a flash player fallback. -When writing a post, you can add an HTML comment `` to split the post for an excerpt. Only the first section of the post, before the comment, -will show up on the blog index. - -This filter is used in `source/_includes/article.html` +[Examples & documentation »](/docs/plugins/video-tag/) ## Image Tag This plugin makes it easy to insert images in a post, with optional class names, alt and title attributes. @@ -69,3 +68,12 @@ Import files on your file system into any blog post or page. For example, to emb {{ "{% render_partial docs/blogging/plugins/index.markdown" }} %} [Examples & documentation »](/docs/plugins/render-partials/) + +Also see the [Octopress Plugin page](/docs/plugins) for more plugins. + +## Excerpt Filter +When writing a post, you can add an HTML comment `` to split the post for an excerpt. Only the first section of the post, before the comment, +will show up on the blog index. + +This filter is used in `source/_includes/article.html` + diff --git a/source/docs/deploying/index.markdown b/source/docs/deploying/index.markdown index 4a0278d..7485863 100644 --- a/source/docs/deploying/index.markdown +++ b/source/docs/deploying/index.markdown @@ -80,4 +80,4 @@ Here's an example for deploying the Octopress website to Github Project Pages: For more info on deploying a Jekyll Blog, checkout [Jekyll's deployment wiki page](https://github.com/mojombo/jekyll/wiki/Deployment). -[Next, Blogging With Octopress »](/docs/blogging) +[Next, Theming & Customization »](/docs/theming) diff --git a/source/docs/index.markdown b/source/docs/index.markdown index 2a68f41..4208222 100644 --- a/source/docs/index.markdown +++ b/source/docs/index.markdown @@ -12,11 +12,13 @@ the documentation and if you have trouble, [I'll be happy to help](http://convor [post an issue](https://github.com/imathis/octopress/issues) or fork and send a pull request on the [site branch](https://github.com/imathis/octopress/tree/site). ## Getting Started -If you're using bundler and rvm, this should be a breeze. +This section will help you get set up, and explain how to configure Octopress for your site. - [Initial setup](/docs/setup) - *get source and install dependencies* - [Basic Configuration](/docs/configuring) - *enable third party services and personalize your blog* - [Deploying Octopress](/docs/deploying) - *simple deploy instructions for Rsync and Github pages* +- [Theming & Customization](/docs/theming) - *guide to making changes to your Octopress theme* +- [Updating Octopress](/docs/updating) - *a guide to help you stay current with Octopress* ## Using Octopress Your blog should be awesome. This should help. @@ -25,8 +27,6 @@ Your blog should be awesome. This should help. - [Sharing Code Snippets](/docs/blogging/code) - *share code snippets with ease* - [Syntax Highlighting Test](/docs/blogging/code/test) - *language highlighting tests* - [Blogging With Plugins](/docs/blogging/plugins) - *overview of plugins for blogging* -- TODO [Theming & Customization](/docs/theming) - *guide to making changes to your Octopress theme* -- TODO [Updating](/docs/updating) - *a guide to help you stay up to date* ## Octopress Plugins - Usage & Examples {% render_partial docs/plugins/index.markdown %} diff --git a/source/docs/plugins/image-tag/index.markdown b/source/docs/plugins/image-tag/index.markdown index 2f57aea..58fc3a5 100644 --- a/source/docs/plugins/image-tag/index.markdown +++ b/source/docs/plugins/image-tag/index.markdown @@ -6,7 +6,7 @@ sidebar: false footer: false --- -If you like Markdown's simple syntax for images, you'll love the simplicity of the Octopress image tag. +If you like Markdown's syntax for images, you'll love the simplicity of the Octopress image tag. #### Syntax @@ -27,4 +27,6 @@ Aliquip nulla do tempor, ball tip dolore anim esse strip steak nisi nostrud. Tri Brisket quis velit bresaola. Pork loin pork chop beef duis. Short loin fugiat officia short ribs magna. Ullamco eu proident jerky, fugiat chuck nostrud ham rump meatloaf eiusmod adipisicing. Qui et reprehenderit, magna biltong consequat short ribs pancetta. Tail tenderloin sausage, hamburger corned beef drumstick ad. Eu labore enim velit. -Filler text courtesy of [Bacon Ipsum](http://baconipsum.com). +Filler text courtesy of [Bacon Ipsum](http://baconipsum.com), Images courtesy of [Place Kitten](http://placekitten.com). + +[« Plugins page](/docs/plugins) diff --git a/source/docs/plugins/index.markdown b/source/docs/plugins/index.markdown index 12cd2de..dfa97d3 100644 --- a/source/docs/plugins/index.markdown +++ b/source/docs/plugins/index.markdown @@ -9,11 +9,12 @@ footer: false Octopress ships with the following plugins. Many have been written specially for Octopress, but some have been selected from the Jekyll community with various changes and improvements. +- [HTML5 Video Tag](/docs/plugins/video-tag) - *easily post images with class names and titles* - [Code Block](/docs/plugins/codeblock) - *for easy inline code sharing* - [Include Code](/docs/plugins/include-code) - *embed code from your filesystem* - [Gist Tag](/docs/plugins/gist-tag) - *automatically downloads and embeds Github gists* -- [Render Partial](/docs/plugins/render-partial) - *insert any file into another post or page* - [Image Tag](/docs/plugins/image-tag) - *easily post images with class names and titles* +- [Render Partial](/docs/plugins/render-partial) - *insert any file into another post or page* - [Blockquote](/docs/plugins/blockquote) - *generate beautiful, semantic block quotes* - [Pullquote](/docs/plugins/pullquote) - *generate CSS only pull quotes — no duplicate data, no javascript* - [Category Generator](/docs/plugins/category-generator) - *generates archive pages for each blog category* diff --git a/source/docs/plugins/pullquote/index.markdown b/source/docs/plugins/pullquote/index.markdown index bdd533c..64c44fe 100644 --- a/source/docs/plugins/pullquote/index.markdown +++ b/source/docs/plugins/pullquote/index.markdown @@ -23,3 +23,5 @@ It is important to note that {" pull quotes are merely visual in presentation an **Inspect the source** and you'll see the pulled content appears in the data-pullquote attribute of the paragraph. The pull quote effect is created entirely with CSS, and is supported by all modern browsers as well as IE8 and up. + +[« Plugins page](/docs/plugins) diff --git a/source/docs/plugins/render-partial/index.markdown b/source/docs/plugins/render-partial/index.markdown index 38ea989..a0c2be6 100644 --- a/source/docs/plugins/render-partial/index.markdown +++ b/source/docs/plugins/render-partial/index.markdown @@ -26,3 +26,5 @@ beginning of the file name, or put it in a directory that begins with an undersc Any post or page could import this file like this: {{ "{% render_partial documentation/TOC.markdown" }} %} + +[« Plugins page](/docs/plugins) diff --git a/source/docs/plugins/video-tag/index.markdown b/source/docs/plugins/video-tag/index.markdown new file mode 100644 index 0000000..c8b1cd2 --- /dev/null +++ b/source/docs/plugins/video-tag/index.markdown @@ -0,0 +1,23 @@ +--- +layout: page +title: "Video Tag" +date: 2011-07-23 17:34 +sidebar: false +footer: false +--- + +This plugin makes it easy to insert mp4 encoded HTML5 videos in a post. Octopress ships with javascripts which +detect mp4 video support ([using Modernizr](http://modernizr.com)) and automatically offer a flash player fallback. + +#### Syntax + + {{ "{% video url/to/video [width height] [url/to/poster]" }} %} + +#### Demo + +{% video http://s3.imathis.com/video/zero-to-fancy-buttons.mp4 640 320 http://s3.imathis.com/video/zero-to-fancy-buttons.png %} + +

You're probably using a browser which supports HTML5 video and you're looking at this page wondering if it really works. +Reloading the page with the url hash #flash-test and you'll get to see the flash player fallback.

+ +[« Plugins page](/docs/plugins) diff --git a/source/docs/setup/index.markdown b/source/docs/setup/index.markdown index 6732f4f..58921d3 100644 --- a/source/docs/setup/index.markdown +++ b/source/docs/setup/index.markdown @@ -42,4 +42,4 @@ and you should be all set up to begin blogging with Octopress. **Note:** If you already have a blog, check out [Jekyll's Migration page](https://github.com/mojombo/jekyll/wiki/blog-migrations) to help you get your content formatted for Jekyll blogging. -[Next, Deploying Octopress »](/docs/deploying) +[Next, Deploying Octopress »](/docs/configuring) diff --git a/source/docs/theming/index.markdown b/source/docs/theming/index.markdown index 5f33c80..0a4d7e6 100644 --- a/source/docs/theming/index.markdown +++ b/source/docs/theming/index.markdown @@ -6,4 +6,85 @@ sidebar: false footer: false --- -WooHoo! +[« Previous, Deploying Octopress](/docs/deploying) + +I hope to eventually release more themes, but for now Octopress ships with a single theme comprised of layouts, partials, pages, javascripts, and +Sass stylesheets located in `.themes/classic/source` and `.themes/classic/sass`. +When you install the Octopress theme, these directories are copied into `/source` and `/sass`. You are free to make any changes you like, +but I've set up a few patterns to make it easy to customize your site. + +## Customizing Styles + +For stylesheet customizations, check out the `/sass/custom` directory and you'll find three files. + + _colors.scss # Change the color scheme + _layout.scss # Make simple changes to the layout + _styles.scss # Easly Override any style + +### Changing the Color Scheme + +All of the colors for Octopress are defined in `/sass/base/_theme.scss` and the variables are used throughout the other stylesheets. Here's +a look at the navigation section of the theme. + +{% codeblock Navigation (_theme.scss) https://github.com/imathis/octopress/tree/master/.themes/classic/sass/base/_theme.scss view on Github %} +/* Navigation */ +$nav-bg: #ccc !default; +$nav-color: darken($nav-bg, 38) !default; +$nav-color-hover: darken($nav-color, 25) !default; +... +{% endcodeblock %} + +The `!default` means that if the color has already been defined it will use that value instead and since `custom/_colors.scss` +is imported before the `_theme.scss` it can predefine these colors easily. There are comments to help out with this in the +[source](https://github.com/imathis/octopress/tree/master/.themes/classic/sass/custom/_colors.scss). + +Many of the colors in the theme are picked using [Sass's color functions](http://sass-lang.com/docs/yardoc/Sass/Script/Functions.html). +As a result you can pick a new background color for the navigation by setting the `$nav-bg` variable +and the other colors will derived for you. This isn't perfect, but it should do a decent job with most colors. + +### Changing Layout Sizes & Padding + +Just like with colors, widths in `/sass/base/_layout.scss` are defined like `$max-width: 1200px !default;` and can be easily customized +by defining them in `sass/custom/_layout.scss`. Here's a look at the layout defaults. + +{% codeblock Layout Defaults (_layout.scss) https://github.com/imathis/octopress/tree/master/.themes/classic/sass/base/_theme.scss view on Github %} +$max-width: 1200px !default; + +// Padding used for layout margins +$pad-min: 18px !default; +$pad-narrow: 25px !default; +$pad-medium: 35px !default; +$pad-wide: 55px !default; + +// Sidebar widths used in media queries +$sidebar-width-medium: 240px !default; +$sidebar-pad-medium: 15px !default; +$sidebar-pad-wide: 20px !default; +$sidebar-width-wide: 300px !default; + +$indented-lists: false !default; +{% endcodeblock %} + +These variables are used to calculate the width and padding for the responsive layouts. The `$indented-lists` variable allows you to +choose if you prefer indented or normal lists. + +### Overriding Styles +If you want to add or override styles, edit `sass/custom/_styles.css`. This stylesheet is imported last, so you can override styles with the cascade. + +## Customizing Layouts & Partials +The key source directories are as follows: + + source/ + _includes/ # main layout partials + asides/ # sidebar partials + 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 at `source/_includes/navigation.html`. +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). + +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. + +[Next, Updating Your Blog »](/docs/updating) diff --git a/source/docs/updating/index.markdown b/source/docs/updating/index.markdown index 34579ee..18f703c 100644 --- a/source/docs/updating/index.markdown +++ b/source/docs/updating/index.markdown @@ -1,7 +1,57 @@ --- layout: page -title: "Updating" +title: "Updating Octopress" date: 2011-07-22 19:46 sidebar: false footer: false --- + +[« Previous, Theming & Customization](/docs/theming) + +In the open source world, version control generally takes care of staying current with the latest releases, but once you've begun to customize your code, +merging in updates isn't always what you want. As a result I've come up with the following pattern for Octopress: + +1. Plugins, configs, gemfiles, `.themes`, `.gitignore` and the `Rakefile` are all tracked for easy to updating and collaborating. + +2. The install process copies layouts, pages, javascripts, and styles out of the `.themes` directory. Once you've installed a theme, none of the +files under `source` or `sass` are in any repository except your own. This way you can change them to your liking without worrying about merging in +updates and screwing up your changes. + +When you pull down changes from the Octopress repository, the latest layouts, pages, javascripts and styles are merged into your `.themes` directory. +To update your site, you must manually merge in the new files. Before you do a spit-take, I came up with something to help out with this. + +## Updating Sass +If you've pulled in changes and you want to update your `/sass` directory, run this. + + rake update_style + +This task will: + +1. Move `/sass` to `/sass.old` +2. Copy `.themes/classic/sass` to `/sass` +3. Replace `/sass/custom/` with `/sass.old/custom/` + +This way if you keep your theme changes in `/sass/custom` you'll be able to upgrade your stylesheets without losing any of your work. If you made changes elsewhere, you can copy them back them from `/sass.old`. +After you have the update in place, you can remove the `/sass.old` directory. + +## Updating Source +If you've pulled in changes and you want to update your `/source` directory, run this. + + rake update_source + +This task will: + +1. Move `/source` to `/source.old` +2. Copy `.themes/classic/source` to `/source` +3. Copy back everything in `/source.old` (`cp -rn` - without replacing ) +4. Replace `/source/_includes/navigation.html` with `/source.old/_includes/navigation.html` (because it commonly has changes). + +This way all of the files you've added, eg. `_posts`, `about.html` etc. will be preserved while all files tracked by Octopress (except for the navigation partial) will be updated. +If you made changes elsewhere, you can copy them back them from `/source.old`. After you have the update in place, you can remove the `/source.old` directory. + +## That's It? + +Yep. I figured this is the simplest thing that could possibly work. I don't like the idea of having blog files change if someone wants to update their plugins, +and I haven't yet figured out a better way. If you have a better idea, I'd love some [help](http://convore.com/octopress/ideas) improving this. + +[Next, Blogging With Octopress »](/docs/blogging) diff --git a/source/test/video.html b/source/test/video.html index 5326b1d..c2236b3 100644 --- a/source/test/video.html +++ b/source/test/video.html @@ -4,9 +4,7 @@ footer: false title: HTML5 Video + Flash Replcement test --- - +{% video http://s3.imathis.com/video/zero-to-fancy-buttons.mp4 640 320 http://s3.imathis.com/video/zero-to-fancy-buttons.png %}

You're probably using a browser which supports HTML5 video and you're looking at this page wondering if it really works. Reloading the page with the url hash #flash-test and you'll get to see the flash player fallback.