gitbook-plugin-snippet
v1.0.0
Published
Quote a fragment of a source file
Downloads
2
Readme
Snippets for GitBook
Include entire code files or fragments of code files in your pages. Read files from file system, or from git.
Installation
{
"plugins": [
"snippet@git+https://github.com/cucumber-ltd/gitbook-plugin-snippet.git"
],
"pluginsConfig": {
"snippet": {
"problem": "fail"
}
}
}
The problem
property can be "warn"
,"error"
or "fail"
. Default is "error"
.
Include entire file
Let's say you have a file some/file.rb
:
puts "hello"
You can include its contents in a document as follows:
Look at this code:
```ruby
[snippet](some/file.rb)
```
The [snippet](...)
link will be replaced with the entire contents of the file:
Look at this code:
```ruby
puts "hello"
```
Include fragments from files
Let's say you have a file some/file-with-fragment.rb
with
doxygen-like block markers:
class Fragment
### [the-marker]
if true
puts "the fragment"
end
### [the-marker]
end
You can include just the fragment between the markers as follows:
Look at this code:
```ruby
[snippet](some/file-with-fragment.rb#the-marker)
```
Result:
Look at this code:
```ruby
if true
puts "the fragment"
end
```
Note that the fragment has been unindented while preserving whitespace.
Include files from git
Just apend @
after the marker, followed by the commit message (or substring of commit message). Example:
[snippet](some/file-with-fragment.rb#the-marker@this fixes a bug)
All branches will be searched. If multiple commits match the commit message, the most recent one is always picked.
Inspiration
- https://github.com/rlmv/gitbook-plugin-include
- https://github.com/azu/gitbook-plugin-include-codeblock