From 758687f9bd5bf8a427d8521b7fdb1d347db23939 Mon Sep 17 00:00:00 2001 From: Brandon Mathis Date: Sun, 3 Jun 2012 00:24:03 -0500 Subject: [PATCH] updated documentation for code plugins --- .../docs/plugins/_partials/options.markdown | 15 ++++ .../plugins/backtick-codeblock/index.markdown | 66 +++++++++----- source/docs/plugins/codeblock/index.markdown | 88 ++++++++++--------- .../docs/plugins/include-code/index.markdown | 59 ++++++++----- 4 files changed, 139 insertions(+), 89 deletions(-) create mode 100644 source/docs/plugins/_partials/options.markdown diff --git a/source/docs/plugins/_partials/options.markdown b/source/docs/plugins/_partials/options.markdown new file mode 100644 index 0000000..7ac3601 --- /dev/null +++ b/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 %} diff --git a/source/docs/plugins/backtick-codeblock/index.markdown b/source/docs/plugins/backtick-codeblock/index.markdown index bbdf207..6b05f58 100644 --- a/source/docs/plugins/backtick-codeblock/index.markdown +++ b/source/docs/plugins/backtick-codeblock/index.markdown @@ -9,33 +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] [start:#] + ``` [language] [title] [url] [link text] [linenos:false] [start:#] [mark:#,#-#] 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 +``` + +*The source:* ``` $ sudo make me a sandwich ``` -``` linenos:false -$ sudo make me a sandwich -``` - -#### Example With Syntax Highlighting a Caption and 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 - def prime? - ('1' * self) !~ /^1?$|^(11+?)\1+$/ - end - end - ``` +**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 @@ -45,7 +47,27 @@ class Fixnum end ``` -#### Example with a custom starting line number +*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? + ('1' * self) !~ /^1?$|^(11+?)\1+$/ + end + end + ``` + +**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: +alphabet = 'abcdefghijklmnopqrstuvwxyz' + +# Iterate over part of the alphabet: +console.log letter for letter in alphabet[4..8] +``` + +*The source:* ``` coffeescript Coffeescript Tricks start:51 mark:52,54-55 # Given an alphabet: @@ -55,10 +77,6 @@ end console.log letter for letter in alphabet[4..8] ``` -``` coffeescript Coffeescript Tricks start:51 mark:52,54-55 -# Given an alphabet: -alphabet = 'abcdefghijklmnopqrstuvwxyz' +### Other ways to embed code snippets -# Iterate over part of the alphabet: -console.log letter for letter in alphabet[4..8] -``` +You might also like to [embed code from a file](/docs/plugins/include-code) or [embed GitHub gists](/docs/plugins/gist-tag). diff --git a/source/docs/plugins/codeblock/index.markdown b/source/docs/plugins/codeblock/index.markdown index 6327f5f..d8b5af0 100644 --- a/source/docs/plugins/codeblock/index.markdown +++ b/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" }} %} - Awesome code snippet - {{ "{% endcodeblock" }} %} +- `[lang:language]` - Choose a language for 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'. + +{% 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 %} - [rectangle setX: 10 y: 10 width: 20 height: 20]; - {% endcodeblock %}{% endraw %} +**2.** This example uses syntax highlighting. {% 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" }} %} - puts "Awesome!" unless lame - {{ "{% endcodeblock" }} %} +**3.** Including a file extension in the title can also trigger highlighting. {% 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. -Add `lang:your_language` to force highlighting if the filename doesn't work. - - {{ "{% codeblock Here's an example .rvmrc file. lang:ruby" }} %} - rvm ruby-1.8.6 # ZOMG, seriously? We still use this version? + {{ "{% codeblock Time to be Awesome - awesome.rb" }} %} + puts "Awesome!" unless lame {{ "{% 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 - -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 %} +**4.** Add an optional URL for downloading or linking to a source. {% 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 %} -# Given an alphabet: -alphabet = 'abcdefghijklmnopqrstuvwxyz' +### Other ways to embed code snippets -# Iterate over part of the alphabet: -console.log letter for letter in alphabet[4..8] -{% endcodeblock %} +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). diff --git a/source/docs/plugins/include-code/index.markdown b/source/docs/plugins/include-code/index.markdown index b1750ec..fff2730 100644 --- a/source/docs/plugins/include-code/index.markdown +++ b/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 -This includes a file from `source/downloads/code/test.js`. +### Basic options - {{ "{% 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 -By default the `
` will be the filename, but you can add a title before the filepath if you like. +*The source:* - {{ "{% 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. - - {% raw %}{% include_code test.js start:10 %}{% endraw %} +**3.** Embed a file starting from a specific line. {% 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. -Add `lang:your_language` to force highlighting if the filename doesn't work. +*The source:* - {{ "{% 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).