jekyll-gfm-admonitions 0.2.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2bd3b14863c909fa009e741f378bff65b4727794fce307818a742e50859d233e
-  data.tar.gz: bcbe98766111c4a71e8f98f1ba8fe00d9c036754262d9e6bc227a3dc54a60c59
+  metadata.gz: 36fde0cfed94f6d07ba07bb23551ddfb045ba9a1d587811a78b6be9407bc4ad9
+  data.tar.gz: efcf212c70ccffeb7f4d834445adec477d2c748e15e2408ea94782bbee70852d
 SHA512:
-  metadata.gz: 57df6efea88902eefe6de29525a290de68cb78165c9924d7d95f2f583c5812d9a676eb81570fa2649ec6201b04ac2eefbfaf9bb36e298548bb6de160555502bf
-  data.tar.gz: d6f84ec3048005512cb32cde7647bfc0c02ab500a1b2bd8a74605e2a6053c66384829ac4a60b5b1b9cfc777020aab048492b7203eff770480e15f96d1a676af0
+  metadata.gz: 230a0a16955e61fd32809530db0ca343730d9ce366f89416696ca5d8f85843f824121bfa3ab816aa5c264b9761aff3b3d1eabfa72264154b748a5fdaf4121c2e
+  data.tar.gz: 2c4b40928769e81341fc9961e0a8b8c6a55c02d492e1ac93d9db6ba38912a8ba09a0c0a3c16448bf69d292282b1ccf3a2a3e837bd80287db5fe25cdb34b4b2d4

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

@@ -44,8 +44,12 @@ 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
 
@@ -67,6 +71,12 @@ module JekyllGFMAdmonitions
     end
 
     def convert_admonitions(doc)
+      code_blocks = []
+      doc.content.gsub!(/```.*?```/m) do |match|
+        code_blocks << match
+        "```{{CODE_BLOCK_#{code_blocks.length - 1}}}```"
+      end
+
       doc.content.gsub!(/>\s*\[!(IMPORTANT|NOTE|WARNING|TIP|CAUTION)\]\s*\n((?:>.*\n?)*)/) do
         type = ::Regexp.last_match(1).downcase
         title = type.capitalize
@@ -79,6 +89,10 @@ module JekyllGFMAdmonitions
           <p>#{@markdown.convert(text)}</p>
         </div>\n\n"
       end
+
+      doc.content.gsub!(/```\{\{CODE_BLOCK_(\d+)}}```/) do
+        "```#{code_blocks[$1.to_i]}```"
+      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.0
 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