jekyll-gfm-admonitions 0.2.1 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bd3b14863c909fa009e741f378bff65b4727794fce307818a742e50859d233e
-  data.tar.gz: bcbe98766111c4a71e8f98f1ba8fe00d9c036754262d9e6bc227a3dc54a60c59
+  metadata.gz: 75cc2a5cd4eaf0017bf2a47ca438f1be25b4a20212faf13e3e40f048ec263cb4
+  data.tar.gz: 274fe45c83097424b627c66d721c68760298f6e2413b361d0f87cb0d62cc6462
 SHA512:
-  metadata.gz: 57df6efea88902eefe6de29525a290de68cb78165c9924d7d95f2f583c5812d9a676eb81570fa2649ec6201b04ac2eefbfaf9bb36e298548bb6de160555502bf
-  data.tar.gz: d6f84ec3048005512cb32cde7647bfc0c02ab500a1b2bd8a74605e2a6053c66384829ac4a60b5b1b9cfc777020aab048492b7203eff770480e15f96d1a676af0
+  metadata.gz: 10967a4046bd913e5611421e3fb5d2d2253fde61161b588af2c294ad79340e53143a83390590b1a7252c616df73f3e3ba7991e1f4646731d045af7960c0592bd
+  data.tar.gz: 50fc8c02dc6b000e4824bd60da24b1f324289b83784d8e6e870879eaeb65d887916e142bbb5daaf232d15617483046ac4009821e163bb3f76a83303dd7d04840

data/README.md

@@ -20,35 +20,35 @@ To use admonitions in your markdown files, simply add the following syntax:
 
 ```markdown
 > [!IMPORTANT]
-> This is an important message.
+> This is an **important** message.
 
 > [!NOTE]
-> This is a note.
+> This is a **note**.
 
 > [!TIP]
-> This is a helpful tip.
+> This is a **helpful** tip.
 
 > [!WARNING]
-> This is a warning.
+> This is a **warning**.
 
 > [!CAUTION]
-> This is a caution message.
+> This is a **caution** message.
 ```
 
 > [!IMPORTANT]
-> This is an important message.
+> This is an **important** message.
 
 > [!NOTE]
-> This is a note.
+> This is a **note**.
 
 > [!TIP]
-> This is a helpful tip.
+> This is a **helpful** tip.
 
 > [!WARNING]
-> This is a warning.
+> This is a **warning**.
 
 > [!CAUTION]
-> This is a caution message.
+> This is a **caution** message.
 
 ## Installation
 
@@ -61,9 +61,16 @@ group :jekyll_plugins do
    
    # ... Add this line:
    gem "jekyll-gfm-admonitions"
+   gem "jekyll-optional-front-matter"
 end
 ```
 
+> [!TIP]
+> 
+> By installing `jekyll-optional-front-matter` alongside this package, you won't need to
+> add ([visible](https://github.com/github/markup/issues/994)) frontmatter headers to each
+> of your files.
+
 Then run:
 
 ```bash
@@ -77,14 +84,18 @@ Next, you need to enable the plugin in your Jekyll configuration file (`_config.
 ```yaml
 plugins:
   - jekyll-gfm-admonitions
+  - jekyll-optional-front-matter
 ```
 
-Then, during build/serve, you should see a log similar to:
+Then, during `build`/`serve`, you should see logs similar to:
 
 ```
-GFMA: Converted adminitions in 1 file(s).
+GFMA: Converted adminitions in 36 file(s).
+GFMA: Injecting admonition CSS in 36 page(s).
 ```
 
+More details are available by passing the `--verbose` flag to your `jekyll` command.
+
 ## When using GitHub Pages
 
 To enable custom plugins in your Jekyll build for GitHub Pages, you need to use GitHub
@@ -92,6 +103,83 @@ Actions (GHA) to build and deploy your Jekyll site. For detailed instructions on
 up GitHub Actions for your Jekyll project, please follow this link: 
 [GitHub Actions Setup for Jekyll](https://jekyllrb.com/docs/continuous-integration/github-actions/).
 
+After following the steps you will have to set up a minimal valid Jekyll project.
+
+### Add a `_config.yml`
+
+```yaml
+# Site settings
+title: Your Project Title
+repository: your-username/your-repository
+description: >-
+  A description of your project
+
+markdown: GFM 
+plugins:
+- jekyll-gfm-admonitions
+- jekyll-optional-front-matter
+
+exclude: 
+  - "**/*.ts" # Exclude source code files!
+  - "**/*.js"
+  - "*.ts" # Also those in the root directory!
+  - "*.js"
+  - "*.json" # Don't forget about assets!
+  - node_modules/ # And large vendored directories
+  # And these ignore all the artifacts the build produces:
+  - .sass-cache/
+  - .jekyll-cache/
+  - gemfiles/
+  - Gemfile
+  - Gemfile.lock
+  - vendor/bundle/
+  - vendor/cache/
+  - vendor/gems/
+  - vendor/ruby/
+```
+
+> [!CAUTION]
+>
+> For private repositories, make sure you exclude your source code files from the Jekyll
+> build, or they might be publicly deployed! Also exclude large vendored package
+> directories such as `node_modules/`.
+
+### Add a `Gemfile`:
+
+```ruby
+source 'https://rubygems.org'
+ 
+gem 'jekyll'
+group :jekyll_plugins do
+  gem 'jekyll-gfm-admonitions'
+  gem 'jekyll-optional-front-matter'
+  gem 'github-pages'
+end
+gem 'jekyll-remote-theme'
+```
+
+### Add [front matter](https://jekyllrb.com/docs/front-matter/)
+
+This step is optional if you've added `jekyll-front-matter`. If you do not, any file
+without a front matter header will be ignored by Jekyll, and only partially included by
+the GitHub Pages plugin.
+
+Make sure that all your `.md` files begin with a valid front matter header:
+
+```markdown
+---
+---
+
+Your markdown files should start like this.
+```
+
+> [!IMPORTANT]
+> 
+> Your root `README.md` front matter should contain the following `permalink` attribute:
+> ```yaml
+> permalink: /index.html
+> ```
+
 ## License
 
 This project is licensed under the MIT License. See the [LICENSE.txt](LICENSE.txt) file

data/lib/jekyll-gfm-admonitions.rb

@@ -23,6 +23,7 @@ module JekyllGFMAdmonitions
   # syntax with HTML markup that includes appropriate iconography and CSS styling.
   class GFMAdmonitionConverter < Jekyll::Generator
     safe true
+    priority :lowest
     @@admonition_pages = []
 
     def initialize(*args)
@@ -44,8 +45,13 @@ module JekyllGFMAdmonitions
 
       # Process admonitions in pages
       site.pages.each do |page|
+        # Patch the root README for GitHub Pages builds
+        if page.path == 'README.md' && page.dir == '/'
+          Jekyll.logger.info 'GFMA:', "Patched /README.html to /index.html"
+          page.instance_variable_set(:@url, '/index.html')
+        end
+
         Jekyll.logger.debug 'GFMA:', "Processing page '#{page.path}' (#{page.content.length} characters)."
-        Jekyll.logger.debug 'GFMA:', "#{page.content.inspect}"
         process(page)
       end
 
@@ -57,7 +63,8 @@ module JekyllGFMAdmonitions
       convert_admonitions(doc)
 
       return unless doc.content != original_content
-
+      # Store a reference to all the pages we modified, to inject the CSS post render
+      # (otherwise GitHub Pages sanitizes the CSS into plaintext)
       @@admonition_pages << doc
       @converted += 1
     end
@@ -67,6 +74,15 @@ module JekyllGFMAdmonitions
     end
 
     def convert_admonitions(doc)
+      code_blocks = []
+      # Temporarily replace code blocks by a tag, so that we don't process any admonitions
+      # inside of code blocks.
+      doc.content.gsub!(/(?:^|\n)(?<!>)\s*```.*?```/m) do |match|
+        code_blocks << match
+        "```{{CODE_BLOCK_#{code_blocks.length - 1}}}```"
+      end
+
+      # Match the admonition syntax
       doc.content.gsub!(/>\s*\[!(IMPORTANT|NOTE|WARNING|TIP|CAUTION)\]\s*\n((?:>.*\n?)*)/) do
         type = ::Regexp.last_match(1).downcase
         title = type.capitalize
@@ -74,22 +90,31 @@ module JekyllGFMAdmonitions
         icon = Octicons::Octicon.new(ADMONITION_ICONS[type]).to_svg
         Jekyll.logger.debug 'GFMA:', "Converting #{type} admonition."
 
+        # Replace them by the GFM admonition HTML
         "<div class='markdown-alert markdown-alert-#{type}'>
           <p class='markdown-alert-title'>#{icon} #{title}</p>
           <p>#{@markdown.convert(text)}</p>
         </div>\n\n"
       end
+
+      # Put the code blocks back in place
+      doc.content.gsub!(/```\{\{CODE_BLOCK_(\d+)}}```/) do
+        code_blocks[$1.to_i]
+      end
     end
   end
 
-  Jekyll::Hooks.register :site, :post_render do |site|
-    Jekyll.logger.info 'GFMA:', "Injecting admonition CSS in #{GFMAdmonitionConverter.admonition_pages.length} page(s)."
+  # Insert the minified CSS before the closing head tag of all pages we put admonitions on
+  Jekyll::Hooks.register :site, :post_render do
+    Jekyll.logger.info 'GFMA:', "Inserting admonition CSS in #{GFMAdmonitionConverter.admonition_pages.length} page(s)."
 
-    for page in GFMAdmonitionConverter.admonition_pages do
+    GFMAdmonitionConverter.admonition_pages.each do |page|
       Jekyll.logger.debug 'GFMA:', "Appending admonition style to '#{page.path}'."
       css = File.read(File.expand_path('../assets/admonitions.css', __dir__))
 
-      page.output += "<style>#{CSSminify.compress(css)}</style>"
+      page.output.gsub!(/<head>(.*?)<\/head>/m) do |match|
+        "#{match[0..-7]}<style>#{CSSminify.compress(css)}</style>#{match[-7..-1]}"
+      end
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jekyll-gfm-admonitions
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 1.0.1
 platform: ruby
 authors:
 - Robin De Schepper
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-09-27 00:00:00.000000000 Z
+date: 2024-09-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: jekyll