Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/mslinn/jekyll_outline
Organizes the index of a collection into chapters.
https://github.com/mslinn/jekyll_outline
jekyll jekyll-plugin
Last synced: about 2 months ago
JSON representation
Organizes the index of a collection into chapters.
- Host: GitHub
- URL: https://github.com/mslinn/jekyll_outline
- Owner: mslinn
- License: mit
- Created: 2022-05-02T13:19:58.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-01-09T15:38:35.000Z (11 months ago)
- Last Synced: 2024-04-25T01:40:35.293Z (8 months ago)
- Topics: jekyll, jekyll-plugin
- Language: Ruby
- Homepage: https://www.mslinn.com/jekyll_plugins/jekyll_outline.html
- Size: 5.05 MB
- Stars: 1
- Watchers: 2
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE.txt
Awesome Lists containing this project
- awesome-jekyll-plugins - **jekyll_outline**
README
# `jekyll_outline` [](https://badge.fury.io/rb/jekyll_outline)
`jekyll_outline` Jekyll tag plugin that creates a clickable table of contents.
## Usage
These examples are taken from [`demo/index.html`](demo/index.html).
Sort by `order` field:
```html
{% outline attribution fields=" title – description " stuff %}
000: A Topic 0..19
020: A Topic 20..39
040: A Topic 40..
{% endoutline %}
```
Sort by `title` field:
```html
{% outline attribution sort_by_title fields=" title – description " stuff %}
000: B Topic 0..19
020: B Topic 20..39
040: B Topic 40..
{% endoutline %}
```
## Installation
Add the following line to your Jekyll project's Gemfile, within the `jekyll_plugins` group:
```ruby
group :jekyll_plugins do
gem 'jekyll_outline'
end
```
And then execute:
```shell
$ bundle
```
## Fields
By default, each displayed entry consists of a document title,
wrapped within an <a href> HTML tag that links to the page for that entry,
followed by an indication of whether the document is visible (a draft) or not.
Entry can also include following fields:
`draft`, `categories`, `description`, `date`, `last_modified` or `last_modified_at`, `layout`, `order`, `title`, `slug`,
`ext`, `tags`, and `excerpt`.
Specify the fields like this:
```html
{% outline fields="title – description " %}
000: Topic 0..19
020: Topic 20..39
040: Topic 40..
{% endoutline %}
```
Words that are not a known field are transcribed into the output.
In the above example, notice that the HTML is space delimited from the field names.
The parser is simple and stupid: each token is matched against the known keywords.
Tokens are separated by white space.
### CSS
The CSS used for the demo website should be copied to your project.
See the sections of
[`demo/assets/css/styles.css`](/mslinn/jekyll_outline/blob/master/demo/assets/css/style.css#L252-L315) as shown:
```css
/* Start of jekyll_plugin_support css */
... copy this portion ...
/* End of jekyll_plugin_support css */
/* Start of jekyll_outline css */
... copy this portion ...
/* End of jekyll_outline css */
```
### JavaScript
This project's `outline_js` tag returns the Javascript necessary to position images relating to the outline.
If used without parameters it just returns the JavaScript.
Use the tag this way:
```html
{%= outline_js %}
```
If passed the `wrap_in_script_tag` parameter, it wraps the JavaScript in ``.
Use the tag this way:
```html
{% outline_js wrap_in_script_tag %}
```
## Explanation
Given an outline that looks like this:
```html
{% outline stuff %}
000: Topic 0..19
020: Topic 20..39
040: Topic 40..
{% endoutline %}
```
...and given pages in the `stuff` collection with the following names:
- `010-published.html` has title **Published Stuff Post 010**
- `020-unpublished.html` has title **Unpublished Post 020**
- `030-unpublished.html` has title **Unpublished Post 030**
Then links to the pages in the `stuff` collection's pages are interleaved into the generated outline like this:
```html
Topic 0..19
Topic 20..39
```
The JavaScript searches for images in the current page that were created by the
[`img`](https://github.com/mslinn/jekyll_img) tag plugin,
and have `id`s that correspond to outline sections.
Each of following image's `id`s have an `outline_` prefix, followed by a number, which corresponds to one of the sections.
Note that leading zeros in the first column above are not present in the `id`s below.
If you want to provide images to embed at appropriate locations within the outline,
wrap them within an invisible `div` so the web page does not jump around as the images are loaded.
```html
{% img align="right"
id="outline_0"
size="quartersize"
src="/assets/images/porcelain_washbasin.webp"
style="margin-top: 0"
wrapper_class="clear"
%}
{% img align="right"
id="outline_20"
size="quartersize"
src="/assets/images/pipes.webp"
style="margin-top: 0"
wrapper_class="clear"
%}
{% img align="right"
id="outline_40"
size="quartersize"
src="/assets/images/libgit2.webp"
style="margin-top: 0"
wrapper_class="clear"
%}
```
The JavaScript identifies the images and repositions them in the DOM such that they follow the appropriate heading.
If no image corresponds to a heading, no error or warning is generated.
The images can be located anywhere on the page; they will be relocated appropriately.
If an image does not correspond to a heading, it is deleted.
## Attribution
See [`jekyll_plugin_support` for `attribution`](https://github.com/mslinn/jekyll_plugin_support#subclass-attribution)
## Additional Information
More information is available on
[Mike Slinn’s website](https://www.mslinn.com/jekyll/3000-jekyll-plugins.html#outline).
## Development
After checking out the repo, run `bin/setup` to install development dependencies.
Then you can run `bin/console` for an interactive prompt that will allow you to experiment using `irb`.
### Build and Install Locally
To build and install this gem onto your local machine, run:
```shell
$ bundle exec rake install
jekyll_outline 0.1.0 built to pkg/jekyll_outline-0.1.0.gem.
jekyll_outline (0.1.0) installed.
$ gem info jekyll_outline
*** LOCAL GEMS ***
jekyll_outline (0.1.0)
Author: Mike Slinn
Homepage:
https://github.com/mslinn/jekyll_outline
License: MIT
Installed at: /home/mslinn/.gems
Generates Jekyll logger with colored output.
```
## Demo
A demo / test website is provided in the `demo` directory.
It can be used to debug the plugin or to run freely.
### Run Freely
1. Run from the command line:
```shell
$ demo/_bin/debug -r
```
2. View the generated website at [`http://localhost:4444`](http://localhost:4444)
### Plugin Debugging
1. Set breakpoints in Visual Studio Code.
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)
## Release
To release a new version,
1. Update the version number in `version.rb`.
2. Describe the changes in `CHANGELOG.md`.
3. Commit all changes to git; if you don't the next step might fail with an unexplainable error message.
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
Bug reports and pull requests are welcome on GitHub at https://github.com/mslinn/jekyll_outline.
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).