creek-jekyll-theme 1.7.4 → 1.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3a338aef1b12d27f26bdf0ccc334aa6ebeeced4daf1074c8ffecd87c84a84562
-  data.tar.gz: 942de0d235a2742ac014e1227b5c1d4e6a9ebbfe29cf04aa16922228b17045f6
+  metadata.gz: 4b118a4111e51a90bfa302e32857c701d8a9ace6c278f1faeef5781ade636b1c
+  data.tar.gz: b6c9c48a8bce657660aa0f502ab85e88fe0997fb9d71c4be28cc4017e31ea99a
 SHA512:
-  metadata.gz: 809c58209543e9f263fbae5f699348640698bf86a8ac924f7e01ce5aea88b3fecbdda848d2220233a1f2e6280ff557446f94b33bc7679445e65ea74a5830a556
-  data.tar.gz: b328a16afe5e609e4570ef2b57a045d6b4a85465a4b6b4f336dbc05382e8654b7a844012309d19bd007d2e4541652c8e007fd7deefa4d610749e7ef2f32db2ca
+  metadata.gz: 41af36e2771e94e630304b2bce7148eb7996e9f71d6a9fd205fdf866983da9ef5173898b84ba74a0a302feae09c6d79702b594eda6c8a277467495e6f78aa231
+  data.tar.gz: 523e31b1201cd7e546ad6a48b0c5c3274abf5dd0b129f957f3b7c87c8db977623655f6a17d393c4e5a60bc47b9ab6e40b8e7671ea99bf63e8759a0afaa155f22

data/README.md

@@ -0,0 +1,147 @@
+# creek-jekyll-theme
+
+The Jekyll theme used by the [Creek site](https://www.creekservice.org).
+
+## Installation
+
+Add this line to your Jekyll site's `Gemfile`:
+
+```ruby
+gem "creek-jekyll-theme"
+```
+
+And add this line to your Jekyll site's `_config.yml`:
+
+```yaml
+theme: creek-jekyll-theme
+```
+
+And then execute:
+
+```shell
+$ bundle
+```
+
+Or install it yourself as:
+
+```shell
+$ gem install creek-jekyll-theme
+```
+
+## Usage
+
+The theme is a fork of [minimal-mistakes](https://github.com/mmistakes/minimal-mistakes), with a load of shared
+defaults, images, data, and customisations.
+
+### `include_snippet` Liquid tag
+
+The gem also bundles an `include_snippet` Liquid tag, which includes a named snippet of text from another file
+into a page or post - handy for keeping code samples in docs in sync with the actual source. It's a drop-in
+replacement for the [`jekyll-include_snippet`](https://github.com/tomdalling/jekyll-include_snippet) gem, with
+one behavioural fix: an explicit `from <path>` on a tag now always takes precedence over a page's
+`snippet_source` front matter default, rather than being silently overridden by it.
+
+To use it, add this gem to the `jekyll_plugins` group in your `Gemfile` instead of (or as well as, if you're
+also using the theme) adding it as a plain gem, so Jekyll requires it as a plugin:
+
+```ruby
+group :jekyll_plugins do
+  gem "creek-jekyll-theme"
+end
+```
+
+If you were previously using the `jekyll-include_snippet` gem directly, remove it - `include_snippet` tags in
+your markdown work unchanged, no content needs to change.
+
+Usage is otherwise the same as the gem it replaces. Put `begin-snippet`/`end-snippet` comments around the code
+you want to include:
+
+```ruby
+# begin-snippet: my_snippet
+def my_method
+  ...
+end
+# end-snippet
+```
+
+Then include it from a page or post:
+
+```liquid
+{% include_snippet my_snippet from path/to/file.rb %}
+```
+
+Or set a default source file in front matter, and override it per-tag when needed:
+
+```yaml
+---
+snippet_source: "path/to/file.rb"
+snippet_comment_prefix: "//" # defaults to "#"
+---
+```
+
+See the source of [`lib/creek-jekyll-theme/include_snippet.rb`](lib/creek-jekyll-theme/include_snippet.rb) for
+full documentation.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/creek-service/creek-jekyll-theme. 
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere
+to the [Contributor Covenant](https://www.contributor-covenant.org/) code of conduct.
+
+## Development
+
+To set up your environment to develop this theme, run `bundle install`.
+
+This theme is set up just like a normal Jekyll site! To test your theme, run `bundle exec jekyll serve` and open 
+your browser at `http://localhost:4000`. This starts a Jekyll server using this theme. Add pages, documents, data, etc. 
+like normal to test the theme's contents. As you make modifications to the theme and to your content, 
+the site will regenerate, and you should see the changes in the browser after a refresh, just like normal.
+
+When the theme is released, only the files in `_data`, `_layouts`, `_includes`, `_sass`, `assets` and `lib` tracked with Git will be bundled.
+To add a custom directory to the theme-gem, please edit the regexp in `creek-jekyll-theme.gemspec` accordingly.
+
+## License
+
+The theme is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Building locally
+
+To build and install locally from source, follow these steps:
+
+1. Update version number in the [gemspec](creek-jekyll-theme.gemspec).
+2. Run: 
+   ```shell
+   rm creek-jekyll-theme-*.gem
+   gem build creek-jekyll-theme.gemspec
+   gem install creek-jekyll-theme-*.gem
+   ```
+
+## Releasing
+
+Releases will automatically be built and pushed to [Ruby Gems](https://rubygems.org/gems/creek-jekyll-theme) when
+a release tag is pushed to git. 
+Currently, the process of updating the gemspec version and pushing a matching git tag is a manual process:
+
+1. Update version number in the [gemspec](creek-jekyll-theme.gemspec).
+2. Run the following to pick up the new version:
+   ```shell
+   bundle update
+   ```
+3. Commit & push
+   ```shell
+   git add -A
+   git commit -m "Bump release version"
+   git push 
+   ```
+4. Push a new git tag, matching the new version in the gemspec:
+   ```shell
+   GEM_VERSION=$(sed -nr 's/.*spec\.version[^"]*"([1-9.]+)"/\1/p' creek-jekyll-theme.gemspec)
+   git tag v$GEM_VERSION
+   git push --tag
+   ```
+
+### Dropping a release
+
+```shell
+gem yank creek-jekyll-theme -v VERSION_TO_DROP  
+```

data/_includes/seo.html

@@ -7,7 +7,7 @@
 {% assign title_separator = site.title_separator | default: '-' | replace: '|', '|' %}
 
 {%- if page.title -%}
-  {%- assign seo_title = page.title | append: " " | append: title_separator | append: " " | append: site.title -%}
+  {%- assign seo_title = page.title | append: " " | append: title_separator | append: " " | append: site.title | truncate: 70 -%}
 {%- endif -%}
 
 {%- if seo_title -%}

data/lib/creek-jekyll-theme/include_snippet.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+# Liquid tag that includes a named snippet of text from another file into a page or post.
+#
+# Bundled with this theme so Creek's docs sites don't need to depend on the separate
+# `jekyll-include_snippet` gem, and so a bug in that gem's precedence rules can be fixed here
+# without waiting on an upstream release.
+#
+# Ported from https://github.com/tomdalling/jekyll-include_snippet (MIT licensed,
+# Copyright (c) Tom Dalling), with one behavioural fix: an explicit `from <path>` on the tag
+# itself now takes precedence over a page's `snippet_source` front matter default. Previously,
+# setting `snippet_source` in front matter silently overrode every `from <path>` on that page,
+# no matter what path was given, which broke pages that need to pull named snippets from more
+# than one source file.
+#
+# Usage:
+#
+#   Put `begin-snippet`/`end-snippet` comments around the code you want to include:
+#
+#     # begin-snippet: my_snippet
+#     def my_method
+#       ...
+#     end
+#     # end-snippet
+#
+#   Then include it from a page or post:
+#
+#     {% include_snippet my_snippet from path/to/file.rb %}
+#
+#   If every `include_snippet` tag on a page reads from the same file, set a default in the
+#   page's front matter instead of repeating `from <path>` on every tag:
+#
+#     ---
+#     snippet_source: "path/to/file.rb"
+#     ---
+#     {% include_snippet my_snippet %}
+#
+#   An explicit `from <path>` always overrides the front matter default for that one tag, so
+#   the two forms can be mixed freely on the same page.
+#
+#   For non-Ruby source, set the comment prefix used to find the begin/end markers, either
+#   per-page via front matter:
+#
+#     ---
+#     snippet_comment_prefix: "//"
+#     ---
+#
+#   The default comment prefix is `#`.
+module CreekJekyllTheme
+  module IncludeSnippet
+    DEFAULT_COMMENT_PREFIX = "#"
+
+    class LiquidTag < Liquid::Tag
+      def initialize(tag_name, arg_str, tokens)
+        super
+        @snippet_name, @source_path = arg_str.split(/\sfrom\s/).map(&:strip)
+      end
+
+      def render(context)
+        source_path = source_path_for(context)
+        source = File.read(source_path)
+        extractor = Extractor.new(comment_prefix: comment_prefix_for(context))
+        snippets = extractor.(source)
+        snippets.fetch(@snippet_name) do
+          raise "Snippet not found: #{@snippet_name.inspect}\n    in file: #{source_path}"
+        end
+      end
+
+      private
+
+      # An explicit `from <path>` on the tag always wins. Only fall back to the page's
+      # `snippet_source` front matter default when the tag doesn't specify its own path.
+      def source_path_for(context)
+        result = @source_path || get_option(:snippet_source, context)
+
+        raise "No source path provided for snippet: #{@snippet_name}" if result.nil?
+
+        result
+      end
+
+      def comment_prefix_for(context)
+        get_option(:snippet_comment_prefix, context) || DEFAULT_COMMENT_PREFIX
+      end
+
+      def get_option(option_name, context)
+        page = context["page"]
+        page && page[option_name.to_s]
+      end
+    end
+
+    class Extractor
+      attr_reader :comment_prefix
+
+      def initialize(comment_prefix:)
+        @comment_prefix = comment_prefix
+      end
+
+      def call(source)
+        everything = Snippet.new(name: "everything", indent: 0)
+        all_snippets = []
+        active_snippets = []
+
+        source.each_line.each_with_index do |line, lineno|
+          case line
+          when begin_regex
+            active_snippets << Snippet.new(name: $2.strip, indent: $1.length)
+          when end_regex
+            raise missing_begin_snippet(lineno) if active_snippets.empty?
+
+            all_snippets << active_snippets.pop
+          else
+            (active_snippets + [everything]).each do |snippet|
+              snippet.lines << line
+            end
+          end
+        end
+
+        (all_snippets + [everything])
+          .map { |s| [s.name, s.dedented_text] }
+          .to_h
+      end
+
+      private
+
+      def begin_regex
+        %r{
+          (\s*)           # optional whitespace (indenting)
+          #{Regexp.quote(comment_prefix)} # the comment prefix
+          \s*             # optional whitespace
+          begin-snippet:  # magic string for beginning a snippet
+          (.+)            # the remainder of the line is the snippet name
+        }x
+      end
+
+      def end_regex
+        %r{
+          \s*          # optional whitespace (indenting)
+          #{Regexp.quote(comment_prefix)} # the comment prefix
+          \s*          # optional whitespace
+          end-snippet  # Magic string for ending a snippet
+        }x
+      end
+
+      def missing_begin_snippet(lineno)
+        <<~END_ERROR
+          There was an `end-snippet` on line #{lineno}, but there doesn't
+          appear to be any matching `begin-snippet` line.
+
+          Make sure you have the correct `begin-snippet` comment --
+          something like this:
+
+              # begin-snippet: MyRadCode
+
+        END_ERROR
+      end
+
+      class Snippet
+        attr_reader :name, :indent, :lines
+
+        def initialize(name:, indent:)
+          @name = name
+          @indent = indent
+          @lines = []
+        end
+
+        def dedented_text
+          lines
+            .map { |line| dedent(line) }
+            .join
+            .rstrip
+        end
+
+        def dedent(line)
+          if line.length >= indent
+            line[indent..-1]
+          else
+            line
+          end
+        end
+      end
+    end
+  end
+end
+
+Liquid::Template.register_tag("include_snippet", CreekJekyllTheme::IncludeSnippet::LiquidTag)

data/lib/creek-jekyll-theme.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require "creek-jekyll-theme/include_snippet"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: creek-jekyll-theme
 version: !ruby/object:Gem::Version
-  version: 1.7.4
+  version: 1.8.0
 platform: ruby
 authors:
 - Creek Service - Big Andy Coates
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-02-22 00:00:00.000000000 Z
+date: 2026-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll
@@ -30,6 +30,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: liquid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: jekyll-paginate
   requirement: !ruby/object:Gem::Requirement
@@ -104,16 +118,22 @@ dependencies:
   name: jekyll-sass-converter
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
         version: '2.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.0'
 - !ruby/object:Gem::Dependency
   name: jekyll-algolia
   requirement: !ruby/object:Gem::Requirement
@@ -132,16 +152,22 @@ dependencies:
   name: jemoji
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: '0.12'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '0.14'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.12'
+    - - "<"
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: '0.14'
 - !ruby/object:Gem::Dependency
   name: jekyll-last-modified-at
   requirement: !ruby/object:Gem::Requirement
@@ -184,7 +210,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 12.3.3
-description: 
+description:
 email:
 - 8012398+big-andy-coates@users.noreply.github.com
 executables: []
@@ -192,6 +218,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- README.md
 - _config.yml
 - _data/navigation/main.yml
 - _data/ui-text.yml
@@ -356,7 +383,6 @@ files:
 - assets/images/logo_drop_shadow.png
 - assets/images/mstile-150x150.png
 - assets/images/safari-pinned-tab.svg
-- assets/images/site-under-construction.png
 - assets/images/site.webmanifest
 - assets/js/_main.js
 - assets/js/lunr/lunr-en.js
@@ -372,12 +398,14 @@ files:
 - assets/js/plugins/jquery.magnific-popup.js
 - assets/js/plugins/smooth-scroll.js
 - assets/js/vendor/jquery/jquery-3.6.0.js
+- lib/creek-jekyll-theme.rb
+- lib/creek-jekyll-theme/include_snippet.rb
 homepage: https://github.com/creek-service/creek-jekyll-theme
 licenses:
 - MIT
 metadata:
   plugin_type: theme
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -392,8 +420,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.26
-signing_key: 
+rubygems_version: 3.4.19
+signing_key:
 specification_version: 4
 summary: A Jekyll theme gem, intended only for the Creek website.
 test_files: []