Jekyll::ID

⚠️ This is gem is under active development! ⚠️

⚠️ Expect breaking changes and surprises until otherwise noted (likely by v0.1.0 or v1.0.0). ⚠️

Jekyll-ID adds ID support for jekyll markdown documents. These IDs do not change alongside document filenames, which make using the ID in a document's permalink attribute more reliable.

Nanoid is used to validate ID format and generate IDs.

This gem is part of the jekyll-bonsai project. 🎋

⚠️ This plugin is meant to write directly to markdown files. Always be sure to backup data and use version control.

Installation

Add this line to your application's Gemfile:

gem 'jekyll-id'

And then execute:

$ bundle install

Or install it yourself as:

$ gem install jekyll-id

Configuration

Defaults look like this:

ids:
  enabled: true
  exclude: []

enabled: Set to false to disable the plugin. (Toggle this off if you only want to use ids in permalinks )

exclude: jekyll document types to exclude from ids processing.

format: set format parameters, available fields are alpha and size, see nanoid docs for details.

nanoid defaults:

ids:
  format:
    alpha: '_-0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
    size: 21

Usage

This plugin assumes all target markdown files contain frontmatter.

ID Generation

The plugin will check each markdown document's data attributes for an id. If none exists, it will prompt the user to generate an ID for them:

// ID Generation
> Generate frontmatter ID for: 
> <doc_info>
> with new ID: <new_id>
> Is that ok?
> (yes, no, yesall, or noall)

If yes or yesall is the response, the plugin will generate an ID and write it to the document's frontmatter in the markdown document.

ID Replacement (Strict Mode With Formatted IDs)

If the format fields have been filled out in the plugin's configuration, the plugin will not only scan for the existence of an id, but it will check that the id is of the correct format. The above logic still applies, but the plugin will also ask about ID replacement when it's of an incorrect format:

// ID Replacement
> Replace frontmatter for: 
> <document_info> 
> with ID: <current_id> 
> with new ID: <new_id>
> Is that ok?
> (yes, no, yesall, or noall)

Permalinks

This plugin adds the ability to insert :id into the configuration for frontmatter defaults:

# _config.yml
defaults:
- 
    scope:
      type: "posts"
    values:
      permalink: "/post/:id/"
  - 
    scope:
      type: "entries"
    values:
      permalink: "/entry/:id/"

Note:

The jekyll core will not make (post) ids permanent: jekyll/jekyll#3725

ToDo

Add support for GUIDs from ruby's built-in SecureRandom