updated documentation for code plugins

This commit is contained in:
Brandon Mathis 2012-06-03 00:24:03 -05:00
parent 020ec2f773
commit 758687f9bd
4 changed files with 139 additions and 89 deletions

View File

@ -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 %}

View File

@ -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] [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
```
``` 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).

View File

@ -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).

View File

@ -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 `<figcaption>` 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).