add docs

stevenschobert · Sep 19, 2020 · 23a126c · 23a126c
1 parent 2d690eb
commit 23a126c
Show file tree

Hide file tree

Showing 7 changed files with 197 additions and 0 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,3 @@
+# Instafeed.js
+
+Instafeed.js is a simple JavaScript plugin for showing your Instagram photos on your website.
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
@@ -0,0 +1,11 @@
+# Instafeed.js <small>2.0.0</small>
+
+> A simple Instagram JS plugin for your website.
+
+- Powered by the [Instagram Basic Display API](https://developers.facebook.com/docs/instagram-basic-display-api/)
+- Lightweight (< 10kB), with 0 dependencies
+- Easily customizable with templating support
+- Maintained and supported since 2012
+
+[GitHub](https://github.com/stevenschobert/instafeed.js/)
+[Get Started](#docsify)
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -0,0 +1,4 @@
+* [Home](/)
+* [Getting Started](getting-started.md)
+* [Managing Access Tokens](managing-access-tokens.md)
+* [Migrating to v2](v2-migration-guide.md)
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,57 @@
+# Getting Started
+
+## Installation
+
+TODO
+
+## Loading
+
+Instafeed.js is compatible with all of the following loading mechanisms:
+
+* [Browser globals](#browser-globals)
+* [RequireJS](#requirejs)
+* [CommonJS (`require`)](#commonjs)
+* [ECMAScript Modules (`import`)](#ecmascript-modules)
+
+#### Browser Globals
+
+If you are loading Instafeed.js via the standard `<script>` tag, Instafeed.js will be available under the global variable `Instafeed`:
+
+```html
+<script type="text/javascript" src="path/to/instafeed.min.js"></script>
+<script type="text/javascript">
+  var feed = new Instafeed({
+    //...
+  });
+</script>
+```
+
+#### RequireJS
+
+```js
+requirejs(['path/to/instafeed.min.js'], function(Instafeed) {
+  var feed = new Instafeed({
+    //...
+  });
+});
+```
+
+#### CommonJS (`require`)
+
+```js
+const Instafeed = require('instafeed.js');
+
+var feed = new Instafeed({
+  //...
+});
+```
+
+#### ECMAScript Modules (`import`)
+
+```js
+import Instafeed from 'instafeed.js';
+
+var feed = new Instafeed({
+  //...
+});
+```
diff --git a/docs/index.html b/docs/index.html
@@ -0,0 +1,24 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>Instafeed.js - a simple Instagram javascript plugin</title>
+  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
+  <meta name="description" content="Instafeed.js is a simple way to display your Instagram photos on your website.">
+  <meta name="viewport" content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0">
+  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">
+</head>
+<body>
+  <div id="app"></div>
+  <script>
+    window.$docsify = {
+      name: 'Instafeed.js',
+      repo: 'stevenschobert/instafeed.js',
+      coverpage: true,
+      loadSidebar: true,
+      subMaxLevel: 2
+    };
+  </script>
+  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
+</body>
+</html>
diff --git a/docs/managing-access-tokens.md b/docs/managing-access-tokens.md
@@ -0,0 +1,44 @@
+# Managing Access Tokens
+
+The [Instagram Basic Display API](https://developers.facebook.com/docs/instagram-basic-display-api/), which powers version 2.0 of Instafeed.js, uses access tokens that are only valid 60 days.
+
+This means that you will need a server-side component to keep your access token valid in order for Instafeed.js to work correctly.
+
+There are currently 2 available options for keeping access tokens valid:
+
+* [Instagram Token Agent](#instagram-token-agent)
+* [Instant-tokens.com](#instant-tokenscom)
+
+## History
+
+In 2019, Instagram launched the [Instagram Basic Display API](https://developers.facebook.com/blog/post/2019/10/15/launch-instagram-basic-display-api/) and announced they would be sunsetting their Legacy API, which powered the 1.0 version of Instafeed.js, in 2020.
+
+In the Legacy API, access tokens had no expiration time, so Instafeed.js was originally designed to have users hard-code their access tokens (which were read-only) in the browser-side code of their webpages. However, when the Basic Display API was initially launched, access tokens were short-lived, and only valid for 1 hour. This posed a challenge for Instafeed.js, since the library relied on those tokens being hard-coded.
+
+In 2020 however, Instagram [added support for long-lived access tokens](https://developers.facebook.com/blog/post/2020/01/14/instagram-basic-display-api-long-lived-access-tokens-available/), opening up an migration path for Instafeed.js.
+
+These long-lived access tokens did come with a caveat, which is that it would require _some_ amount of server-side code to keep the tokens refreshed past their 60-day lifetime.
+
+## Instant-tokens.com
+
+[Instant-tokens.com](https://www.instant-tokens.com) is a website that generates & refreshes Instagram access tokens. It is provided for free by [Coding Badger](https://codingbadger.com), and is easy to integrate with Instafeed.js.
+
+Pros:
+* Free to use
+* No setup required, just sign in with your Instagram account.
+
+Cons:
+* Closed-source
+* Owned & operated by 3rd party (Coding Badger)
+
+## Instagram Token Agent
+
+[Instagram Token Agent](https://github.com/companionstudio/instagram-token-agent) is an open-source Ruby-on-Rails application written by Ben Hull, and [available on GitHub](https://github.com/companionstudio/instagram-token-agent). It can be quickly deployed to Heroku, or any other Rails-compatible hosting mechanism.
+
+Pros:
+* Open-source
+* Fully controllable by you
+
+Cons:
+* Requires some setup (e.g. creating Facebook API keys, deploying application)
+* Relies on a Sandbox developer account (unless you can get approval from Facebook), which has some limitations.
diff --git a/docs/v2-migration-guide.md b/docs/v2-migration-guide.md
@@ -0,0 +1,54 @@
+# Migrating to Version 2
+
+Quite a few things have changed with the switch to Instagram's new API. The amount of information the new API provides about images and videos is greatly reduced. This is great thing for privacy, but as a result some options in v1 are no longer available in v2.
+
+v2 provides a much simpler service, but should still cater to the most common use-case for Instafeed: embedding your most recent Instagram posts on your website.
+
+## Key Changes:
+
+ - Media is generally only available from the user that the access token belongs to. (You can only display your own posts)
+ - Geographic/location information is not available
+ - Searching by tag is not available
+ - Information on likes and comments is not available
+ - Most sorting options are removed - only sort by name, date is available
+
+## Additional requirements:
+
+ - An access token refresh service is required. See [Managing Access Tokens](Managing-Access-Tokens) for more info.
+
+## Migrating, Step by Step
+
+Assuming you have a simple Instafeed implementation (a single user's most recent images), follow these steps to update to v2.
+
+ 1. [Setup your Facebook app](https://github.com/stevenschobert/instafeed.js/wiki/Facebook-app-and-test-user-setup)
+ 2. [Set up the token agent](https://github.com/stevenschobert/instafeed.js/wiki/Managing-Access-Tokens) and include the script on your web page, before the Instafeed script.
+ 3. Update instafeed.js on your website. Current release is `v2.0.0rc1` _This process varies depending on how you have included the script initially_.
+ 4. Review and update your Instafeed options. See below for which options have been changed or removed.
+
+## Comparison of options between v1 and v2:
+
+These are the v1 options and their status in v2:
+
+| Key  | Status  | Notes  |
+|---|---|---|
+| accessToken | Required, Updated | The accessToken from the Facebook App associated with the user. Needs to be retrieved from a token service. [More info](Managing-Access-Tokens) |
+| after | Optional | Works as v1 |
+| before | Optional | Works as v1 |
+| ~clientId~ | Removed | Basic display API only supports getting the user's own media. |
+| error | Optional | Works as v1 |
+| filter | Optional | Works as v1 |
+| ~get~ | Removed | No longer supported by Basic Display API |
+| limit | Optional, Updated |  Maximum number of media items to add to the page. This limit is applied in the browser. Basic Display API limits are unclear. |
+| ~links~ | Removed | Links are included by default. Use the template option to control this instead. |
+| ~locationId~ | Removed | No longer supported by Basic Display API |
+| mock | Optional | Works as v1 |
+| ~resolution~ | Removed | A single image resolution is returned by the Basic Display API. This is generally high resolution - 1440px wide is typical. |
+| sortBy | Removed | Replaced by the new `sort` option, which uses a function. Sorting is performed in the browser.  |
+| success | Optional | Works as v1 |
+| ~tagName~ | Removed | No longer supported by Basic Display API. Use `filter` instead |
+| target | Optional | Either the ID name or the DOM element itself where you want to add the images to. |
+| template | Optional, Updated | Custom HTML template to render media. See templating. |
+| ~useHttp~ | Removed | All URLs are HTTPS only |
+| ~userId~ | Removed | No longer supported by Basic Display API |
+
+See the full [v2 options reference](Options-Reference)
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Instafeed.js

		Instafeed.js is a simple JavaScript plugin for showing your Instagram photos on your website.