From 39b31a055305013a9691afc52b3d88bdca418267 Mon Sep 17 00:00:00 2001 From: Brandon Mathis Date: Fri, 22 Jul 2011 18:36:49 -0400 Subject: [PATCH] updated documentation for plugins --- source/docs/blogging/plugins/index.markdown | 36 +++++++++++++++++-- source/docs/index.markdown | 21 +++-------- source/docs/plugins/codeblock/index.markdown | 2 +- source/docs/plugins/index.markdown | 25 +++++++++++++ .../plugins/render-partial/index.markdown | 26 ++++++++++++-- 5 files changed, 87 insertions(+), 23 deletions(-) create mode 100644 source/docs/plugins/index.markdown diff --git a/source/docs/blogging/plugins/index.markdown b/source/docs/blogging/plugins/index.markdown index 54b1318..8669c7e 100644 --- a/source/docs/blogging/plugins/index.markdown +++ b/source/docs/blogging/plugins/index.markdown @@ -12,10 +12,9 @@ footer: false Give a man a fish, he'll have food for a day. Teach a man to fish, and he'll always come to you with his fishing problems. {% endblockquote %} -[Examples & documentation »](/docs/plugins/blockquotes/) +[Examples & documentation »](/docs/plugins/blockquote/) ## Pull quote - Octopress offers a CSS3 only technique for pull quotes, based on the technique by [Maykel Loomans](http://miekd.com/articles/pull-quotes-with-html5-and-css/). {% pullquote %} @@ -23,4 +22,35 @@ When writing longform posts, I find it helpful to include pull quotes to help re It is important to note that {" pull quotes are merely visual in presentation and should not appear twice in the text. "} That is why it a CSS only technique for styling pull quotes is preferable. Octopress includes a handy pull quote plugin to make this easy for you. {% endpullquote %} -[Examples & documentation »](/docs/plugins/blockquotes/) +[Examples & documentation »](/docs/plugins/pullquote/) + +## Code Blocks +Write blocks of code directly in your posts and optionally add titles and links. + +{% codeblock Javascript Array Syntax (array.js) https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array MDN Documentation %} +var arr1 = new Array(arrayLength); +var arr2 = new Array(element0, element1, ..., elementN); +{% endcodeblock %} + +[Examples & documentation »](/docs/plugins/codeblock/) + +## Gist Tag +Easily embed gists in your posts or pages. + + {{ "{% gist 996818" }} %} + +[Examples & documentation »](/docs/plugins/gist-tag/) + +## Include Code +Import files on your filesystem into any blog post as embedded code snippets with syntax highlighting and a download link. + +{% include_code Testing include_code javascripts/test.js %} + +[Examples & documentation »](/docs/plugins/include-code/) + +## Render Partial +Import files on your file system into any blog post or page. For example, to embed this page in another post I'd use the following code. + + {{ "{% render_partial docs/blogging/plugins/index.markdown" }} %} + +[Examples & documentation »](/docs/plugins/render-partials/) diff --git a/source/docs/index.markdown b/source/docs/index.markdown index 3c50e7f..6347ca5 100644 --- a/source/docs/index.markdown +++ b/source/docs/index.markdown @@ -12,12 +12,14 @@ 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. - [Initial setup](/docs/setup) - Get source and install dependencies -- [Basic Configuration](/docs/configuring) - A descriptive list of configurations +- [Basic Configuration](/docs/configuring) - Enable third party services and personalize your blog - [Deploying Octopress](/docs/deploying) - Simple deploy instructions for Rsync and Github pages ## Using Octopress -- [Blogging Basics](/docs/blogging) - Creating blog posts and pages +Your blog should be awesome. This should help. +- [Blogging Basics](/docs/blogging) - How to create blog posts and pages - [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 @@ -25,17 +27,4 @@ the documentation and if you have trouble, [I'll be happy to help](http://convor - TODO [Updating](/docs/updating) - A guide to help you stay up to date ## Octopress Plugins - Usage & Examples -- [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. -- [Figure Tag](/docs/plugins/figure-tag) - Easily post images with semantic <figure> & <figcaption> elements -- [Blockquote](/docs/plugins/blockquote) - Generate beautiful, semantic block quotes -- [Pullquote](/docs/plugins/pullquote) - Generate CSS only pull quotes — no duplicate data, no javascript. -- [Custom filters](/docs/plugins/octopress-filters) - Liquid filters built just for Octopress -- [Category Generator](/docs/plugins/category-generator) - Generates archive pages for each blog category -- Sitemap Generator - Generates an SEO friendly sitemap.xml -- Compass Compiler - Forces Jekyll to compile Compass on each load -- Haml Converter - Allows .haml pages to be processed by Jekyll -- Pygments Cache - Caches code snippets to speed up Jekyll processing -- Titlecase - Required by several plugins to automatically generate proper title captalization +{% render_partial docs/plugins/index.markdown %} diff --git a/source/docs/plugins/codeblock/index.markdown b/source/docs/plugins/codeblock/index.markdown index 2a6a104..fe42711 100644 --- a/source/docs/plugins/codeblock/index.markdown +++ b/source/docs/plugins/codeblock/index.markdown @@ -6,7 +6,7 @@ sidebar: false footer: false --- -With this plugin you can write blocks of code directly in your posts and optionally add titles or links. +With this plugin you can write blocks of code directly in your posts and optionally add titles and links. #### Syntax diff --git a/source/docs/plugins/index.markdown b/source/docs/plugins/index.markdown new file mode 100644 index 0000000..903bb4d --- /dev/null +++ b/source/docs/plugins/index.markdown @@ -0,0 +1,25 @@ +--- +layout: page +title: "Octopress Plugins - Usage & Examples" +date: July 18 2011 +sidebar: false +comments: false +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. + +- [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. +- [Figure Tag](/docs/plugins/figure-tag) - Easily post images with semantic <figure> & <figcaption> elements +- [Blockquote](/docs/plugins/blockquote) - Generate beautiful, semantic block quotes +- [Pullquote](/docs/plugins/pullquote) - Generate CSS only pull quotes — no duplicate data, no javascript. +- [Custom filters](/docs/plugins/octopress-filters) - Liquid filters built just for Octopress +- [Category Generator](/docs/plugins/category-generator) - Generates archive pages for each blog category +- Sitemap Generator - Generates an SEO friendly sitemap.xml +- Compass Compiler - Forces Jekyll to compile Compass on each load +- Haml Converter - Allows .haml pages to be processed by Jekyll +- Pygments Cache - Caches code snippets to speed up Jekyll processing +- Titlecase - Required by several plugins to automatically generate proper title captalization diff --git a/source/docs/plugins/render-partial/index.markdown b/source/docs/plugins/render-partial/index.markdown index 93dd78e..38ea989 100644 --- a/source/docs/plugins/render-partial/index.markdown +++ b/source/docs/plugins/render-partial/index.markdown @@ -2,7 +2,27 @@ layout: page title: "Render Partial" date: 2011-07-22 09:14 -comments: true -sharing: true -footer: true +sidebar: false +footer: false --- + +Import files on your file system into any blog post or page. As a best practice, be sure these files are included in your site's repository. + +#### Syntax + + {{ "{% render_partial path/to/file" }} %} + +The `render_partial` tag resolves paths to the `source` directory, so write your paths accordingly. + +#### Example Usage 1 +Perhaps you want to create a readme page for your blog. You have a file at `source/readme/index.markdown` and the `README.markdown` for your project is +a sibling to your source directory. To import your project's readme into your readme page, you'd do this: + + {{ "{% render_partial ../README.markdown" }} %} + +#### Example Usage 2 +You may have two pages which need to share some of the same content. To prevent your partial from being rendered by Jekyll as a page, add an underscore to the +beginning of the file name, or put it in a directory that begins with an underscore. For example, if you wanted multiple pages to share a table of contents, you might create `source/documentation/_partials/TOC.markdown`. +Any post or page could import this file like this: + + {{ "{% render_partial documentation/TOC.markdown" }} %}