updated documentation for code plugins

source/docs/plugins/_partials/options.markdown

@@ -0,0 +1,15 @@
+### Additional options:
+
+These options don't depend on any previous option and order does not matter.
+
+{% if show-range %}
+- `start:#` - Render a snippet from the file beginning at the specified line.
+- `end:#` - Render a snippet from the file ending at the specified line.
+- `range:#-#` - Render a specified range of lines from a file (a shortcut for start:# end:#).
+- `mark:#,#-#` - Mark one or more lines of code with the class name "marked". Accepts one number, numbers separated by commas, and number ranges. Example `mark:1,5-8` will mark lines 1,5,6,7,8. Note: If you've changed the beginning line number be sure these match rendered line numbers 
+- `linenos:false` - Do not add line numbers to highlighted code.
+{% else %}
+- `start:#` - Line numbers begin at # (useful for using snippets to reference longer code).
+- `mark:#,#-#` - Mark one or more lines of code with the class name "marked". Accepts one number, numbers separated by commas, and number ranges. Example `mark:1,5-8` will mark lines 1,5,6,7,8. Note: If you've changed the beginning line number be sure these match rendered line numbers 
+- `linenos:false` - Do not add line numbers to highlighted code.
+{% endif %}

source/docs/plugins/backtick-codeblock/index.markdown

@@ -9,25 +9,35 @@ footer: false
 With the `backtick_codeblock` filter you can use Github's lovely back tick syntax highlighting blocks.
 Simply start a line with three back ticks followed by a space and the language you're using.
 
-#### Syntax
+## Syntax
 
-
+    ``` [language] [title] [url] [link text] [linenos:false] [start:#] [mark:#,#-#]
-    ``` [language] [title] [url] [link text] [start:#]
     code snippet
     ```
+### Basic options
 
+- `[language]` - Used by the syntax highlighter. Passing 'plain' disables highlighting.
+- `[title]` - Add a figcaption to your code block.
+- `[url]` - Download or reference link for your code.
+- `[Link text]` - Text for the link, defaults to 'link'.
 
-#### Example (plain)
+{% render_partial docs/plugins/_partials/options.markdown %}
+
+## Examples
+
+**1.** Here's an example without setting the language.
 
 ```
 $ sudo make me a sandwich
 ```
 
-``` linenos:false
+*The source:*
+
+    ```
     $ sudo make me a sandwich
     ```
 
-#### Example With Syntax Highlighting a Caption and Link
+**2.** This example uses syntax highlighting and a code link.
 
 ``` ruby Discover if a number is prime http://www.noulakaz.net/weblog/2007/03/18/a-regular-expression-to-check-for-prime-numbers/ Source Article
 class Fixnum
@@ -37,6 +47,8 @@ $ sudo make me a sandwich
 end
 ```
 
+*The source:*
+
     ``` ruby Discover if a number is prime http://www.noulakaz.net/weblog/2007/03/18/a-regular-expression-to-check-for-prime-numbers/ Source Article
     class Fixnum
       def prime?
@@ -45,7 +57,7 @@ class Fixnum
     end
     ```
 
-#### Example with a custom starting line number
+**3.** This example uses a custom starting line number and marks lines 52 and 54 through 55.
 
 ``` coffeescript Coffeescript Tricks start:51 mark:52,54-55
 # Given an alphabet:
@@ -55,6 +67,8 @@ end
 console.log letter for letter in alphabet[4..8]
 ```
 
+*The source:*
+
     ``` coffeescript Coffeescript Tricks start:51 mark:52,54-55
     # Given an alphabet:
     alphabet = 'abcdefghijklmnopqrstuvwxyz'
@@ -62,3 +76,7 @@ alphabet = 'abcdefghijklmnopqrstuvwxyz'
     # Iterate over part of the alphabet:
     console.log letter for letter in alphabet[4..8]
     ```
+
+### Other ways to embed code snippets
+
+You might also like to [embed code from a file](/docs/plugins/include-code) or [embed GitHub gists](/docs/plugins/gist-tag).

source/docs/plugins/codeblock/index.markdown

@@ -8,79 +8,87 @@ footer: false
 
 With this plugin you can write blocks of code directly in your posts and optionally add titles and links.
 
-#### Syntax
+## Syntax
 
-    {{ "{% codeblock [title] [lang:language] [start:#] [url] [link text]" }} %}
+    {{ "{% codeblock [lang:language] [title] [url] [link text] [start:#] [mark:#,#-#] [linenos:false]" }} %}
     code snippet
     {{ "{% endcodeblock" }} %}
 
-#### Example 1
+### Basic options
 
-    {{ "{% codeblock" }} %}
+- `[lang:language]` - Choose a language for the syntax highlighter. Passing 'plain' disables highlighting.
-    Awesome code snippet
+- `[title]` - Add a figcaption to your code block.
-    {{ "{% endcodeblock" }} %}
+- `[url]` - Download or reference link for your code.
+- `[link text]` - Text for the link, defaults to 'link'.
+
+{% render_partial docs/plugins/_partials/options.markdown %}
+
+## Examples
+
+**1.** Here's an example without setting the language.
 
 {% codeblock %}
 Awesome code snippet
 {% endcodeblock %}
 
-#### Syntax highlighting
+*The source:*
 
-You can also add syntax highlighting like this.
+    {{ "{% codeblock" }} %}
+    Awesome code snippet
+    {{ "{% endcodeblock" }} %}
 
-    {% raw %}{% codeblock lang:objc %}
+**2.** This example uses syntax highlighting.
-    [rectangle setX: 10 y: 10 width: 20 height: 20];
-    {% endcodeblock %}{% endraw %}
 
 {% codeblock lang:objc %}
 [rectangle setX: 10 y: 10 width: 20 height: 20];
 {% endcodeblock %}
 
-#### Syntax highlighting, alternate method
+*The source:*
 
-Including a file extension in the title enables highlighting
+    {% raw %}{% codeblock lang:objc %}
+    [rectangle setX: 10 y: 10 width: 20 height: 20];
+    {% endcodeblock %}{% endraw %}
 
-    {{ "{% codeblock Time to be Awesome - awesome.rb" }} %}
+**3.** Including a file extension in the title can also trigger highlighting.
-    puts "Awesome!" unless lame
-    {{ "{% endcodeblock" }} %}
 
 {% codeblock Time to be Awesome - awesome.rb %}
 puts "Awesome!" unless lame
 {% endcodeblock %}
 
-#### Force highlighting
+*The source:*
 
-Pygments supports many languages, but doesn't recognize some file extensions.
+    {{ "{% codeblock Time to be Awesome - awesome.rb" }} %}
-Add `lang:your_language` to force highlighting if the filename doesn't work.
+    puts "Awesome!" unless lame
-
-    {{ "{% codeblock Here's an example .rvmrc file. lang:ruby" }} %}
-    rvm ruby-1.8.6 # ZOMG, seriously? We still use this version?
     {{ "{% endcodeblock" }} %}
 
-{% codeblock Here's an example .rvmrc file. lang:ruby %}
-rvm ruby-1.8.6 # ZOMG, seriously? We still use this version?
-{% endcodeblock %}
 
-#### Add a URL
+**4.** Add an optional URL for downloading or linking to a source.
-
-Add an optional URL to enable downloading or linking to source.
-
-    {% raw %}{% codeblock Javascript Array Syntax lang:js http://j.mp/pPUUmW MDN Documentation %}
-    var arr1 = new Array(arrayLength);
-    var arr2 = new Array(element0, element1, ..., elementN);
-    {% endcodeblock %}{% endraw %}
 
 {% codeblock Javascript Array Syntax lang:js http://j.mp/pPUUmW MDN Documentation %}
 var arr1 = new Array(arrayLength);
 var arr2 = new Array(element0, element1, ..., elementN);
 {% endcodeblock %}
 
-The last argument `link_text` is optional. You may want to link to a source for download file, or documentation on some other site.
+*The source:*
 
+    {% raw %}{% codeblock Javascript Array Syntax lang:js http://j.mp/pPUUmW MDN Documentation %}
+    var arr1 = new Array(arrayLength);
+    var arr2 = new Array(element0, element1, ..., elementN);
+    {% endcodeblock %}{% endraw %}
 
-#### Start on a custom line number
+**5.** This example uses a custom starting line number and marks lines 52 and 54 through 55.
 
-    {% raw %}{% codeblock Coffeescript Tricks lang:coffeescript start:51 %}
+{% codeblock lang:coffeescript Coffeescript Tricks start:51 mark:51,54-55 %}
+# Given an alphabet:
+alphabet = 'abcdefghijklmnopqrstuvwxyz'
+
+# Iterate over part of the alphabet:
+console.log letter for letter in alphabet[4..8]
+{% endcodeblock %}
+
+*The source:*
+
+    {% raw %}{% codeblock Coffeescript Tricks lang:coffeescript start:51 mark:51,54-55 %}
     # Given an alphabet:
     alphabet = 'abcdefghijklmnopqrstuvwxyz'
 
@@ -88,10 +96,6 @@ The last argument `link_text` is optional. You may want to link to a source for
     console.log letter for letter in alphabet[4..8]
     {% endcodeblock %}{% endraw %}
 
-{% codeblock lang:coffeescript Coffeescript Tricks start:51 %}
+### Other ways to embed code snippets
-# Given an alphabet:
-alphabet = 'abcdefghijklmnopqrstuvwxyz'
 
-# Iterate over part of the alphabet:
+You might also like to [use back tick code blocks](/docs/plugins/backtick-codeblock), [embed code from a file](/docs/plugins/include-code), or [embed GitHub gists](/docs/plugins/gist-tag).
-console.log letter for letter in alphabet[4..8]
-{% endcodeblock %}

source/docs/plugins/include-code/index.markdown

@@ -11,52 +11,65 @@ Import files on your filesystem into any blog post as embedded code snippets wit
 In the `_config.yml` you can set your `code_dir` but the default is `source/downloads/code`. Simply put a file anywhere under that directory and
 use the following tag to embed it in a post.
 
-### Syntax
+## Syntax
 
-    {{ "{% include_code [title] [lang:language] path/to/file [start:#] [end:#] [range:#,#]" }} %}
+    {{ "{% include_code [title] [lang:language] path/to/file [start:#] [end:#] [range:#-#] [mark:#,#-#] [linenos:false]" }} %}
 
-### Basic Example
+### Basic options
-This includes a file from `source/downloads/code/test.js`.
 
-    {{ "{% include_code test.js" }} %}
+- `[title]` - Add a custom figcaption to your code block (defaults to filename).
+- `lang:language` - Force the syntax highlighter to use this language. By default the file extension is used for highlighing, but not all extensions are known by Pygments.
+
+{% assign show-range = true %}
+{% render_partial docs/plugins/_partials/options.markdown %}
+
+## Examples
+
+**1.** This code snipped was included from `source/downloads/code/test.js`.
 
 {% include_code test.js %}
 
-### Custom title
+*The source:*
-By default the `<figcaption>` will be the filename, but you can add a title before the filepath if you like.
 
-    {{ "{% include_code Add to_fraction for floats ruby/test.rb" }} %}
+    {{ "{% include_code test.js" }} %}
+
+**2.** Setting a custom caption.
+
+{% include_code ruby/test.rb Add to_fraction for floats %}
+
+*The source:*
+
+    {{ "{% ruby/test.rb include_code Add to_fraction for floats" }} %}
 
 This includes a file from `source/downloads/code/ruby/test.rb`.
 
-{% include_code Add to_fraction for floats ruby/test.rb %}
 
-### Include part of a file
+### Including part of a file
 
-Start on line a specific line.
+**3.** Embed a file starting from a specific line.
-
-    {% raw %}{% include_code test.js start:10 %}{% endraw %}
 
 {% include_code test.js start:10 %}
 
-End on line a specific line.
+*The source:* 
 
-    {% raw %}{% include_code test.js end:10 %}{% endraw %}
+    {% raw %}{% include_code test.js start:10 %}{% endraw %} 
+
+**4.** Embed a file ending at a specific line.
 
 {% include_code test.js end:10 %}
 
-Choose a custom range of lines to include.
+*The source:*
 
-    {% raw %}{% include_code test.js range:10,15 %}{% endraw %}
+    {% raw %}{% include_code test.js end:10 %}{% endraw %}
 
-{% include_code test.js range:10,15 %}
+**5.** Display only the lines in a specific range.
 
-### Force highlighting
+{% include_code test.js range:5-16 %}
 
-Pygments supports many languages, but doesn't recognize some file extensions.
+*The source:*
-Add `lang:your_language` to force highlighting if the filename doesn't work.
 
-    {{ "{% include_code test.coffee lang:coffeescript" }} %}
+    {% raw %}{% include_code test.js range:5-16 %}{% endraw %}
 
-{% include_code test.coffee lang:coffeescript %}
+### Other ways to embed code snippets
 
+You might also like to [use back tick code blocks](/docs/plugins/backtick-codeblock) or [embed GitHub gists](/docs/plugins/gist-tag).