README.md in jekyll-twitter-plugin-1.4.0 vs README.md in jekyll-twitter-plugin-2.0.0
- old
+ new
@@ -1,39 +1,64 @@
-## jekyll-twitter-plugin
+<img alt="Screenshot embedded tweet" src="https://raw.githubusercontent.com/rob-murray/jekyll-twitter-plugin/master/media/embedded-tweet.png" align="right" />
-A Liquid tag plugin for Jekyll that renders Tweets from Twitter API.
+# jekyll-twitter-plugin
+A Liquid tag plugin for Jekyll blogging engine that embeds Tweets, Timelines and more from Twitter API.
+
[](https://travis-ci.org/rob-murray/jekyll-twitter-plugin)
[](http://badge.fury.io/rb/jekyll-twitter-plugin)
+---
-### Description
-A Liquid tag plugin for [Jekyll](http://jekyllrb.com/) that enables Twitter content to be used in any content served by Jekyll, content is fetched from the [Twitter API](https://dev.twitter.com/home).
+## Description
-It is based on the original [Jekyll Tweet Tag](https://github.com/scottwb/jekyll-tweet-tag) from [scottwb](https://github.com/scottwb/) which has not been updated since Twitter changed their API to require certain preconditions. This version uses the excellent [Twitter gem](https://github.com/sferik/twitter) to make requests and handle authentication.
+**jekyll-twitter-plugin** is a Liquid tag plugin for [Jekyll](http://jekyllrb.com/) that enables Twitter content to be used in any pages generated by Jekyll, content is fetched from the [Twitter Publish platform](https://publish.twitter.com).
-This plugin replaces the broken [Jekyll Tweet Tag](https://github.com/scottwb/jekyll-tweet-tag) plugin mentioned above and uses a different tag name and API - this is by design so that the two plugins can be separated and you can be certain which plugin is being used. You can also install this plugin via Rubygems and require it in your Jekyll `_config.yml` file. You can use *ENV* variables or `_config.yml` file for your Twitter API secret keys.
+The [Publish platform](https://publish.twitter.com) allows Twitter users to curate content for display outside of Twitter, you can display many different types of content with the familiar Twitter styling. We use this API and allow any customisation of the content that is accepted by the Twitter publish platform.
+> You can now embed any Twitter content in your Jekyll powered blog!
-### Features
+### Here are a few examples
-The plugin supports the following features:
+#### Tweet
-* Installed via Rubygems.
-* Twitter API secrets read from *ENV* vars or `_config.yml` file.
-* [Oembed](#oembed) - Embed a Tweet in familiar Twitter styling.
-* [Caching](#caching) - Twitter API responses can be cached to avoid hitting request limits.
+An example of a Tweet - `{% twitter https://twitter.com/rubygems/status/518821243320287232 %}`
+
-### Requirements
+#### Timeline
-* Twitter oauth credentials - Most Twitter api functions now require authentication. Set up your [application](https://dev.twitter.com/apps/new) and get the credentials.
+An example of a Timeline - `{% twitter https://twitter.com/jekyllrb maxwidth=500 limit=5 %}`
+
-### Usage
+#### Grid Timeline
+An example of a Grid Timeline - `{% twitter https://twitter.com/TwitterDev/timelines/539487832448843776 limit=5 widget_type=grid maxwidth=500 %}`
+
+
+
+#### Moment
+
+An example of a Moment - `{% twitter https://twitter.com/i/moments/650667182356082688 maxwidth=500 %}`
+
+
+
+
+### Features
+
+The plugin supports the following features:
+
+* Installed via Rubygems.
+* [Customisation](#customisation) - All customisation options passed to Twitter API.
+* [Authentication](#authentication) - No authentication required!
+* [Caching](#caching) - Twitter API responses can be cached to speed up builds.
+
+
+## Getting Started
+
As mentioned by [Jekyll's documentation](http://jekyllrb.com/docs/plugins/#installing-a-plugin) you have two options; manually import the source file or require the plugin as a `gem`.
#### Require gem
@@ -47,11 +72,10 @@
```ruby
gems: ['jekyll-twitter-plugin']
```
-
#### Manual import
> Note: this is deprecated and support will be removed in a later version.
Just download the source file into your `_plugins` directory, e.g.
@@ -61,131 +85,117 @@
$ mkdir -p _plugins && cd _plugins
$ wget https://raw.githubusercontent.com/rob-murray/jekyll-twitter-plugin/master/lib/jekyll-twitter-plugin.rb
```
-#### Credentials
+#### Plugin tag usage
-Your Twitter application authentication credentials are private - do not distribute these!
+To use the plugin, in your source content use the tag `twitter` and then pass additional options to the plugin, these are passed to the API.
-You can set the authentication variables by adding them to `_config.yml`.
+```liquid
+{% plugin_type twitter_url *options %}
-```yaml
-# _config.yml
-twitter:
- consumer_key: asdf
- consumer_secret: asdf
- access_token: asdf
- access_token_secret: asdf
+# Example for timeline of the **jekyllrb** user with a maximum of 5 Tweets and with a width of 500px
+{% twitter https://twitter.com/jekyllrb maxwidth=500 limit=5 %}
```
-If the authentication variables are not present in `_config.yml` they can be gathered from
-environment variables.
+| Argument | Required? | Description |
+|---|---|---|
+| `plugin_type` | Yes | Either `twitter` or `twitternocache` (same as `twitter` but does not cache api responses) |
+| `twitter_url` | Yes | The Twitter URL to use, check below for supported URLs. |
+| `*options` | No | Parameters for the API separated by spaces. Refer below and to respective Twitter API documentation for available parameters. |
-* TWITTER_CONSUMER_KEY
-* TWITTER_CONSUMER_SECRET
-* TWITTER_ACCESS_TOKEN
-* TWITTER_ACCESS_TOKEN_SECRET
-```bash
-$ export TWITTER_CONSUMER_KEY=foo etc.
-# Or given a file .env with the keys and secrets
-$ export $(cat .env | xargs)
-```
+### Supported Twitter URLs
+The Twitter URLs that are supported depends on Twitter, we pass the url and all parameters to the API - check [Twitter Publish platform](https://publish.twitter.com) for availability. Here is documentation for some common types:
-#### Plugin tag usage
+##### Tweet:
-To use the plugin, in your source content use the tag `twitter` and then pass additional parameters to the plugin.
+* [https://dev.twitter.com/web/overview](https://dev.twitter.com/web/overview)
+* [https://dev.twitter.com/web/embedded-tweets/parameters](https://dev.twitter.com/web/embedded-tweets/parameters)
-```liquid
-{% plugin_type api_type *params %}
-```
+##### Timeline:
-| Argument | Required? | Description |
-|---|---|---|
-| `plugin_type` | Yes | Either `twitter` or `twitternocache` (same as `twitter` but does not cache api responses) |
-| `api_type` | No - defaults to **oembed** | The Twitter API to use, check below for supported APIs. |
-| `*params` | Yes* | Parameters for the API separated by spaces. Refer below and to respective Twitter API documentation for available parameters. |
+* [https://dev.twitter.com/web/embedded-timelines/oembed](https://dev.twitter.com/web/embedded-timelines/oembed)
-* Required arguments depend on the API used.
+##### Moments:
+* [https://dev.twitter.com/web/embedded-moments/oembed](https://dev.twitter.com/web/embedded-moments/oembed)
-### Supported Twitter APIs
+### Customisation
-The following Twitter APIs are supported.
+All pairs of options and values after the URL are passed to the API, the parameters must be in pairs with the option as the key: `option=value`.
+For exampled if you wanted to limit the width of the embedded content then the API supports a `maxwidth` option so you could construct the tag as below to limit it to a value of 500 (pixels).
-#### Oembed - Default
+```liquid
+{% twitter https://twitter.com/jekyllrb maxwidth=500 %}
+```
-The [oembed](https://dev.twitter.com/rest/reference/get/statuses/oembed) API returns html snippet to embed in your app, this will be rendered in the familiar Twitter style.
+### Authentication
-This API requires the `status_url` parameter, all others are optional.
+The API does not require any authentication.
-```liquid
-# With api_type specified
-{% twitter oembed status_url *options %}
-# 'oembed' autoselected by default
-{% twitter status_url *options %}
+> Previous version of this library used an API that required API keys (TWITTER_CONSUMER_KEY TWITTER_CONSUMER_SECRET TWITTER_ACCESS_TOKEN TWITTER_ACCESS_TOKEN_SECRET). We now print a warning if these are detected as a reminder that you can safely remove them.
-# Basic example
-{% twitter oembed https://twitter.com/rubygems/status/518821243320287232 %}
-# Oembed default example
-{% twitter https://twitter.com/rubygems/status/518821243320287232 %}
-# With options
-{% twitter oembed https://twitter.com/rubygems/status/518821243320287232 align='right' width='350' %}
-```
-
### Output
-As with the original plugin, all content will be rendered inside a div with the classes 'embed' and 'twitter'
+All content will be rendered inside a div with the class `jekyll-twitter-plugin`.
```html
-<div class='embed twitter'>
- -- content --
+<div class='jekyll-twitter-plugin'>
+ -- content from API --
</div>
```
If something goes wrong then a basic error message will be displayed;
> Tweet could not be processed
-If the Twitter client receives one of `Twitter::Error::NotFound, Twitter::Error::Forbidden` errors, this suggests the Tweet is protected or deleted and the following error will be displayed and cached so that it is not fetched again, and again. If the Tweet is restored then simply delete the cached response from `.tweet-cache` directory and build again.
+If we receive an error from the API then a message will be cached and rendered something like this below. If its a 404 then this suggests the Tweet is protected or deleted and it is not fetched again, and again. If the Tweet is restored then simply delete the cached response from `.tweet-cache` directory and build again.
-> There was a '{error name}' error fetching Tweet '{Tweet status url}'
+```html
+<div class='jekyll-twitter-plugin'>
+ <p>There was a '{error name}' error fetching Tweet '{Tweet status url}'</p>
+</div>
+```
-
### Caching
-Twitter API responses can be cached to speed up Jekyll site builds and avoid going over API limits. The reponses will be cached in a directory within your Jekyll project called `.tweet-cache`, ensure that this is not commit to source control.
+Twitter API responses can be cached to speed up Jekyll site builds. The reponses will be cached in a directory within your Jekyll project called `.tweet-cache`, this should not be committed to source control.
-Caching is enabled by default.
+Caching is enabled by using the `twitter` tag.
It is possible to disable caching by using the specific `twitternocache` tag.
```liquid
-{% twitternocache oembed status_url *options %}
+{% twitternocache twitter_url *options %}
# Example
-{% twitternocache oembed https://twitter.com/rubygems/status/518821243320287232 %}
+{% twitternocache https://twitter.com/rubygems/status/518821243320287232 %}
```
### Contributions
-I've tried hard to keep all classes and code in the one `lib/jekyll-twitter-plugin.rb` file so that people can just grab this file and include in their Jekyll `_plugins` directory if they do not want to use the Gem. This will be dropped in a later version.
+I've tried hard to keep all code in the one `lib/jekyll-twitter-plugin.rb` file so that people can just grab this file and include in their Jekyll `_plugins` directory if they do not want to install with Rubygems. This will be dropped in a later version.
Please use the GitHub pull-request mechanism to submit contributions.
-There is a quick integration test in `spec/integration_tests.rb` that needs API keys and will use the public api and output a file `output_test.html`. Run this with the following command:
+There is a quick integration test in `spec/integration_tests.rb` that will use the **jekyll-twitter-plugin** public api and output a file `output_test.html`. Run this with the following command:
```ruby
-$ ruby spec/integration_tests.rb
+$ ruby spec/integration_tests.rb && open output_test.html
```
-### License
+## Versioning
-This project is available for use under the MIT software license.
-See LICENSE
+We use [SemVer](http://semver.org/) for versioning. For the versions available, see the [tags on this repository](https://github.com/rob-murray/jekyll-twitter-plugin/tags).
+
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details