adamsdesk
/
jekyll-seo-tag
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #212 from jekyll/docs 

Move docs to their own folder
This commit is contained in:
Ben Balter 2017-07-14 11:52:18 -07:00 committed by GitHub
parent 264aabad6f 8dc1719b81
commit 3ba744cf43
10 changed files with 243 additions and 206 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
.gitignore vendored
View File

@ -9,3 +9,4 @@
/tmp/
/bin/
*.gem
_site

2
Gemfile
View File

@ -3,3 +3,5 @@ require "json"
require "open-uri"
gemspec
gem "github-pages", :group => :jekyll_plugins

207
README.md
View File

@ -45,209 +45,6 @@ Jekyll SEO tag isn't designed to accommodate every possible use case. It should
{% seo %}
```
## Usage
## Documentation
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.)
* `description` - A short description (e.g., A blog dedicated to reviewing cat gifs)
* `url` - The full URL to your site. Note: `site.github.url` will be used by default.
* `author` - global author information (see below)
* `twitter:username` - The site's Twitter handle. You'll want to describe it like so:
```yml
twitter:
username: benbalter
```
* `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`)
* `social` - For [specifying social profiles](https://developers.google.com/structured-data/customize/social-profiles). 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.
* `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.
```yml
social:
name: Ben Balter
links:
- https://twitter.com/BenBalter
- https://www.facebook.com/ben.balter
- https://www.linkedin.com/in/BenBalter
- https://plus.google.com/+BenBalter
- https://github.com/benbalter
- https://keybase.io/benbalter
```
* `google_site_verification` for verifying ownership via Google webmaster tools
* Alternatively, verify ownership with several services at once using the following format:
```yml
webmaster_verifications:
google: 1234
bing: 1234
alexa: 1234
yandex: 1234
```
* `lang` - The locale these tags are marked up in. Of the format `language_TERRITORY`. Default is `en_US`.
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 below)
* `lang` - Page-, post-, or document-specific language information
## 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:
```
{% seo title=false %}
```
### 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](http://schema.org/docs/schemas.html), and will probably usually be something like [`BlogPosting`](http://schema.org/BlogPosting), [`NewsArticle`](http://schema.org/NewsArticle), [`Person`](http://schema.org/Person), [`Organization`](http://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.
### 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 default](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/templates/). 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="http://yoursite.com/title-of-your-post" />
```
See [the documentation](https://jekyll.github.io/jekyll-seo-tag) for more information.

3
docs/README.md Normal file
View File

@ -0,0 +1,3 @@
* [Usage](usage.md)
* [Advanced usage](advanced-usage.md)

10
docs/_config.yml Normal file
View File

@ -0,0 +1,10 @@
title: Jekyll SEO Tag
description: A Jekyll plugin to add metadata tags for search engines and social networks to better index and display your site's content.
permalink: pretty
gems:
- jekyll-seo-tag
- jekyll-sitemap
theme: jekyll-theme-primer

16
docs/_layouts/default.html Normal file
View File

@ -0,0 +1,16 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link href="{{ '/assets/css/style.css?v=' | append: site.github.build_revision | relative_url }}" rel="stylesheet">
{% seo %}
</head>
<body>
<div class="container markdown-body">
<h1>{{ site.title }}</h1>
{{ content }}
</div>
</body>
</html>

138
docs/advanced-usage.md Normal file
View File

@ -0,0 +1,138 @@
## 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:
```
{% seo title=false %}
```
### 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](http://schema.org/docs/schemas.html), and will probably usually be something like [`BlogPosting`](http://schema.org/BlogPosting), [`NewsArticle`](http://schema.org/NewsArticle), [`Person`](http://schema.org/Person), [`Organization`](http://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.
### 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 default](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/templates/). 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="http://yoursite.com/title-of-your-post" />
```

67
docs/usage.md Normal file
View File

@ -0,0 +1,67 @@
## 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.)
* `description` - A short description (e.g., A blog dedicated to reviewing cat gifs)
* `url` - The full URL to your site. Note: `site.github.url` will be used by default.
* `author` - global author information (see below)
* `twitter:username` - The site's Twitter handle. You'll want to describe it like so:
```yml
twitter:
username: benbalter
```
* `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`)
* `social` - For [specifying social profiles](https://developers.google.com/structured-data/customize/social-profiles). 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.
* `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.
```yml
social:
name: Ben Balter
links:
- https://twitter.com/BenBalter
- https://www.facebook.com/ben.balter
- https://www.linkedin.com/in/BenBalter
- https://plus.google.com/+BenBalter
- https://github.com/benbalter
- https://keybase.io/benbalter
```
* `google_site_verification` for verifying ownership via Google webmaster tools
* Alternatively, verify ownership with several services at once using the following format:
```yml
webmaster_verifications:
google: 1234
bing: 1234
alexa: 1234
yandex: 1234
```
* `lang` - The locale these tags are marked up in. Of the format `language_TERRITORY`. Default is `en_US`.
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 below)
* `lang` - Page-, post-, or document-specific language information

3
script/site Executable file
View File

@ -0,0 +1,3 @@
#!/bin/sh
bundle exec jekyll serve --source docs

2
spec/jekyll_seo_tag/drop_spec.rb
View File

@ -213,7 +213,7 @@ RSpec.describe Jekyll::SeoTag::Drop do
end
context "with no descriptions" do
let(:page_meta) { { "description"=> nil, "excerpt" => nil } }
let(:page_meta) { { "description" => nil, "excerpt" => nil } }
let(:config) { { "description"=> nil } }
it "uses returns nil" do