Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vduseev/jekyll-dry
Don't Repeat Yourself plugin for Jekyll to reuse fragments of pages by including them.
https://github.com/vduseev/jekyll-dry
ddd documentation documentation-tool documentation-toolchain jekyll jekyll-plugin
Last synced: 23 days ago
JSON representation
Don't Repeat Yourself plugin for Jekyll to reuse fragments of pages by including them.
- Host: GitHub
- URL: https://github.com/vduseev/jekyll-dry
- Owner: vduseev
- License: mit
- Created: 2018-02-22T23:54:56.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2020-02-29T18:51:52.000Z (over 4 years ago)
- Last Synced: 2024-04-23T18:52:22.303Z (7 months ago)
- Topics: ddd, documentation, documentation-tool, documentation-toolchain, jekyll, jekyll-plugin
- Language: Ruby
- Homepage:
- Size: 17.6 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# jekyll-dry
[](https://travis-ci.org/vduseev/jekyll-dry)
[](https://www.codacy.com/manual/vduseev/jekyll-dry?utm_source=github.com&utm_medium=referral&utm_content=vduseev/jekyll-dry&utm_campaign=Badge_Grade)
Jekyll plugin that helps you to implement the DRY (Don't Repeat Yourself) principle while writing documentation using Jekyll.
The plugin allows you to reuse any fragments of markdown multiple times across a single Jekyll website. The fragments can include Liquid syntax and tags.
## Table of contents
* User Guide:
* [Usage](#usage)
* [Installation](#installation)
* [Incompatibility with GitHub Pages](#incompatibility-with-github-pages)
* Implementation:
* [Plugin's architecture](architecture.md)
* [Detailed Design](detailed_design.md)
## Usage
### Fragment's beginning tag: `{% frag ... %}`
`frag` tag marks the beginning of a reusable fragment and assigns a unique id to it. Everything between `frag` and `endfrag` tags with unique id is considered a unique reusable fragment that can be included to any page.
Example of usage:
```
It was decided that the amount of dependencies of the executable will
be kept at minimum. For that reason {% frag dependencies %}the only
dependency is Python's `argparse` library{% endfrag dependencies %}.
```
As a result of the above markup the `dependencies` file will be generated and will contain following text:
```
the only dependency is Python's `argparse` library
```
The generated file is now available for inclusion at any page, including the page where it was initially declared. During generation process `frag` tag is replaced in page with an empty string.
### Fragment's end tag: `{% endfrag ... %}`
`endfrag` tag only marks the end of the fragment declared by `frag` tag and is only used by it. After Jekyll processes the page `endfrag` disappears.
If no matching `endfrag` is found for a given `frag`, then that `frag` will not be counted as a valid fragment and will not produce an include file.
Example of usage: [see above](#example-of-frag-usage).
During generation process `endfrag` tag is replaced in page with an empty string.
### Fragment embedding tag: `{% > ... %}`
`>` inclusion tag that searches for an include file with a given unique id generated by `frag` tag. Works in exactly same way as traditional `include` tag, but does not use parameters.
Example of usage:
```
Testing will require a test suite that covers a set of test cases
derived from initial use cases. However, since {% > dependencies %},
the testing will be entirely implemented using just the `py.test`
library.
```
Which will produce the following result:
Testing will require a test suite that covers a set of test cases derived from initial use cases. However, since the only
dependency is Python's `argparse` library, the testing will be entirely implemented using just the `py.test` library.
## Installation
Drop the `jekyll-dry.rb` file into the `_plugins` directory of the website as described in the first option of enabling a plugin in [Jekyll documentation](https://jekyllrb.com/docs/plugins/#installing-a-plugin):
```
In your site source root, make a _plugins directory. Place your plugins
here. Any file ending in *.rb inside this directory will be loaded
before Jekyll generates your site.
```
## Incompatibility with GitHub Pages
Since this is a custom plugin which is not included in the code set of GitHub pages plugins it will not work with GitHub's automatic website generation.
You will have to generate the website locally and then push the contents of the `_site` folder to GitHub in order to publish your website.