README.md in jekyll_flexible_include-2.0.20 vs README.md in jekyll_flexible_include-2.0.21
- old
+ new
@@ -1,8 +1,6 @@
-Jekyll `flexible_include` Plugin
-[](https://badge.fury.io/rb/jekyll_flexible_include)
-===========
+# Jekyll `flexible_include` Plugin [](https://badge.fury.io/rb/jekyll_flexible_include)
`Flexible_include` is a Jekyll plugin that includes the contents of a file
or the result of a process into a generated page.
`Flexible_include` is useful because Jekyll's built-in `include` tag only
supports the including of files residing within the `_includes/` subfolder of a Jekyll project,
@@ -16,11 +14,11 @@
More information is available on my website about [my Jekyll plugins](https://www.mslinn.com/blog/2020/10/03/jekyll-plugins.html).
This plugin supports 4 types of includes:
-### Include Types
+## Include Types
1. Absolute filenames (recognized by filename paths that start with `/`).
2. Filenames relative to the top-level directory of the Jekyll website (relative paths **do not** start with `.` or `/`).
@@ -28,22 +26,24 @@
4. Executable filenames on the `PATH` (recognized by filename paths that begin with `!`).
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.
+`$` character are expanded according to the environment variables
+defined when `jekyll build` 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`.
+- `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
+
Configuration parameters can be added to a section in `_config.yml` called `flexible_include`, like this:
```yaml
flexible_include:
die_on_file_error: true
@@ -53,21 +53,25 @@
```
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_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_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_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.
+- If `die_on_other_error` is enabled, then any other exception will cause Jekyll to die with an error message.
-### Syntax
+## Syntax
+
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 ] %}
@@ -76,59 +80,73 @@
Note that the [square brackets] merely indicate optional parameters
and are not intended to be written literally.
-### Options
- * `attribution` see [`jekyll_plugin_support`](https://github.com/mslinn/jekyll_plugin_support#subclass-attribution)
- * `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.
+## Options
- * `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.
+- `attribution` see [`jekyll_plugin_support`](https://github.com/mslinn/jekyll_plugin_support#subclass-attribution)
- * `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.
+- `do_not_escape` keyword option caused the content to be included without HTML escaping it.
+ By default, the included file will escape characters `<`,
+ `{` and `}` unless the `do_not_escape` keyword option is specified.
+- `from='regex'` specifies that the beginning of the output should discarded until the matching string or regex is encountered.
+
+- `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` 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.
+
+- `to='regex'` specifies that the output should discarded after the matching string or regex is encountered
+ (includes the matched line).
+
+- `until='regex'` specifies that the output should discarded after the matching string or regex is encountered
+ (excludes the matched line).
+
The following options imply `pre`:
- * `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` 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.
+- `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)
- * `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.
+- `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.
- * `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.
+- `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="blah blah"` specifies a label for the contents; this value overrides the default label.
- The value can be enclosed in single or double quotes.
+- `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.
-### Restricting Directory Access
-By default, `flexible_include` can read from all directories according to the permissions of the user account that launched the `jekyll` process.
+
+## Restricting Directory Access
+
+By default, `flexible_include` can read from all directories according to the permissions of the
+user account that launched the `jekyll` process.
For security-conscience environments, the accessible paths can be restricted.
-Defining an environment variable called `FLEXIBLE_INCLUDE_PATHS` prior to launching Jekyll will restrict the paths that `flexible_include` will be able to read from.
+Defining an environment variable called `FLEXIBLE_INCLUDE_PATHS` prior to launching Jekyll will
+restrict the paths that `flexible_include` will be able to read from.
This environment variable consists of a colon-delimited set of
[file and directory glob patterns](https://docs.ruby-lang.org/en/2.7.0/Dir.html#method-c-glob).
For example, the following restricts access to only the files within:
- 1. The `~/my_dir` directory tree of the account of the user that launched Jekyll.
+1. The `~/my_dir` directory tree of the account of the user that launched Jekyll.
- 2. The directory tree rooted at `/var/files`.
+2. The directory tree rooted at `/var/files`.
- 3. The directory tree rooted at the expanded value of the `$work` environment variable.
+3. The directory tree rooted at the expanded value of the `$work` environment variable.
```shell
export FLEXIBLE_INCLUDE_PATHS='~/.*:$sites/.*:$work/.*'
```
@@ -137,21 +155,25 @@
```shell
export FLEXIBLE_INCLUDE_PATHS='~/my_dir/**/*:/var/files/**/*:$work/**/*'
```
-#### Note
+
+### Note
+
The specified directories are traversed when the plugin starts,
and the filenames are stored in memory.
Directories with lots of files might take a noticable amount of
time to enumerate the files.
-### Restricting Arbitrary Processes
+## Restricting Arbitrary Processes
+
By default, `flexible_include` can execute any command.
You can disable that by setting the environment variable `DISABLE_FLEXIBLE_INCLUDE`
to any non-empty value.
+
```shell
export DISABLE_FLEXIBLE_INCLUDE=true
```
If a potential command execution is intercepted,
@@ -160,68 +182,68 @@
and a red error message will be logged on the console that says something like:
`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
```
2. Add the following to `_config.yml`.
This is necessary because the name of the plugin
does not match the name of the entry point file:
+
```yaml
plugins:
- flexible_include
```
3. Copy `demo/assets/images/clippy.svg` to a directory that resolves to
`assets/images/` in your Jekyll website.
-4. Copy the CSS from `demo/assets/css/styles.css` between the comments to your Jekyll project's CSS file:
- ```css
- blah blah blah
+4. Copy the CSS from `demo/assets/css/jekyll_flexible_include.css` to your Jekyll project's CSS file.
- /* START OF CSS TO COPY */
- Copy this stuff
- /* END OF CSS TO COPY */
+5. Install the `jekyll_flexible_include` Ruby gem and mark it as a dependency of your project:
- blah blah blah
- ```
-
-5. Install the `jekyll_flexible_include` Ruby gem as usual:
```shell
- $ bundle install
+ $ bundle
```
## Examples
1. Include files, escaping any HTML markup, so it appears as written; all four types of includes are shown.
- ```
+
+ ```html
{% 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 help' %}
{% flexible_include '$HOME/.bash_aliases' %}
```
2. Include a JSON file (without escaping characters).
- ```
+
+ ```html
{% 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).
## GitHub Pages
+
GitHub Pages only allows [these plugins](https://pages.github.com/versions/).
That means `flexible_include` will not work on GitHub Pages.
Following is a workaround.
1. Let's assume your git repository that you want to publish as GitHub Pages is called `mysite`.
@@ -235,14 +257,16 @@
5. Run `git commit` on `generated_site`.
6. Tell GitHub that you want the `generated_site` repository to hold your GitHub pages.
-7. A moment later, your website will now be visible as GitHub Pages, with the included content, just as you saw it locally.
+7. A moment later, your website will now be visible as GitHub Pages, with the included content,
+ just as you saw it locally.
## Known Issues
+
If the plugin does not work:
1. Ensure `_config.yml` doesn't have `safe: true` set.
That prevents all plugins from working.
@@ -250,21 +274,26 @@
delete the file `_plugins/flexible_include.rb`,
or you will have version conflicts.
## Development
+
After checking out the repo, run `bin/setup` to install dependencies as binstubs in the `exe` directory.
You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
### Build and Install Locally
+
To build and install this gem onto your local machine, run:
+
```shell
-$ rake install
+$ bundle exec rake install
```
Examine the newly built gem:
+
```shell
$ gem info jekyll_flexible_include
*** LOCAL GEMS ***
@@ -278,15 +307,17 @@
generated site.
```
## Demo Website
+
A test/demo website is provided in the `demo` directory.
You can run it under a debugger, or let it run free.
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
debug - Run the demo Jekyll website.
@@ -307,47 +338,47 @@
-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
- ```
+1. Set breakpoints.
+2. Initiate a debug session from the command line:
- 3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch configuration called `Attach rdebug-ide`.
+ ```shell
+ $ demo/bin/debug
+ ```
- 4. View the generated website at [`http://localhost:4444`](http://localhost:4444).
+3. Once the `Fast Debugger` signon appears, launch the Visual Studio Code launch configuration called `Attach rdbg`.
+4. View the generated website at [`http://localhost:4444`](http://localhost:4444).
### Build and Push to RubyGems
+
To release a new version,
1. Update the version number in `version.rb`.
-
2. Add a comment to the top of `CHANGELOG.md`.
-
3. Commit all changes to git; if you don't the next step will fail.
-
4. Run the following:
+
```shell
$ bundle exec rake release
```
+
The above creates a git tag for the version, commits the created tag,
and pushes the new `.gem` file to [RubyGems.org](https://rubygems.org).
## Contributing
-1. Fork the project
+1. Fork the project
2. Create a descriptively named feature branch
-
3. Add your feature
-
4. Submit a pull request
## License
+
The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).