Allow configuring base URL in page front matter (#72)

Merge pull request 72

README.md

@@ -37,6 +37,8 @@ Hey @benbalter, what do you think of this?
 
 ## Configuration
 
+### Within the `_config.yml`
+
 Have your own social network? No problem. We allow you to configure the base URL of all the mentions.
 
 To change it, add the following to your Jekyll configuration:
@@ -52,14 +54,45 @@ If you're lazy like me, you can use this shorthand:
 jekyll-mentions: https://twitter.com
 ```
 
-An example of Twitter mentions using jekyll-mentions: 
+An example of Twitter mentions using jekyll-mentions:
 
 ```yaml
 plugins:
   - jekyll-mentions
 
 jekyll-mentions:
   base_url: https://twitter.com
-```  
+```
 
 Et voilà! Your mentions will now use that base URL instead of the default of `https://github.com`.
+
+### Within a page's front matter
+
+Now do you want to override the base URL for just a single page/post? No problem. Just set the base URL for that specific page in the front matter:
+
+```yaml
+jekyll-mentions:
+  base_url: https://facebook.com
+```
+
+You also can use this shorthand:
+
+```yaml
+jekyll-mentions: https://facebook.com
+```
+
+Now, every single mentions in the site will use the base URL defined in the `_config.yml`, _except_ in the file where you set the base URL to be something different.
+
+If you wish to change the base URL for a single mention, but not every mentions in that file, then you'll have to link to the URL the old-fashioned way:
+
+```markdown
+[@benbalter](https://instagram.com/benbalter)
+```
+
+Now, let's say you have a single file where you _don't_ want your mentions to become mentionable, AKA you want that to stay plain text. You can do that by specifying `false` in the front matter of that file:
+
+```yaml
+jekyll-mentions: false
+```
+
+Now that page/post's mentions will not link to the profiles.

lib/jekyll-mentions.rb

@@ -18,7 +18,8 @@ def mentionify(doc)
         content = doc.output
         return unless content.include?("@")
 
-        src = mention_base(doc.site.config)
+        src = mention_base(doc.site.config.merge(doc.data || {}))
+
         if content.include? BODY_START_TAG
           head, opener, tail  = content.partition(OPENING_BODY_TAG_REGEX)
           body_content, *rest = tail.partition("</body>")
@@ -57,12 +58,13 @@ def filters
       end
 
       # Public: Calculate the base URL to use for mentioning.
-      # The custom base URL can be defined in the config as
-      # jekyll-mentions.base_url or jekyll-mentions, and must
-      # be a valid URL (i.e. it must include a protocol and valid domain)
+      #
+      # The custom base URL can be defined in either the site config or a document's
+      # front matter as `jekyll-mentions.base_url` or `jekyll-mentions`, and must be
+      # a valid URL (i.e. it must include a protocol and valid domain).
       # It should _not_ have a trailing slash.
       #
-      # config - the hash-like configuration of the document's site
+      # config - The effective configuration that includes configurations for mentions.
       #
       # Returns a URL to use as the base URL for mentions.
       # Defaults to the https://github.com.
@@ -82,14 +84,15 @@ def mention_base(config = {})
         end
       end
 
-      # Public: Defines the conditions for a document to be emojiable.
+      # Public: Defines the conditions for a document to be mentionable.
       #
       # doc - the Jekyll::Document or Jekyll::Page
       #
       # Returns true if the doc is written & is HTML.
       def mentionable?(doc)
         (doc.is_a?(Jekyll::Page) || doc.write?) &&
-          doc.output_ext == ".html" || (doc.permalink&.end_with?("/"))
+          (doc.output_ext == ".html" || (doc.permalink&.end_with?("/"))) &&
+          (doc.data["jekyll-mentions"] != false)
       end
 
       private

spec/fixtures/custom-url-01.md

@@ -0,0 +1,7 @@
+---
+title: custom URL 01
+jekyll-mentions: https://custom-url.com
+---
+
+test @TestUser test
+> test

spec/fixtures/custom-url-02.md

@@ -0,0 +1,8 @@
+---
+title: custom URL 02
+jekyll-mentions:
+  base_url: https://custom-url.com
+---
+
+test @TestUser test
+> test

spec/fixtures/disabled-mentioning.md

@@ -0,0 +1,7 @@
+---
+title: ignore all mentions
+jekyll-mentions: false
+---
+
+test @TestUser test
+> test

spec/mentions_spec.rb

@@ -28,6 +28,11 @@
   let(:doc_with_liquid) { find_by_title(site.collections["docs"].docs, "With Liquid") }
   let(:txt_doc) { find_by_title(site.collections["docs"].docs, "Don't Touch Me") }
   let(:spl_chars_doc) { find_by_title(site.collections["docs"].docs, "Unconventional Names") }
+  let(:index_page) { find_by_title(site.pages, "I'm a page") }
+  let(:minified_page) { find_by_title(site.pages, "I'm minified!") }
+  let(:disabled_mentioning_page) { find_by_title(site.pages, "ignore all mentions") }
+  let(:custom_url_01) { find_by_title(site.pages, "custom URL 01") }
+  let(:custom_url_02) { find_by_title(site.pages, "custom URL 02") }
 
   def para(content)
     "<p>#{content}</p>"
@@ -60,16 +65,16 @@ def para(content)
   end
 
   it "correctly replaces the mentions with the link in pages" do
-    expect(site.pages.first.output).to include(para(result))
+    expect(index_page.output).to include(para(result))
   end
 
   it "correctly replaces the mentions with the link in minified pages" do
-    expect(find_by_title(site.pages, "I'm minified!").output).to include(para(result))
+    expect(minified_page.output).to include(para(result))
   end
 
   it "doesn't mangle layouts" do
-    expect(site.pages.first.output).to include("<html lang=\"en-US\">")
-    expect(site.pages.first.output).to include("<body class=\"wrap\">\n")
+    expect(index_page.output).to include("<html lang=\"en-US\">")
+    expect(index_page.output).to include("<body class=\"wrap\">\n")
   end
 
   it "correctly replaces the mentions with the link in collection documents" do
@@ -86,6 +91,50 @@ def para(content)
     )
   end
 
+  context "when jekyll-mentions is set to false" do
+    it "should not replace the @TestUser with the link to @TestUser" do
+      expect(disabled_mentioning_page.output).not_to include(result)
+    end
+
+    it "should leave other pages in the site alone and mention as normal" do
+      expect(index_page.output).to include(result)
+    end
+  end
+
+  context "when the jekyll-mentions is overridden on a single file" do
+    let(:custom_url_result) do
+      "<a href=\"https://custom-url.com/TestUser\" class=\"user-mention\">@TestUser</a>"
+    end
+
+    context "when overriden in pattern 'jekyll-mentions: custom_url'" do
+      it "should replace the mentions with the link in that specific file" do
+        expect(custom_url_01.output).to include(custom_url_result)
+      end
+
+      it "should not include the default URL" do
+        expect(custom_url_01.output).not_to include(result)
+      end
+
+      it "should leave other pages in the site alone and mention as normal" do
+        expect(index_page.output).to include(result)
+      end
+    end
+
+    context "when overriden in pattern 'jekyll-mentions.base_url: custom_url'" do
+      it "should replace the mentions with the link in that specific file" do
+        expect(custom_url_02.output).to include(custom_url_result)
+      end
+
+      it "should not include the default URL" do
+        expect(custom_url_02.output).not_to include(result)
+      end
+
+      it "should leave other pages in the site alone and mention as normal" do
+        expect(index_page.output).to include(result)
+      end
+    end
+  end
+
   context "with non-word characters" do
     it "does not render when there's a leading hyphen" do
       expect(spl_chars_doc.output).to start_with(para("Howdy @-pardner!"))
@@ -126,11 +175,30 @@ def para(content)
       expect(mentions.mention_base(site.config)).to eql(mentions_src)
     end
 
-    it "respects the new base when mentionsfying" do
+    it "respects the new base when mentionifying" do
       expect(basic_post.output).to start_with(para(result.sub(default_src, mentions_src)))
     end
   end
 
+  context "when the different base is defined in the front matter of the doc" do
+    let(:mentions_src) { "https://twitter.com" }
+    let(:doc_overrides) do
+      {
+        "jekyll-mentions" => { "base_url" => mentions_src },
+      }
+    end
+    let(:config_overrides) do
+      {
+        "jekyll-mentions" => { "base_url" => default_src },
+      }
+    end
+
+    it "fetches the custom base from the config" do
+      effective_overrides = site.config.merge(doc_overrides)
+      expect(mentions.mention_base(effective_overrides)).to eql(mentions_src)
+    end
+  end
+
   context "with the SSL and GITHUB_HOSTNAME environment variables set" do
     let(:ssl)                  { "true" }
     let(:github_hostname)      { "github.vm" }