jekyll-soopr-seo-tag 2.7.3

data/docs/advanced-usage.md

@@ -0,0 +1,156 @@
+## Advanced usage
+
+Jekyll SEO Tag is designed to implement SEO best practices by default and to be the right fit for most sites right out of the box. If for some reason, you need more control over the output, read on:
+
+### Disabling `<title>` output
+
+If for some reason, you don't want the plugin to output `<title>` tags on each page, simply invoke the plugin within your template like so:
+
+<!-- {% raw %} -->
+```
+{% seo title=false %}
+```
+<!-- {% endraw %} -->
+
+### Author information
+
+Author information is used to propagate the `creator` field of Twitter summary cards. This should be an author-specific, not site-wide Twitter handle (the site-wide username be stored as `site.twitter.username`).
+
+*TL;DR: In most cases, put `author: [your Twitter handle]` in the document's front matter, for sites with multiple authors. If you need something more complicated, read on.*
+
+There are several ways to convey this author-specific information. Author information is found in the following order of priority:
+
+1. An `author` object, in the documents's front matter, e.g.:
+
+  ```yml
+  author:
+    twitter: benbalter
+  ```
+
+2. An `author` object, in the site's `_config.yml`, e.g.:
+
+  ```yml
+  author:
+    twitter: benbalter
+  ```
+
+3. `site.data.authors[author]`, if an author is specified in the document's front matter, and a corresponding key exists in `site.data.authors`. E.g., you have the following in the document's front matter:
+
+  ```yml
+  author: benbalter
+  ```
+
+  And you have the following in `_data/authors.yml`:
+
+  ```yml
+  benbalter:
+    picture: /img/benbalter.png
+    twitter: jekyllrb
+
+  potus:
+    picture: /img/potus.png
+    twitter: whitehouse
+  ```
+
+  In the above example, the author `benbalter`'s Twitter handle will be resolved to `@jekyllrb`. This allows you to centralize author information in a single `_data/authors` file for site with many authors that require more than just the author's username.
+
+  *Pro-tip: If `authors` is present in the document's front matter as an array (and `author` is not), the plugin will use the first author listed, as Twitter supports only one author.*
+
+4. An author in the document's front matter (the simplest way), e.g.:
+
+  ```yml
+  author: benbalter
+  ```
+
+5. An author in the site's `_config.yml`, e.g.:
+
+  ```yml
+  author: benbalter
+  ```
+
+### Customizing JSON-LD output
+
+The following options can be set for any particular page. While the default options are meant to serve most users in the most common circumstances, there may be situations where more precise control is necessary.
+
+* `seo`
+  * `name` - If the name of the thing that the page represents is different from the page title. (i.e.: "Frank's Café" vs "Welcome to Frank's Café")
+  * `type` - The type of things that the page represents. This must be a [Schema.org type](https://schema.org/docs/schemas.html), and will probably usually be something like [`BlogPosting`](https://schema.org/BlogPosting), [`NewsArticle`](https://schema.org/NewsArticle), [`Person`](https://schema.org/Person), [`Organization`](https://schema.org/Organization), etc.
+  * `links` - An array of other URLs that represent the same thing that this page represents. For instance, Jane's bio page might include links to Jane's GitHub and Twitter profiles.
+  * `date_modified` - Manually specify the `dateModified` field in the JSON-LD output to override Jekyll's own `dateModified`.
+  This field will take **first priority** for the `dateModified` JSON-LD output. This is useful when the file timestamp does not match the true time that the content was modified. A user may also install [Last Modified At](https://github.com/gjtorikian/jekyll-last-modified-at) which will offer an alternative way of providing for the `dateModified` field.
+
+### Customizing image output
+
+For most users, setting `image: [path-to-image]` on a per-page basis should be enough. If you need more control over how images are represented, the `image` property can also be an object, with the following options:
+
+* `path` - The relative path to the image. Same as `image: [path-to-image]`
+* `height` - The height of the Open Graph (`og:image`) image
+* `width` - The width of the Open Graph (`og:image`) image
+
+You can use any of the above, optional properties, like so:
+
+```yml
+image:
+  path: /img/twitter.png
+  height: 100
+  width: 100
+```
+
+### Setting a default image
+
+You can define a default image using [Front Matter defaults](https://jekyllrb.com/docs/configuration/front-matter-defaults/), to provide a default Twitter Card or OGP image to all of your posts and pages.
+
+Here is a very basic example, that you are encouraged to adapt to your needs:
+
+```yml
+defaults:
+  - scope:
+      path: ""
+    values:
+      image: /assets/images/default-card.png
+```
+
+### SmartyPants Titles
+
+Titles will be processed using [Jekyll's `smartify` filter](https://jekyllrb.com/docs/liquid/filters/). This will use SmartyPants to translate plain ASCII punctuation into "smart" typographic punctuation. This will not render or strip any Markdown you may be using in a page title.
+
+### Setting customized Canonical URL
+
+You can set custom Canonical URL for a page by specifying canonical_url option in page front matter.
+E.g., you have the following in the page's front matter:
+```yml
+layout: post
+title: Title of Your Post
+canonical_url: 'https://github.com/jekyll/jekyll-seo-tag/'
+```
+
+Which will generate canonical_url with specified link in canonical_url.
+```html
+<link rel="canonical" href="https://github.com/jekyll/jekyll-seo-tag/" />
+```
+
+If no canonical_url option was specified, then uses page url for generating canonical_url.
+E.g., you have not specified canonical_url in front matter:
+```yml
+layout: post
+title: Title of Your Post
+```
+
+Which will generate following canonical_url:
+```html
+<link rel="canonical" href="https://example.com/title-of-your-post" />
+```
+
+### Customizing title modifier for paginated pages
+
+You can override the default title modifier for paginated pages from `Page %{current} of %{total} for ` to a string of your
+choice by setting a `seo_paginator_message` key in your `_config.yml`.
+
+For example:  
+
+```yml
+seo_paginator_message: "%<current>s / %<total>s | "
+```
+
+While the value can be any string text, we recommend using a Ruby string-template containing the variables `current` and `total`
+similar to the example above, to incorporate the current page-number and total number of paginated pages in the title.

data/docs/installation.md

@@ -0,0 +1,24 @@
+# Installing Jekyll SEO Tag
+
+1. Add the following to your site's `Gemfile`:
+
+  ```ruby
+  gem 'jekyll-seo-tag'
+  ```
+
+2. Add the following to your site's `_config.yml`:
+
+  ```yml
+  plugins:
+    - jekyll-seo-tag
+  ```
+
+If you are using a Jekyll version less than `3.5.0`, use the `gems` key instead of `plugins`.
+
+3. Add the following right before `</head>` in your site's template(s):
+
+<!-- {% raw %} -->
+  ```liquid
+  {% seo %}
+  ```
+<!-- {% endraw %} -->

data/docs/usage.md

@@ -0,0 +1,80 @@
+## Usage
+
+The SEO tag will respect any of the following if included in your site's `_config.yml` (and simply not include them if
+they're not defined):
+
+* `title` - Your site's title (e.g., *Ben's Awesome Site*, *The GitHub Blog*, etc.), used as part of the title tag like
+`Home | Ben's Awesome Site`.
+* `tagline` - A short description (e.g., *A blog dedicated to reviewing cat gifs*), used as part of the title tag like
+`Ben's Awesome Site | A blog dedicated to reviewing cat gifs` instead of `Ben's Awesome Site | Long description about a
+blog dedicated to reviewing cat gifs` that would be used when `page.title` is not defined.
+* `description` - A longer description used for the description meta tag. Also used as fallback for pages that don't
+provide their own `description`, and also as part of the page's title tag if neither `page.title` nor `site.tagline`
+has been defined.
+* `url` - The full URL to your site. Note: `site.github.url` will be used by default.
+* `author` - global author information (see [Advanced usage](advanced-usage.md#author-information))
+* `twitter` - The following properties are available:
+  * `twitter:card` - The site's default card type
+  * `twitter:username` - The site's Twitter handle.
+
+  You'll want to describe them like so:
+
+  ```yml
+  twitter:
+    username: benbalter
+    card: summary
+  ```
+* `facebook` - The following properties are available:
+  * `facebook:app_id` - a Facebook app ID for Facebook insights
+  * `facebook:publisher` - a Facebook page URL or ID of the publishing entity
+  * `facebook:admins` - a Facebook user ID for domain insights linked to a personal account
+
+  You'll want to describe one or more like so:
+
+  ```yml
+  facebook:
+    app_id: 1234
+    publisher: 1234
+    admins: 1234
+  ```
+* `logo` - URL to a site-wide logo (e.g., `/assets/your-company-logo.png`) - If you would like the "publisher" property
+to be present, you must add this field to your site's configuration, during the validation of the structured data by
+Google Search Console, if the `logo` field is not validated, you will find errors inherent to the publisher in the
+[Rich Results Testing Tool](https://search.google.com/test/rich-results)
+* `social` - For [specifying social profiles](https://developers.google.com/search/docs/guides/enhance-site#add-your-sites-name-logo-and-social-links).
+The following properties are available:
+  * `name` - If the user or organization name differs from the site's name
+  * `links` - An array of links to social media profiles.
+
+  ```yml
+  social:
+    name: Ben Balter
+    links:
+      - https://twitter.com/BenBalter
+      - https://www.facebook.com/ben.balter
+      - https://www.linkedin.com/in/BenBalter
+      - https://github.com/benbalter
+      - https://keybase.io/benbalter
+  ```
+* `google_site_verification` for verifying ownership via Google Search Console
+* Alternatively, verify ownership with several services at once using the following format:
+  ```yml
+  webmaster_verifications:
+    google: 1234
+    bing: 1234
+    alexa: 1234
+    yandex: 1234
+    baidu: 1234
+  ```
+* `locale` - The locale these tags are marked up in. Of the format `language_TERRITORY`. Default is `en_US`. Takes priority
+over existing config key `lang`.
+
+The SEO tag will respect the following YAML front matter if included in a post, page, or document:
+
+* `title` - The title of the post, page, or document
+* `description` - A short description of the page's content
+* `image` - URL to an image associated with the post, page, or document (e.g., `/assets/page-pic.jpg`)
+* `author` - Page-, post-, or document-specific author information (see [Advanced usage](advanced-usage.md#author-information))
+* `locale` - Page-, post-, or document-specific locale information. Takes priority over existing front matter attribute `lang`.
+
+*Note:* Front matter defaults can be used for any of the above values as described in advanced usage with an image example.

data/jekyll-soopr-seo-tag.gemspec

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "lib/jekyll-seo-tag/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "jekyll-soopr-seo-tag"
+  spec.version       = Jekyll::SeoTag::VERSION
+  spec.authors       = ["Ben Balter"]
+  spec.email         = ["ben.balter@github.com"]
+  spec.summary       = "A Jekyll plugin to add metadata tags for search engines and social networks to better index and display your site's content."
+  spec.homepage      = "https://github.com/abhinavs/jekyll-soopr-seo-tag"
+  spec.license       = "MIT"
+
+  # Prevent pushing this gem to RubyGems.org by setting 'allowed_push_host', or
+  # delete this section to allow pushing this gem to any host.
+  if spec.respond_to?(:metadata)
+    spec.metadata["allowed_push_host"] = "https://rubygems.org"
+  else
+    raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
+  end
+
+  spec.required_ruby_version = ">= 2.4.0"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r!^(test|spec|features)/!) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r!^exe/!) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "jekyll", ">= 3.8", "< 5.0"
+  spec.add_development_dependency "bundler", ">= 1.15"
+  spec.add_development_dependency "html-proofer", "~> 3.7"
+  spec.add_development_dependency "rspec", "~> 3.5"
+  spec.add_development_dependency "rubocop-jekyll", "~> 0.11"
+end

data/lib/jekyll-seo-tag/author_drop.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class SeoTag
+    # A drop representing the current page's author
+    #
+    # Author name will be pulled from:
+    #
+    # 1. The page's `author` key
+    # 2. The first author in the page's `authors` key
+    # 3. The `author` key in the site config
+    #
+    # If the result from the name search is a string, we'll also check
+    # for additional author metadata in `site.data.authors`
+    class AuthorDrop < Jekyll::Drops::Drop
+      # Initialize a new AuthorDrop
+      #
+      # page - The page hash (e.g., Page#to_liquid)
+      # site - The Jekyll::Drops::SiteDrop
+      def initialize(page: nil, site: nil)
+        raise ArgumentError unless page && site
+
+        @mutations = {}
+        @page = page
+        @site = site
+      end
+
+      # AuthorDrop#to_s should return name, allowing the author drop to safely
+      # replace `page.author`, if necessary, and remain backwards compatible
+      def name
+        author_hash["name"]
+      end
+      alias_method :to_s, :name
+
+      def twitter
+        return @twitter if defined? @twitter
+
+        twitter = author_hash["twitter"] || author_hash["name"]
+        @twitter = twitter.is_a?(String) ? twitter.sub(%r!^@!, "") : nil
+      end
+
+      private
+
+      attr_reader :page
+      attr_reader :site
+
+      # Finds the page author in the page.author, page.authors, or site.author
+      #
+      # Returns a string or hash representing the author
+      def resolved_author
+        return @resolved_author if defined? @resolved_author
+
+        sources = [page["author"]]
+        sources << page["authors"].first if page["authors"].is_a?(Array)
+        sources << site["author"]
+        @resolved_author = sources.find { |s| !s.to_s.empty? }
+      end
+
+      # If resolved_author is a string, attempts to find coresponding author
+      # metadata in `site.data.authors`
+      #
+      # Returns a hash representing additional metadata or an empty hash
+      def site_data_hash
+        @site_data_hash ||= begin
+          return {} unless resolved_author.is_a?(String)
+          return {} unless site.data["authors"].is_a?(Hash)
+
+          author_hash = site.data["authors"][resolved_author]
+          author_hash.is_a?(Hash) ? author_hash : {}
+        end
+      end
+
+      # Returns the normalized author hash representing the page author,
+      # including site-wide metadata if the author is provided as a string,
+      # or an empty hash, if the author cannot be resolved
+      def author_hash
+        @author_hash ||= begin
+          if resolved_author.is_a? Hash
+            resolved_author
+          elsif resolved_author.is_a? String
+            { "name" => resolved_author }.merge!(site_data_hash)
+          else
+            {}
+          end
+        end
+      end
+
+      # Since author_hash is aliased to fallback_data, any values in the hash
+      # will be exposed via the drop, allowing support for arbitrary metadata
+      alias_method :fallback_data, :author_hash
+    end
+  end
+end

data/lib/jekyll-seo-tag/drop.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Jekyll
+  class SeoTag
+    class Drop < Jekyll::Drops::Drop
+      include Jekyll::SeoTag::UrlHelper
+
+      TITLE_SEPARATOR = " | "
+      FORMAT_STRING_METHODS = [
+        :markdownify, :strip_html, :normalize_whitespace, :escape_once,
+      ].freeze
+      HOMEPAGE_OR_ABOUT_REGEX = %r!^/(about/)?(index.html?)?$!.freeze
+
+      EMPTY_READ_ONLY_HASH = {}.freeze
+      private_constant :EMPTY_READ_ONLY_HASH
+
+      def initialize(text, context)
+        @obj = EMPTY_READ_ONLY_HASH
+        @mutations = {}
+        @text = text
+        @context = context
+      end
+
+      def version
+        Jekyll::SeoTag::VERSION
+      end
+
+      # Should the `<title>` tag be generated for this page?
+      def title?
+        return false unless title
+        return @display_title if defined?(@display_title)
+
+        @display_title = (@text !~ %r!title=false!i)
+      end
+
+      def site_title
+        @site_title ||= format_string(site["title"] || site["name"])
+      end
+
+      def site_tagline
+        @site_tagline ||= format_string site["tagline"]
+      end
+
+      def site_description
+        @site_description ||= format_string site["description"]
+      end
+
+      # Page title without site title or description appended
+      def page_title
+        @page_title ||= format_string(page["title"]) || site_title
+      end
+
+      def site_tagline_or_description
+        site_tagline || site_description
+      end
+
+      # Page title with site title or description appended
+      # rubocop:disable Metrics/CyclomaticComplexity
+      def title
+        @title ||= begin
+          if site_title && page_title != site_title
+            page_title + TITLE_SEPARATOR + site_title
+          elsif site_description && site_title
+            site_title + TITLE_SEPARATOR + site_tagline_or_description
+          else
+            page_title || site_title
+          end
+        end
+
+        return page_number + @title if page_number
+
+        @title
+      end
+      # rubocop:enable Metrics/CyclomaticComplexity
+
+      def name
+        return @name if defined?(@name)
+
+        @name = if seo_name
+                  seo_name
+                elsif !homepage_or_about?
+                  nil
+                elsif site_social["name"]
+                  format_string site_social["name"]
+                elsif site_title
+                  site_title
+                end
+      end
+
+      def description
+        @description ||= begin
+          format_string(page["description"] || page["excerpt"]) || site_description
+        end
+      end
+
+      # A drop representing the page author
+      def author
+        @author ||= AuthorDrop.new(:page => page, :site => site)
+      end
+
+      # A drop representing the JSON-LD output
+      def json_ld
+        @json_ld ||= JSONLDDrop.new(self)
+      end
+
+      # Returns a Drop representing the page's image
+      # Returns nil if the image has no path, to preserve backwards compatability
+      def image
+        @image ||= ImageDrop.new(:page => page, :context => @context)
+        @image if @image.path
+      end
+
+      def date_modified
+        @date_modified ||= begin
+          date = page_seo["date_modified"] || page["last_modified_at"].to_liquid || page["date"]
+          filters.date_to_xmlschema(date) if date
+        end
+      end
+
+      def date_published
+        @date_published ||= filters.date_to_xmlschema(page["date"]) if page["date"]
+      end
+
+      def type
+        @type ||= begin
+          if page_seo["type"]
+            page_seo["type"]
+          elsif homepage_or_about?
+            "WebSite"
+          elsif page["date"]
+            "BlogPosting"
+          else
+            "WebPage"
+          end
+        end
+      end
+
+      def links
+        @links ||= begin
+          if page_seo["links"]
+            page_seo["links"]
+          elsif homepage_or_about? && site_social["links"]
+            site_social["links"]
+          end
+        end
+      end
+
+      def logo
+        @logo ||= begin
+          return unless site["logo"]
+
+          if absolute_url? site["logo"]
+            filters.uri_escape site["logo"]
+          else
+            filters.uri_escape filters.absolute_url site["logo"]
+          end
+        end
+      end
+
+      def page_lang
+        @page_lang ||= page["lang"] || site["lang"] || "en_US"
+      end
+
+      def page_locale
+        @page_locale ||= (page["locale"] || site["locale"] || page_lang).tr("-", "_")
+      end
+
+      def canonical_url
+        @canonical_url ||= begin
+          if page["canonical_url"].to_s.empty?
+            filters.absolute_url(page["url"]).to_s.gsub(%r!/index\.html$!, "/")
+          else
+            page["canonical_url"]
+          end
+        end
+      end
+
+      def soopr
+        @soopr ||= SooprDrop.new(:page => page, :site => site)
+        @soopr if @soopr.publish_token
+      end
+
+      private
+
+      def filters
+        @filters ||= Jekyll::SeoTag::Filters.new(@context)
+      end
+
+      def page
+        @page ||= @context.registers[:page].to_liquid
+      end
+
+      def site
+        @site ||= @context.registers[:site].site_payload["site"].to_liquid
+      end
+
+      def homepage_or_about?
+        page["url"] =~ HOMEPAGE_OR_ABOUT_REGEX
+      end
+
+      def page_number
+        return unless @context["paginator"] && @context["paginator"]["page"]
+
+        current = @context["paginator"]["page"]
+        total = @context["paginator"]["total_pages"]
+        paginator_message = site["seo_paginator_message"] || "Page %<current>s of %<total>s for "
+
+        format(paginator_message, :current => current, :total => total) if current > 1
+      end
+
+      attr_reader :context
+
+      def fallback_data
+        @fallback_data ||= {}
+      end
+
+      def format_string(string)
+        string = FORMAT_STRING_METHODS.reduce(string) do |memo, method|
+          filters.public_send(method, memo)
+        end
+
+        string unless string.empty?
+      end
+
+      def seo_name
+        @seo_name ||= format_string(page_seo["name"]) if page_seo["name"]
+      end
+
+      def page_seo
+        @page_seo ||= sub_hash(page, "seo")
+      end
+
+      def site_social
+        @site_social ||= sub_hash(site, "social")
+      end
+
+      # Safely returns a sub hash
+      #
+      # hash - the parent hash
+      # key  - the key in the parent hash
+      #
+      # Returns the sub hash or an empty hash, if it does not exist
+      def sub_hash(hash, key)
+        if hash[key].is_a?(Hash)
+          hash[key]
+        else
+          EMPTY_READ_ONLY_HASH
+        end
+      end
+    end
+  end
+end