First formal version. README and CHANGELOG.

- Version updated to 1.0.0, as we're at a good and stable base.
- Completed README and CHANGELOG with useful informations and docs.

.gitignore

@@ -4,4 +4,4 @@
 *.css.map
 
 
-# vendors directory commited because Grav don't install composer dependencies
+# vendors directory committed because Grav don't install composer dependencies

CHANGELOG.md

@@ -1,5 +1,8 @@
-# v0.1.0
-##  06/30/2018
+# v1.0.0
+##  07/07/2018
 
 1. [](#new)
-    * ChangeLog started...
+    * First version
+    * Support for Twitter, Mastodon and Instagram, with light or dark embeds, using simple shortcodes.
+    * Support for texts, images, videos, GIF, multiple medias, Mastodon's CW.
+    * Images and videos can be downloaded locally for enhanced independence.

README.md

@@ -22,7 +22,7 @@ You should now have all the plugin files under
 
     /your/site/grav/user/plugins/static-social-embeds
 
-> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav) and the [Error](https://github.com/getgrav/grav-plugin-error) and [Problems](https://github.com/getgrav/grav-plugin-problems) to operate.
+> NOTE: This plugin is a modular component for Grav which requires [Grav](http://github.com/getgrav/grav), the [Error](https://github.com/getgrav/grav-plugin-error), [Problems](https://github.com/getgrav/grav-plugin-problems) and [Shortcode Core](https://github.com/getgrav/grav-plugin-shortcode-core) plugins to operate. Also, the [CURL PHP extension](https://secure.php.net/curl) must be enabled for this plugin to work.
 
 ### Admin Plugin
 
@@ -32,18 +32,101 @@ If you use the admin plugin, you can install directly through the admin plugin b
 
 Before configuring this plugin, you should copy the `user/plugins/static-social-embeds/static-social-embeds.yaml` to `user/config/plugins/static-social-embeds.yaml` and only edit that copy.
 
-Here is the default configuration and an explanation of available options:
+Here is the default configuration and a short explanation of available options. Extensive explanations are available in the admin page of the plugin.
 
 ```yaml
 enabled: true
+
+# The plugin ships its own JS and CSS to run the static embeds.
+# If you want to provide your own, feel free to disable them.
+built_in_css: true
+built_in_js: true
+
+# The plugin can download images, videos, and GIFs, to ensure a
+# complete independence from the social networks, at the cost of
+# some disk space.
+downloaded_content:
+  images: true
+  videos: true
+
+# Options for Twitter: embed theme (with the default CSS, matches the
+# light & dark Twitter themes) and API credentials required to load
+# tweets (an explanation on how to create an application is available
+# below).
+twitter:
+  theme: light
+  consumer_key: null
+  consumer_secret: null
+  access_token: null
+  access_token_secret: null
+
+# Options for Mastodon: embed theme (with the default CSS, matches the
+# light & dark Mastodon themes).
+mastodon:
+  theme: light
+
+# Options for Instagram: embed theme (with the default CSS, the light theme
+# matches Instagram, and the dark one was created from the light one and
+# some inspiration from Twitter own dark theme).
+instagram:
+  theme: light
 ```
 
+Themes can be `light` or `dark` as for now and for the built-in CSS. If you want to add your own, themes only add a CSS class to the embeds containers: `sse-theme-[thetheme]` (e.g. `sse-theme-light` or `sse-theme-dark`); you can put anything there and reference it on your CSS file.
+
+### Twitter setup
+
+To use Twitter embeds, you'll need to register an application. This is done in a few simple steps.
+
+1. Go to [the Twitter Apps page](https://apps.twitter.com/app/new) to create an application. You don't need to provide a callback URL (we never use that).
+2. Then, click the **Keys and access tokens** tab and at the bottom of the page, click **Create my Access Token**.
+3. Finally, copy the credentials in the configuration file (or in the admin).
+
 Note that if you use the admin plugin, a file with your configuration, and named static-social-embeds.yaml will be saved in the `user/config/plugins/` folder once the configuration is saved in the admin.
 
+### Customization
+
+If you want to customize the embeds' HTML code, you can override the `partials/static-social-embeds` templates. The template name is the same as the shortcode name (see below), e.g. `toot.html.twig` for Mastodon embeds template. Templates context vary for different social networks; checkout built-in templates or shortcode classes to know which variables you can use.
+
 ## Usage
 
-**Describe how to use the plugin.**
+The plugin supports static embeds for Twitter, Mastodon and Instagram posts. It tries to match original embeds styles, so it's close to the real embeds, wut without any request to the social networks: independence!
+
+Three shortcodes are declared to embed status: `tweet`, `toot` and `instagram`, for respectively Twitter, Mastodon and Instagram. They accept one parameter: the status URL to embed. Use them in your articles like this:
+
+```markdown
+[tweet="https://twitter.com/INSVideos/status/1013375197984980992"]
+
+[toot="https://mamot.fr/@ploum/100244825435451499"]
+
+[instagram="https://www.instagram.com/p/BkiaGXxgmOH/"]
+``` 
+
+The following shortcodes will be rendered as below (for light and dark themes, with built-in CSS & JS).
+
+![](assets/docs/embeds-preview.png)
+
+Texts, images (single or multiples), videos (single or multiples), GIFs, are supported for all networks above. Mastodon toots supports CW and sensitive images.
+
+Extensive caching is used to retrieve data and medias only once per embed. The first page load may be slow (especially if there are a lot of embeds in the page), but subsequent calls will be lightning-fast, as all data will be read from the cache, without any request to the social networks (no tracking, yay!). This also means that if an embed status is deleted, it will be kept on your site if the cache is not deleted. Custom locations are used for the cache files.
+
+- Raw data is stored in `<root>/cache/static-social-embeds`. You can delete this folder at any time: embeds data will be retrieved from the social networks if not found in the cache.
+- Images and videos are stored in `<root>/images/static-social-embeds`. You _should not_ delete this folder without deleting the above cache folder: if images are downloaded, links to images and videos references this medias cache folder. If you delete it, all images from existing embeds will be broken, except if you remove the data cache folder, as it will trigger a re-download of the medias (or references of CDN URLs if you disable the medias download).
+
+The plugin is translated in English and French.
+
+## Technical considerations regarding Instagram
+
+While Twitter and Mastodon data are retrieved using their respective API, there is no way to do that with Instagram (or there is, but deprecated and soon-to-be-removed in december 2018). We scrap an internal JSON embed in the post pages to retrieve data (thanks to [RSSBridge](https://github.com/RSS-Bridge/rss-bridge/blob/master/bridges/InstagramBridge.php) for the tip). As it isn't official, it may break anytime.
+
+Data is cached without expiration, so as long as you don't delete the cache, existing embeds will never break. New ones will. Feel free to open an issue if such problem occurs (but this is pretty stable for a few years now and I hope it will remains as such).
+
+## Thanks
+
+- Thanks to [`jedkirby/tweet-entity-linker`](https://github.com/jedkirby/tweet-entity-linker) used to parse tweets and add entities links (hashtags, mentions…) referenced in Twitter's JSON statuses.
 
 ## To Do
 
-- [ ] Future plans, if any
+- [ ] Support for Twitter pools.
+- [ ] Support for Pleroma (should be simple as it's compatible with the Mastodon API) and maybe other networks (by request).
+- [ ] Maybe option to proxy medias, allowing not to store them but still serve them from the website's domain.

blueprints.yaml

@@ -1,5 +1,5 @@
 name: Static Social Embeds
-version: 0.1.0
+version: 1.0.0
 description: |
   Embeds social status (like tweets, instagram posts, toots, etc.) in articles without using their embed iframe,
   but rather statically without any dependency to the service.
@@ -10,7 +10,7 @@ author:
 homepage: https://github.com/Nebulius/grav-plugin-static-social-embeds
 keywords: grav, plugin, embed, static, twitter, instagram, mastodon, tweet, toot, integration, post
 bugs: https://github.com/Nebulius/grav-plugin-static-social-embeds/issues
-docs: https://github.com/Nebulius/grav-plugin-static-social-embeds/blob/develop/README.md
+docs: https://github.com/Nebulius/grav-plugin-static-social-embeds/blob/master/README.md
 license: MIT
 
 dependencies:

static-social-embeds.yaml

@@ -1,21 +1,35 @@
 enabled: true
 
+# The plugin ships its own JS and CSS to run the static embeds.
+# If you want to provide your own, feel free to disable them.
 built_in_css: true
 built_in_js: true
 
+# The plugin can download images, videos, and GIFs, to ensure a
+# complete independence from the social networks, at the cost of
+# some disk space.
 downloaded_content:
   images: true
   videos: true
 
+# Options for Twitter: embed theme (with the default CSS, matches the
+# light & dark Twitter themes) and API credentials required to load
+# tweets (an explanation on how to create an application is available
+# below).
 twitter:
   theme: light
   consumer_key: null
   consumer_secret: null
   access_token: null
   access_token_secret: null
 
+# Options for Mastodon: embed theme (with the default CSS, matches the
+# light & dark Mastodon themes).
 mastodon:
   theme: light
 
+# Options for Instagram: embed theme (with the default CSS, the light theme
+# matches Instagram, and the dark one was created from the light one and
+# some inspiration from Twitter own dark theme).
 instagram:
   theme: light