jekyll-is-hookdown 0.8.0.4 → 0.8.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: da37ba1fb35409ea8c632c8b1febf8817e2661ceab9274ba2bef23c020147826
-  data.tar.gz: 868079cadc51e00b6d19bedcbc0df7bf1640201259e0117300b5c09e199dd921
+  metadata.gz: 87b9cb1f0ca5eb1bc498487c55691e7133387aea3c571f5347081f56edf87367
+  data.tar.gz: 3a6d1f962ad0d4fdfd8dc5d91184e48471b02e23262fe6269e107a17463fc049
 SHA512:
-  metadata.gz: b2c250e14593802d2c3af5cd6d930e565887f59cbd5d19bf2e99e7f50e6ffaa402089053cf1dda892ec04723509192146da477294cd96e16c5ca71aba40e5cd8
-  data.tar.gz: 6fa6ba530ea69d14144718491864d6a995ca0c3835c543c8e2b45b32a2b125943fb3f2ce84dbcef17ab257b52cea33bdf36b43c6d5a6bb9a551e16a33e49d89a
+  metadata.gz: b5274949a9a9c9de234af8dd310905717b19fcbc63c4ed230d3c2d69cac4b79d9b8a9380f90c011e5f9599c3e47417ac06c0672a1a83da3f8e2fc74af9f45e30
+  data.tar.gz: 67b7b329bee0303da0ccc3d2410676e47cb02a032c72b47ac3fce7c5f258231c619e37848d6885abcc84072a82ae0b21e90c4e0b072ac185ae54e94c653061a3

data/README-ru.md

@@ -0,0 +1,144 @@
+| [en](README.md) | RU |
+|----------|----------|
+
+# jekyll-is-hookdown
+
+[![GitHub License](https://img.shields.io/github/license/jekyll-is/jekyll-is-hookdown)](LICENSE)
+[![Gem Version](https://badge.fury.io/rb/jekyll-is-hookdown.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/jekyll-is-hookdown)
+[![Ruby](https://github.com/jekyll-is/jekyll-is-hookdown/actions/workflows/ruby.yml/badge.svg)](https://github.com/jekyll-is/jekyll-is-hookdown/actions/workflows/ruby.yml)
+![Coverage](coverage-badge.svg)
+
+Плагин для Jekyll, позволяющий подменить markdown-парсер на кастомный — унаследованный от стандартного Kramdown и дополняющий его
+дополнительным хуком для перехвата внутреннего AST-представления.
+
+## Подключение
+
+Вообще, гем предназначен для использования другими плагинами и должен быть указан в зависимостях именно в них, а не в `Gemfile` сайта.
+Однако, в Jekyll есть возможность писать плагины в подкаталоге `_plugins` — чтобы там использовать данный хук, потребуется подключить
+данный гем именно как плагин:
+
+В `Gemfile`:
+
+```ruby
+group :jekyll_plugins do
+    . . .
+  gem 'jekyll-is-hookdown', '~> 0.8'
+end
+```
+
+Или, если вы не используете Bundler, установить гем командой:
+
+```shell
+gem install jekyll-is-hookdown
+```
+
+В `_config.yml`:
+
+```yaml
+plugins:
+    . . .
+  - jekyll-is-hookdown
+
+markdown: Hookdown
+```
+
+Последняя строчка включает работу плагина. При этом, поскольку конвертер унаследован от стандартного Kramdown, будут работать все расширения
+и настройки в подразделе конфигурации `kramdown` (собственной секции `hookdown` плагин не предусматривает), например:
+
+```yaml
+kramdown:
+  input: GFM
+  hard_wrap: false
+```
+
+### Зависимости
+
++ Ruby >= 3.4
+
++ Jekyll ~> 4.4
+
++ Kramdown ~> 2.5
+
+## Использование
+
+Основной хук внедрен в [общую систему хуков Jekyll](https://jekyllrb.com/docs/plugins/hooks/) как событие `:post_parse`. Он доступен
+для объектов `:pages`, `:documents` и `:posts` (нужно
+заметить, что `:documents` _включает в себя_ `:posts`). В обработчик передается объект документа/страницы и объект
+класса [`Kramdown::Document`](https://kramdown.gettalong.org/rdoc/Kramdown/Document.html).
+
+```ruby
+Jekyll::Hooks::register [ :pages, :documents ], :post_parse do |page, document|
+  # Какие-то действия с документом...
+end
+```
+
+Поскольку чаще всего нужно обрабатывать не весь документ, а определенные теги/элементы, предусмотрен и другой хук, не приводимый к стандартным,
+он регистрируется иначе. В обработчик передается объект документа/страницы и объект
+класса [`Kramdown::Element`](https://kramdown.gettalong.org/rdoc/Kramdown/Element.html).
+
+```ruby
+JekyllIS::Hookdown::register_element_hook [ :pages, :documents ], :a, :img do |page, element|
+  case element.type
+  when :a
+    # Тут что-то делаем...
+  when :img
+    # И тут что-то делаем...
+  end
+end
+```
+
+При этом значение, возвращаемое обработчиком, важно и трактуется следующим образом:
+
++ `nil` — не приводит к дополнительным действиям.
+
++ `Kramdown::Element` — заменяет текущий элемент в AST-дереве.
+
++ `:delete` — удаляет текущий элемент из AST-дерева.
+
++ Прочие значения трактуются как ошибочные.
+
+_Замена и удаление корневого элемента (`document.root`) не поддерживается._
+
+### Рекомендация
+
+Если вы пишете свой плагин с использованием этого хука, крайне желательно убедиться, что он активирован, то есть в конфиге выбран соответствующий
+кастомный конвертер. Можно, конечно, непосредственно проверять значение в `_config.yml`, но лучше использовать специальный метод:
+
+```ruby
+if JekyllIS::Hookdown::enabled?
+  # Устанавливаем свои хуки здесь...
+end
+```
+
+Проверка этого условия будет работать даже _до_ инициализации сайта.
+
+### Пример
+
+Выставим всем внешним ссылкам `target="_blank"`:
+
+```ruby
+if JekyllIS::Hookdown::enabled?
+  JekyllIS::Hookdown::register_element_hook [ :pages, :documents ], :a do |_, element|
+    href = element.attr['href']
+    target = element.attr['target']
+    if href && !target && (href.start_with?('https://') || href.start_with?('http://'))
+      element.attr['target'] = '_blank'
+    end
+    nil
+  end
+end
+```
+
+## Лицензия
+
+Плагин опубликован под **[GNU Lesser General Public License v3.0](https://www.gnu.org/licenses/lgpl-3.0.html)**. Это означает, что вы можете свободно
+им пользоваться без каких-то ограничений, пока подтягиваете его по зависимостям. Если же вы захотите _взять код_ и втянуть его в свой проект,
+или выпустить _форк_ данного плагина, результат должен быть опубликован так же под LGPLv3.
+
+## Статус
+
+Текущая версия — **0.8.x**. Это следует трактовать как публичную альфа-версию.
+
+Однако, в силу принципиального ограничения функциональности — плагин чисто инфраструктурный и не должен делать ничего лишнего, скорее всего чего-то
+нового в нем уже не появится. Так что по мере доработки автотестов и документации он будет плавно переходить в стадию бета-версии (0.9.x) и затем
+релиза (1.0) без каких-либо сущностных изменений в коде.

data/README.md

@@ -1,3 +1,131 @@
+| **EN** | [ru](README-ru.md) |
+|----------|----------|
+
 # jekyll-is-hookdown
 
-Hooked Kramdown for Jekyll
+[![GitHub License](https://img.shields.io/github/license/jekyll-is/jekyll-is-hookdown)](LICENSE)
+[![Gem Version](https://badge.fury.io/rb/jekyll-is-hookdown.svg?icon=si%3Arubygems)](https://badge.fury.io/rb/jekyll-is-hookdown)
+[![Ruby](https://github.com/jekyll-is/jekyll-is-hookdown/actions/workflows/ruby.yml/badge.svg)](https://github.com/jekyll-is/jekyll-is-hookdown/actions/workflows/ruby.yml)
+![Coverage](coverage-badge.svg)
+
+A Jekyll plugin that replaces the default Markdown parser with a custom one — inheriting from the standard Kramdown and extending it with an additional hook for intercepting the internal AST representation.
+
+## Setup
+
+In general, this gem is intended to be used by other plugins and should be listed as a dependency in *their* gemspecs, not in the site's `Gemfile`.
+However, Jekyll allows writing plugins in the `_plugins` subdirectory — to use this hook there, you will need to include the gem as a plugin:
+
+In `Gemfile`:
+
+```ruby
+group :jekyll_plugins do
+    . . .
+  gem 'jekyll-is-hookdown', '~> 0.8'
+end
+```
+
+Or, if you are not using Bundler, install the gem manually:
+
+```shell
+gem install jekyll-is-hookdown
+```
+
+In `_config.yml`:
+
+```yaml
+plugins:
+    . . .
+  - jekyll-is-hookdown
+
+markdown: Hookdown
+```
+
+The last line activates the plugin. Since the converter inherits from the standard Kramdown parser, all extensions and settings in the `kramdown` configuration subsection will continue to work (the plugin does not define its own `hookdown` section), for example:
+
+```yaml
+kramdown:
+  input: GFM
+  hard_wrap: false
+```
+
+### Dependencies
+
++ Ruby >= 3.4
+
++ Jekyll ~> 4.4
+
++ Kramdown ~> 2.5
+
+## Usage
+
+The main hook is injected into the [standard Jekyll hook system](https://jekyllrb.com/docs/plugins/hooks/) as the `:post_parse` event. It is available for `:pages`, `:documents`, and `:posts` (note that `:documents` *includes* `:posts`). The handler receives the page/document object and a [`Kramdown::Document`](https://kramdown.gettalong.org/rdoc/Kramdown/Document.html) instance.
+
+```ruby
+Jekyll::Hooks::register [ :pages, :documents ], :post_parse do |page, document|
+  # Do something with the document...
+end
+```
+
+Since in most cases you want to process specific tags/elements rather than the entire document, an additional hook is provided. It is *not* mapped to the standard Jekyll hook system and is registered differently. The handler receives the page/document object and a [`Kramdown::Element`](https://kramdown.gettalong.org/rdoc/Kramdown/Element.html) instance.
+
+```ruby
+JekyllIS::Hookdown::register_element_hook [ :pages, :documents ], :a, :img do |page, element|
+  case element.type
+  when :a
+    # Do something here...
+  when :img
+    # And something here...
+  end
+end
+```
+
+The return value of the handler is significant and interpreted as follows:
+
++ `nil` — no additional action is taken.
+
++ `Kramdown::Element` — replaces the current element in the AST tree.
+
++ `:delete` — removes the current element from the AST tree.
+
++ Any other value is treated as an error.
+
+_Replacing or deleting the root element (`document.root`) is not supported._
+
+### Recommendation
+
+If you are writing your own plugin that uses this hook, it is highly recommended to verify that it is active, i.e. that the corresponding custom converter is selected in the config. You could check the value in `_config.yml` directly, but it is better to use the dedicated method:
+
+```ruby
+if JekyllIS::Hookdown::enabled?
+  # Register your hooks here...
+end
+```
+
+This check will work even *before* the site is initialized.
+
+### Example
+
+Add `target="_blank"` to all external links:
+
+```ruby
+if JekyllIS::Hookdown::enabled?
+  JekyllIS::Hookdown::register_element_hook [ :pages, :documents ], :a do |_, element|
+    href = element.attr['href']
+    target = element.attr['target']
+    if href && !target && (href.start_with?('https://') || href.start_with?('http://'))
+      element.attr['target'] = '_blank'
+    end
+    nil
+  end
+end
+```
+
+## License
+
+The plugin is released under the **[GNU Lesser General Public License v3.0](https://www.gnu.org/licenses/lgpl-3.0.html)**. This means you are free to use it without any restrictions as long as you pull it in as a dependency. If you wish to *take the code* and incorporate it into your own project, or release a *fork* of this plugin, the result must also be published under the LGPLv3.
+
+## Status
+
+The current version is **0.8.x**. This should be treated as a public alpha release.
+
+However, due to the deliberately limited scope — the plugin is purely infrastructural and should not do anything extra — it is unlikely that any significant new features will be added. As tests and documentation are refined, it will gradually move to beta (0.9.x) and then to a stable release (1.0) without any substantial code changes.

data/coverage-badge.svg

@@ -0,0 +1,6 @@
+<?xml version="1.0"?><svg xmlns="http://www.w3.org/2000/svg" width="100" height="20">
+<rect width="100" height="20" fill="#555"/>
+<rect x="63" width="37" height="20" fill="#c6bc3d"/>
+<text x="8" y="14" fill="#fff" font-family="Verdana" font-size="11">coverage</text>
+<text x="66" y="14" fill="#fff" font-family="Verdana" font-size="11">84%</text>
+</svg>

data/lib/jekyll-is/hookdown/converter.rb

@@ -2,10 +2,13 @@
 
 require 'jekyll'
 
-require_relative 'jekyll_patch'
+require_relative 'setup'
 
+# @private
 class Jekyll::Converters::Markdown::Hookdown < Jekyll::Converters::Markdown::KramdownParser
 
+  # @param [String] content
+  # @return [String]
   def convert content
     document = Kramdown::JekyllDocument.new content, @config
     page = JekyllIS::Hookdown::current_page

data/lib/jekyll-is/hookdown/extra.rb

@@ -3,12 +3,20 @@
 require 'set'
 require 'kramdown'
 
-require_relative 'jekyll_patch'
+require_relative 'setup'
 
 module JekyllIS::Hookdown
 
   class << self
 
+    # @param [Symbol, Array<Symbol>] owner
+    # @param [Array<Symbol>] elements
+    # @param [Integer, Symbol] priority
+    # @return [Proc, nil]
+    # @yield Hook block
+    # @yieldparam [Jekyll::Page, Jekyll::Document] page
+    # @yieldparam [Kramdown::Element] element
+    # @yieldreturn [nil, Kramdown::Element, :delete]
     def register_element_hook owner, *elements, priority: Jekyll::Hooks::DEFAULT_PRIORITY, &block
       if enabled?
         priority = Jekyll::Hooks::priority_value(priority)
@@ -23,14 +31,17 @@ module JekyllIS::Hookdown
         end
         block
       else
-        false
+        nil
       end
     end
 
+    # @param [Proc] block
+    # @return [void]
     def unregister_element_hook block
       if @hooks
         @hooks.reject! { it[:block] == block }
       end
+      nil
     end
 
     private

data/lib/jekyll-is/hookdown/info.rb

@@ -7,7 +7,7 @@ module JekyllIS::Hookdown; end
 module JekyllIS::Hookdown::Info
 
   NAME     = 'jekyll-is-hookdown'
-  VERSION  = '0.8.0.4'
+  VERSION  = '0.8.0.6'
   SUMMARY  = 'Hooked Kramdown for Jekyll'
   LICENSE  = 'LGPL-3.0-or-later'
   AUTHOR   = 'Ivan Shikhalev'

data/lib/jekyll-is/hookdown/setup.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require 'jekyll'
+
+require_relative 'info'
+
+module JekyllIS::Hookdown
+
+  class << self
+
+    # @return [Jekyll::Page or Jekyll::Document]
+    def current_page
+      Thread::current[:hookdown_current_page]
+    end
+
+    # @param [Jekyll::Site, nil] site
+    def enabled? site = nil
+      @site ||= site
+      @enabled ||= setup
+    end
+
+    private
+
+    def setup
+      enabled = if @site
+        @site.config['markdown'] == 'Hookdown'
+      else
+        # Fallback
+        Jekyll::configuration['markdown'] == 'Hookdown'
+      end
+      if enabled
+        registry = Jekyll::Hooks.instance_variable_get :@registry
+        [ :pages, :posts, :documents ].each do |owner|
+          registry[owner][:post_parse] ||= [] if registry[owner]
+        end
+        Jekyll::Hooks::register [ :pages, :documents ], :pre_render do |page|
+          Thread::current[:hookdown_current_page] = page
+        end
+        Jekyll::Hooks::register [ :pages, :documents ], :post_render do |page|
+          if Thread::current[:hookdown_current_page] == page
+            Thread::current[:hookdown_current_page] = nil
+          else
+            Jekyll::logger.warn JekyllIS::Hookdown::Info::NAME, "Mismatch pages: #{ page.inspect } vs #{ Thread::current[:hookdown_current_page].inspect }"
+          end
+        end
+      end
+      enabled
+    end
+
+  end
+
+end
+
+Jekyll::Hooks::register :site, :after_init, priority: 50 do |site|
+  if JekyllIS::Hookdown::enabled?(site)
+    Jekyll::logger.info JekyllIS::Hookdown::Info::NAME, 'JekyllIS::Hookdown enabled.'
+  else
+    Jekyll::logger.warn JekyllIS::Hookdown::Info::NAME, 'JekyllIS::Hookdown disabled.'
+  end
+end

data/lib/jekyll-is/hookdown.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
-require_relative 'hookdown/jekyll_patch'
+require_relative 'hookdown/setup'
 require_relative 'hookdown/converter'
 require_relative 'hookdown/extra'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-is-hookdown
 version: !ruby/object:Gem::Version
-  version: 0.8.0.4
+  version: 0.8.0.6
 platform: ruby
 authors:
 - Ivan Shikhalev
@@ -79,6 +79,76 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: is-module-reset
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: redcarpet
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: yard-markdown-relative-links
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 description: Hooked Kramdown for Jekyll.
 email:
 - shikhalev@gmail.com
@@ -87,13 +157,15 @@ extensions: []
 extra_rdoc_files: []
 files:
 - LICENSE
+- README-ru.md
 - README.md
+- coverage-badge.svg
 - lib/jekyll-is-hookdown.rb
 - lib/jekyll-is/hookdown.rb
 - lib/jekyll-is/hookdown/converter.rb
 - lib/jekyll-is/hookdown/extra.rb
 - lib/jekyll-is/hookdown/info.rb
-- lib/jekyll-is/hookdown/jekyll_patch.rb
+- lib/jekyll-is/hookdown/setup.rb
 homepage: https://github.com/jekyll-is/jekyll-is-hookdown
 licenses:
 - LGPL-3.0-or-later

data/lib/jekyll-is/hookdown/jekyll_patch.rb

@@ -1,50 +0,0 @@
-# frozen_string_literal: true
-
-require 'jekyll'
-
-require_relative 'info'
-
-module JekyllIS::Hookdown
-
-  class << self
-
-    def apply_patch
-      registry = Jekyll::Hooks.instance_variable_get :@registry
-      [ :pages, :posts, :documents ].each do |owner|
-        registry[owner][:post_parse] ||= [] if registry[owner]
-      end
-    end
-
-    def current_page
-      Thread::current[:hookdown_current_page]
-    end
-
-    def current_page= value
-      Thread::current[:hookdown_current_page] = value
-    end
-
-    def enabled?
-      Jekyll::configuration['markdown'] == 'Hookdown'
-    end
-
-  end
-
-end
-
-if JekyllIS::Hookdown::enabled?
-
-  JekyllIS::Hookdown::apply_patch
-
-  Jekyll::Hooks::register [ :pages, :documents ], :pre_render do |page|
-    JekyllIS::Hookdown::current_page = page
-  end
-
-  Jekyll::Hooks::register [ :pages, :documents ], :post_render do |page|
-    if JekyllIS::Hookdown::current_page == page
-      JekyllIS::Hookdown::current_page = nil
-    else
-      Jekyll::logger.warn JekyllIS::Hookdown::Info::NAME, "Mismatch pages: #{ page.inspect } vs #{ JekyllIS::Hookdown::current_page.inspect }"
-    end
-  end
-
-end