README.md in jekyll_flexible_include-2.0.15 vs README.md in jekyll_flexible_include-2.0.18
- old
+ new
@@ -32,50 +32,82 @@
In addition, filenames that require environment expansion because they contain a
<code>$</code> character are expanded according to the environment variables
defined when <code>jekyll build</code> executes.
+A file from a git repository can also be included.
+Files can be retrieved from at a given commit or tag.
+Two new options are provided for this purpose:
+ - `repo` - directory where git repo resides; environment variables are expanded; defaults to current directory.
+ - `git_ref` - Git ref of commit or tag to be examined for the file; defaults to `HEAD`.
+
+
+### Configuration
+Configuration parameters can be added to a section in `_config.yml` called `flexible_include`, like this:
+
+```yaml
+flexible_include:
+ die_on_file_error: true
+ die_on_path_denied: true
+ die_on_run_error: true
+ die_on_other_error: true
+```
+
+The default values for all of these parameters is `false`,
+except for `die_on_other_error`, which defaults to `true`.
+
+ - If `die_on_file_error` is enabled, then an attempt to include a file that fails will cause Jekyll to die with an error message.
+
+ - If `die_on_path_denied` is enabled (see [Restricting Directory Access](#restricting-directory-access)), then an attempt to include a file that should be blocked will cause Jekyll to die with an error message.
+
+ - If `die_on_run_error` is enabled, then an attempt to run a process that fails will cause Jekyll to die with an error message.
+
+ - If `die_on_other_error` is enabled, then any other exception will cause Jekyll to die with an error message.
+
+
### Syntax
-The following are equivalent:
+The following are all equivalent, however, the first two are recommended:
```html
+{% flexible_include file="path" [ OPTIONS ] %}
+{% flexible_include file='path' [ OPTIONS ] %}
{% flexible_include path [ OPTIONS ] %}
{% flexible_include 'path' [ OPTIONS ] %}
{% flexible_include "path" [ OPTIONS ] %}
```
-By default, the included file will escape characters <code><</code>,
-<code>{</code> and <code>}</code> unless the <code>do_not_escape</code> keyword option is specified.
Note that the [square brackets] merely indicate optional parameters
and are not intended to be written literally.
### Options
- * `do_not_escape` includes the content without HTML escaping it.
+ * `do_not_escape` keyword option caused the content to be included without HTML escaping it.
+ By default, the included file will escape characters <code><</code>,
+ <code>{</code> and <code>}</code> unless the <code>do_not_escape</code> keyword option is specified.
* `highlight='regex pattern here'` wraps content matching the regex pattern within a
`<span class='bg_yellow'></span>` tag.
Note that the pattern can simply consist of the exact text that you want to highlight.
- * `pre` causes the included file to be wrapped inside a <pre></pre> tag,
- no label is generated.
+ * `pre` is a keyword option that causes the included file to be wrapped inside a
+ <pre></pre> tag; no label is generated.
The <pre></pre> tag has an `data-lt-active="false"` attribute, so
[LanguageTool](https://forum.languagetool.org/t/avoid-spell-check-on-certain-html-inputs-manually/3944)
will not attempt to check the spelling or grammar of the contents.
The following options imply `pre`:
- * `dark` applies the `dark` class to the generated <pre></pre> tag.
+ * `dark` keyword option applies the `dark` class to the generated <pre></pre> tag.
You can define the `dark` and `darkLabel` classes as desired.
[This CSS is a good starting point.](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html#pre_css)
- * `download` uses the name of the file as a label,
+ * `download` keyword option uses the name of the file as a label,
and displays it above the <pre></pre> tag.
Clicking the label causes the file to be downloaded.
- * `copy_button` draws an icon at the top right of the <pre></pre>
+ * `copyButton` keyword option draws an icon at the top right of the <pre></pre>
tag that causes the included contents to be copied to the clipboard.
- * `label` specifies that an automatically generated label be placed above the contents.
+ * `label` keyword option specifies that an automatically generated label be placed above the contents.
There is no need to specify this option if `download` or `copy_button` options are provided.
* `label="blah blah"` specifies a label for the contents; this value overrides the default label.
The value can be enclosed in single or double quotes.
@@ -128,11 +160,11 @@
`ERROR FlexibleInclude: _posts/2020/2020-10-03-jekyll-plugins.html - Arbitrary command execution denied by DISABLE_FLEXIBLE_INCLUDE value.`
## Installation
1. Add the following to `Gemfile`, inside the `jekyll_plugins` group:
- ```
+ ```ruby
group :jekyll_plugins do
gem 'jekyll_flexible_include', '~> 2.0.15'
end
```
@@ -170,17 +202,17 @@
```
{% flexible_include '../../folder/outside/jekyll/site/foo.html' %}
{% flexible_include 'folder/within/jekyll/site/bar.js' %}
{% flexible_include '/etc/passwd' %}
{% flexible_include '~/.ssh/config' %}
- {% flexible_include '!jekyll' %}
+ {% flexible_include '!jekyll help' %}
{% flexible_include '$HOME/.bash_aliases' %}
```
2. Include a JSON file (without escaping characters).
```
- {% flexible_include '~/folder/under/home/directory/foo.html' do_not_escape %}
+ {% flexible_include do_not_escape file='~/folder/under/home/directory/foo.html' %}
```
## Additional Information
More information is available on
[Mike Slinn’s website](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html).
@@ -208,11 +240,11 @@
## Known Issues
If the plugin does not work:
-1. Ensure `_config.yml` doesn't have `safe: true`.
+1. Ensure `_config.yml` doesn't have `safe: true` set.
That prevents all plugins from working.
2. If you have version older than v2.x.x,
delete the file `_plugins/flexible_include.rb`,
or you will have version conflicts.
@@ -244,33 +276,50 @@
Jekyll plugin supports various ways to include content into the
generated site.
```
-## Demo
+## Demo Website
A test/demo website is provided in the `demo` directory.
You can run it under a debugger, or let it run free.
-### Free Range Demo Website
-To let it run freely, without a debugger, use the `-r` option:
- ```shell
- $ demo/bin/debug -r
- ```
+The `demo/_bin/debug` script can set various parameters for the demo.
+View the help information with the `-h` option:
+```shell
+$ demo/_bin/debug -h
-View the generated website at [`http://localhost:4444`](http://localhost:4444)
+debug - Run the demo Jekyll website.
-### Demo Website Debugging
+By default the demo Jekyll website runs without restriction under ruby-debug-ide and debase.
+View it at http://localhost:4444
+
+Options:
+ -e Restrict the allowable directories to read from to the following regexes:
+ jekyll_flexible_include_plugin/.*
+ /dev/.*
+ /proc/.*
+ /run/.*
+
+ -h Show this error message
+
+ -r Run freely, without a debugger
+
+ -x Disable the ability to execute arbitrary commands
+```
+
+
+### Debugging the Demo
To run under a debugger, for example Visual Studio Code:
1. Set breakpoints.
2. Initiate a debug session from the command line:
```shell
$ demo/bin/debug
```
3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch configuration called `Attach rdebug-ide`.
- 4. View the generated website at [`http://localhost:4444`](http://localhost:4444)
+ 4. View the generated website at [`http://localhost:4444`](http://localhost:4444).
### Build and Push to RubyGems
To release a new version,