jekyll_outline Gem Version

jekyll_outline Jekyll tag plugin that creates a clickable table of contents.

Usage

These examples are taken from demo/index.html.

Sort by order field:

{% outline attribution fields="<b> title </b> &ndash; <i> description </i>" stuff %}
000: A Topic 0..19
020: A Topic 20..39
040: A Topic 40..
{% endoutline %}

Sort by title field:

{% outline attribution sort_by_title fields="<b> title </b> &ndash; <i> description </i>" 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:

group :jekyll_plugins do
  gem 'jekyll_outline'
end

And then execute:

$ 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:

{% outline fields="title &ndash; <i> description </i>" %}
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 as shown:

/* 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:

<script>
  {%= outline_js %}
</script>

If passed the wrap_in_script_tag parameter, it wraps the JavaScript in <script></script>. Use the tag this way:

{% outline_js wrap_in_script_tag %}

Explanation

Given an outline that looks like this:

{% 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:

<div class="outer_posts">
  <h3 class='post_title clear' id="title_0">Topic 0..19</h3>
  <div id='posts_wrapper_0' class='clearfix'>
    <div id='posts_0' class='posts'>
      <span>2022-04-01</span> <span><a href='/stuff/010-published.html'>Published Stuff Post 010</a></span>
      <span>2022-04-17</span> <span><a href='/stuff/020-unpublished.html'>Unpublished Post 020</a> <i class='jekyll_draft'>Draft</i></span>
    </div>
  </div>
  <h3 class='post_title clear' id="title_20">Topic 20..39</h3>
  <div id='posts_wrapper_20' class='clearfix'>
    <div id='posts_20' class='posts'>
      <span>2022-04-17</span> <span><a href='/stuff/030-unpublished.html'>Unpublished Post 030</a> <i class='jekyll_draft'>Draft</i></span>
    </div>
  </div>
</div>

The JavaScript searches for images in the current page that were created by the img tag plugin, and have ids that correspond to outline sections.

Each of following image's ids 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 ids 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.

<div style="display: none;">
{% 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"
%}
</div>

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

Additional Information

More information is available on Mike Slinn’s website.

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:

$ 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:
   $ demo/_bin/debug -r
  1. View the generated website at http://localhost:4444

Plugin Debugging

  1. Set breakpoints in Visual Studio Code.

  2. Initiate a debug session from the command line:

   $ demo/_bin/debug
  1. Once the Fast Debugger signon appears, launch the Visual Studio Code launch configuration called Attach rdebug-ide.
  2. View the generated website at 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:

    $ 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.

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.