Improved documentation

CHANGELOG.md

@@ -1,70 +1,76 @@
+# v1.0.14
+## 15-10-2022
+
+1. [](#bugfix)
+    * Correct changelog format
+
 # v1.0.13
-## 15/10/2022
+## 15-10-2022
 
 1. [](#improved)
     * Animate banner show/hide
 
 # v1.0.12
-## 14/10/2022
+## 14-10-2022
 
 1. [](#improved)
     * CDN fix now defaults to non-visible banner revealed by JS
 2. [](#new)
     * Added ability to whitelist pages for showing banner
 
 # v1.0.11
-## 10/10/2022
+## 10-10-2022
 
 1. [](#improved)
     * Align banner content left by default
 
 # v1.0.10
-## 10/10/2022
+## 10-10-2022
 
 1. [](#improved)
     * Improved flex layout
 
 # v1.0.9
-## 10/10/2022
+## 10-10-2022
 
 1. [](#improved)
     * Changed container from <p> to <div> to allow non-inline elements
     * Added overflow-wrap: anywhere to improve responsive behaviour 
 
 # v1.0.8
-## 10/26/2021
+## 26-10-2021
 
 1. [](#improved)
     * Changed CDN Fix behaviour to use client side JS to hide banner
     * Added strict SameSite attribute to dismissal choice cookie 
 
 # v1.0.7
-## 10/19/2021
+## 19-10-2021
 
 1. [](#improved)
     * Added option that fixes behaviour when site is served behind CDN
 
 # v1.0.6
-## 07/24/2021
+## 24-07-2021
 
 1. [](#improved)
     * Improved formatting of banner action buttons on mobile devices
 
 # v1.0.5
-## 06/03/2021
+## 03-06-2021
 
-1. [](#fixed)
+1. [](#bugfix)
     * Fixed install via admin plugin by shipping vendor folder
 
 # v1.0.4
-## 04/29/2021
+## 29-04-2021
 
 1. [](#improved)
     * Processing stops if dismiss cookie is set
     * Dismiss cookie is unset on plugin config change
 
 # v1.0.3
-## 04/28/2021
+## 28-04-2021
 
 1. [](#new)
     * Added option to choose banner location (top or bottom)
@@ -73,19 +79,19 @@
     * Improved config page with sections
 
 # v1.0.2
-## 04/28/2021
+## 28-04-2021
 
 1. [](#new)
     * Added optional dismiss button to dismiss banner for 30 mins
 
 # v1.0.1
-## 04/28/2021
+## 28-04-2021
 
 1. [](#improved)
     * Unset config values are now merged with defaults to catch unset value errors
 
 # v1.0.0
-##  04/27/2021
+##  27-04-2021
 
 1. [](#new)
     * ChangeLog started...

README.md

@@ -6,40 +6,38 @@ The **Custom Banner** Plugin is an extension for [Grav CMS](http://github.com/ge
 
 ## Installation
 
-Installing the Custom Banner plugin can be done in one of three ways: The GPM (Grav Package Manager) installation method lets you quickly install the plugin with a simple terminal command, the manual method lets you do so via a zip file, and the admin method lets you do so via the Admin Plugin.
+To install the Custom Banner plugin you need to put its files in the `grav/user/plugins/custom-banner/` directory.
 
-### GPM Installation (Preferred)
+The easiest way to do this is to install the plugin through the Admin plugin which does it all for you, but you can also use the command line Grav Package Manager, or even just do it manually.
 
-To install the plugin via the [GPM](http://learn.getgrav.org/advanced/grav-gpm), through your system's terminal (also called the command line), navigate to the root of your Grav-installation, and enter:
+### Admin Plugin (Recommended)
 
-    bin/gpm install custom-banner
-
-This will install the Custom Banner plugin into your `/user/plugins`-directory within Grav. Its files can be found under `/your/site/grav/user/plugins/custom-banner`.
+If you use the Admin Plugin, you can install the plugin directly by browsing the `Plugins`-menu and clicking on the `Add` button, then searching through the available plugins.
 
-### Manual Installation
+### GPM Installation
 
-To install the plugin manually, download the zip-version of this repository and unzip it under `/your/site/grav/user/plugins`. Then rename the folder to `custom-banner`. You can find these files on [GitHub](https://github.com/aricooperdavis/grav-plugin-custom-banner) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
+To install the plugin via the [GPM](http://learn.getgrav.org/advanced/grav-gpm), through your system's command line, navigate to the root of your Grav-installation, and enter:
 
-You should now have all the plugin files under
+    bin/gpm install custom-banner
 
-    /your/site/grav/user/plugins/custom-banner
+On some systems you may need to prepend this command with `php `.
 
-> NOTE: This plugin is a modular component for Grav which may require other plugins to operate, please see its [blueprints.yaml-file on GitHub](https://github.com/aricooperdavis/grav-plugin-custom-banner/blob/master/blueprints.yaml).
+### Manual Installation
 
-### Admin Plugin
+To install the plugin manually, download the zip-version of this repository and unzip it under `grav/user/plugins`. Then rename the folder to `custom-banner`.
 
-If you use the Admin Plugin, you can install the plugin directly by browsing the `Plugins`-menu and clicking on the `Add` button.
+You can find these files on [GitHub](https://github.com/aricooperdavis/grav-plugin-custom-banner) or via [GetGrav.org](http://getgrav.org/downloads/plugins#extras).
 
-## Configuration
+## Usage
 
-### Note for Cloudflare/CDN Users
-Users of Cloudflare or other cacheing CDNs must enable the "Cloudflare/CDN Fix" option in the plugin configuration. This forces the server to add the banner to all (non-excluded) pages, but hides it immediately on pageload if the dismissal cookie is set. This may result in the banner flickering on page-load in certain race conditions.
+Once configured and activated this plugin displays a banner on your site, and needs no other intervention.
 
-### Manual Configuration
+### Configuration file
+Configure the plugin to customise the appearance and behaviour of the banner. It's easiest to configure it through the Admin Plugin, by navigating to `admin/plugins/custom-banner`. This updates the configuration file through an easy to use graphical user interface.
 
-Before configuring this plugin, you should copy the `user/plugins/custom-banner/custom-banner.yaml` to `user/config/plugins/custom-banner.yaml` and only edit that copy.
+Alternatively you may configure it manually by copying the `grav/user/plugins/custom-banner/custom-banner.yaml` to `grav/user/config/plugins/custom-banner.yaml` and making your changes in that configuration file.
 
-Here is the default configuration and an explanation of available options:
+The default configuration file is as follows:
 
 ```yaml
 enabled: true
@@ -53,27 +51,42 @@ cdn-fix: false
 bg-colour: '#EC565C'
 fg-colour: 'rgba(255, 255, 255, 0.80)'
 box-shadow: true
-show-on-pages: # - /route-to-page/you-want-to/include
+show-on-pages:
 hide-on-pages:
   - /route-to-page/you-want-to/exclude
 ```
 
-You can also overwrite the style defined in `custom-banner/css/custom-banner.css` with your own css rules.
-
-### Admin Plugin
-
-It's much easier to configure the plugin using the Admin Plugin through the plugin settings page. If you use the Admin Plugin, a file with your configuration named custom-banner.yaml will be saved in the `user/config/plugins/`-folder once the configuration is saved in the Admin.
-
-## Usage
-
-To add a banner to your site simply enable the plugin and change the content and colours as required.
+### Options
+The configuration options can broadly be separated into those that change the plugins appearance, and those that change its behaviour. See the above default configuration for examples of valid configuration values.
+
+#### Appearance
+| Option | Type | Description |
+| -- | -- | -- |
+| `content` | string | The content of the banner. It must be [valid HTML](https://developer.mozilla.org/en-US/docs/Web/Guide/HTML/Content_categories#flow_content) as it is injected directly into a `<div>` within the banner. Generally, the smaller and simpler this is the better it will appear (without manual CSS customisation). |
+| `position` | string | Whether the banner appears at the `bottom` or `top` of the screen. |
+| `button-text` | string | The text of the action button. It is injected into an `<a>` within the banner so make sure it meets the [permitted content requirements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#properties). |
+| `dismiss-text` | string | The text of the dismiss button. It is injected into an `<a>` within the banner so make sure it meets the [permitted content requirements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#properties). |
+| `bg-colour` | string | The colour of the banner background. Should be a valid [HTML colour representation](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). |
+| `fg-colour` | string | The colour of the banner content. Should be a valid [HTML colour representation](https://developer.mozilla.org/en-US/docs/Web/CSS/color_value). |
+| `box-shadow` | boolean | Whether or not the banner should cast a shadow on the page below it. |
+
+#### Behaviour
+| Option | Type | Description |
+| -- | -- | -- |
+| `button-url` | string | The URL that the action button links to. |
+| `show-on-pages` | array of strings | List of routes of pages on which the banner should be exclusively shown (i.e. a whitelist). Leave empty to show the banner on all pages. |
+| `hide-on-pages` | array of strings | List of routes of pages on which the banner should be hidden (i.e. a blacklist). Takes priority over the `show-on-pages` value for any given page route. |
+| `dismiss-button` | boolean | Whether a dismiss button is shown or not. |
+| `cdn-fix` | boolean | Enable if a CDN is used for cacheing in-front of the site. This uses client-side javascript for the display logic rather than the default behaviour of server-side logic. |
 
 ## Credits
 
-I pretty much copied the style and format of the premium banner from the [Grav Site](https://getgrav.org/) and just wrapped it up in a plugin for ease of use - so thanks to the Grav Team for doing most of the legwork.
+The initial concept was inspired by the premium banner from the [Grav Site](https://getgrav.org/), but the designed has since evolved to improve responsiveness and customisation.
+
+Thanks to all [contributors](https://github.com/aricooperdavis/grav-plugin-custom-banner/graphs/contributors), and those who have [reported bugs](https://github.com/aricooperdavis/grav-plugin-custom-banner/issues?q=is%3Aissue+label%3Abug) and [proposed improvements](https://github.com/aricooperdavis/grav-plugin-custom-banner/issues?q=is%3Aissue+label%3Aenhancement).
 
-## To Do
+## Contributing
 
-- [x] Add a button to make the banner hide-able (for the session? by setting a cookie?)
-- [ ] Add more position options, such as left and right
-- [ ] Translations (help needed)
+- If you use the plugin and have found a bug or would like to see a new feature please [open an issue](https://github.com/aricooperdavis/grav-plugin-custom-banner/issues/new/).
+- If you speak multiple languages and could help with translations then please [fork this repository](https://github.com/aricooperdavis/grav-plugin-custom-banner/fork), [add your translations](https://learn.getgrav.org/16/content/multi-language#plugin-and-theme-language-translations) to the `languages.yaml` file, and open a pull request.
+- If you are a developer and would like to contribute then please fork, commit, and pull-request as normal - if you don't have any ideas then [the open issues](https://github.com/aricooperdavis/grav-plugin-custom-banner/issues) is a good place to start!

blueprints.yaml

@@ -1,7 +1,7 @@
 name: Custom Banner
 slug: custom-banner
 type: plugin
-version: 1.0.13
+version: 1.0.14
 description: Add a custom banner to your Grav site
 icon: bookmark
 author: