Update readme formatting and add preview image.

cwsdigital · Sep 21, 2021 · 54c55e4 · 54c55e4
1 parent 209c387
commit 54c55e4
Showing 1 changed file with 50 additions and 44 deletions.
diff --git a/README.md b/README.md
@@ -1,8 +1,10 @@
-## Twill Metadata
+# Twill Metadata
 
-This package is a simple way to add editable SEO metadata to your twill models.  
+This package is a simple way to add SEO metadata to your [Twill](https://twill.io/) models by providing a drop-in fieldset to add all the required fields into your model edit form.  With sensible defaults, configurable fallbacks, and a global settings screen; this package should meet most of the needs for optimising meta tags within a site.
 
-#### Installation
+![default and expanded views of twill metadata fieldset](https://github.com/cwsdigital/twill-metadata/blob/master/Twill-Metadata-Preview.jpg)
+
+## Installation
 ```shell script
 $ composer require cwsdigital/twill-metadata
 ```
@@ -11,7 +13,9 @@ $ composer require cwsdigital/twill-metadata
 $ artisan migrate
 ```
 
-### In your model
+## Configuration
+
+### In the model
 
 Set your model to use the `HasMetadata` trait, and add the public property `$metadataFallbacks`. 
 Your model also need to use the HasMedias trait in order to allow for OpenGraph images.
@@ -27,7 +31,7 @@ class Page extends Model {
 }
 
 ```
-### In your controller
+### In the controller
 
 In the Twill admin controller for the model, ensure the `metadata_card_type_options` and `metadata_og_type_options` are set in the `formData()` method.
 ```php
@@ -41,10 +45,10 @@ protected function formData($request)
     }
 ```
 
-### In your repository
+### In the repository
 Add `use HandleMetadata` onto your page repository.
 ```php
-//App/Repositories/PageRepository.php
+// App/Repositories/PageRepository.php
 class PageRepository extends ModuleRepository
 {
     use HandleBlocks, HandleSlugs, HandleMedias, HandleFiles, HandleRevisions, HandleMetadata;
@@ -56,8 +60,8 @@ class PageRepository extends ModuleRepository
 }
 ```
 
-### In your view
-
+### In the view
+#### Add the fieldset to your form
 In the admin 'form.blade.php' view add the metadata fieldset to the additional fieldsets of the form.
 ```blade
 {{-- resources/views/admin/pages/form.blade.php --}}
@@ -76,7 +80,7 @@ In the admin 'form.blade.php' view add the metadata fieldset to the additional f
 @stop
 ```
 
-### Add the global settings form
+#### Add the global settings form
 In your twill-navigation config file add a settings section for the form fields.
 ```php
 // config/twill-navigation.php
@@ -103,15 +107,48 @@ return [
 ```
 
 ```blade
-<!-- views/admin/settings/seo.blade.php -->
+{{-- views/admin/settings/seo.blade.php --}}
 @extends('twill::layouts.settings')
 
 @section('contentFields')
     @metadataSettings
 @stop
 ```
 
-### Config & Customisation
+
+## Setting meta tags
+In your controller for your front end application you can add the trait `SetsMetadata` and then use the `setMetadata()` function to set the metadata.  
+
+```php
+<?php
+// App/Http/Controllers/PageController.php
+class PageController extends Controller
+{
+    use setsMetadata;
+
+    public function show($slug) {
+        $page = Page::forSlug($slug)->first();
+        $this->setMetadata($page);
+        return view('site.pages.page', ['page' => $page ]);
+    }
+}
+```
+
+Under the hood this uses the [artesaos/seotools](https://github.com/artesaos/seotools) package to set and display metadata. So you are free to not use the above helper, and manually set the meta tags as required. Or you can use the helper, and then use the methods provided by the package to amend the tags.
+
+## Outputting meta tags
+See the documentation for [artesaos/seotools](https://github.com/artesaos/seotools) for more granular options, but the easiest way is shown below:
+```blade
+{{-- resources/views/layouts/site.blade.php --}}
+<html lang="en">
+<head>
+
+    {!! SEO::generate() !!}
+
+</head>
+```
+
+## Customization
 
 You can publish the config for the package with the following command:
 ```shell script
@@ -132,6 +169,7 @@ Within the config file is a fallbacks array, which can be customised according t
 
 To provide different fallback configurations to different models with the HasMetadata trait you can use the same array in the public $metadataFallBacks property on the model.
 ```php
+// App/Models/Page.php
 class Page extends Model {
 
     use HasMetadata;
@@ -152,35 +190,3 @@ If you wish to provide a default OpenGraph Type and Twitter Card Type then you c
     public $metadataDefaultCardType = 'summary_large_image';
 ```
 
-### Setting Meta Tags
-In your controller for your front end application you can add the trait `SetsMetadata` and then use the `setMetadata()` function to set the metadata.  
-
-```php
-<?php
-//App/Http/Controllers/PageController.php
-class PageController extends Controller
-{
-    use setsMetadata;
-
-    public function show($slug) {
-        $page = Page::forSlug($slug)->first();
-        $this->setMetadata($page);
-        return view('site.pages.page', ['page' => $page ]);
-    }
-}
-```
-
-Under the hood this uses the [artesaos/seotools](https://github.com/artesaos/seotools) package to set and display metadata. So you are free to not use the above helper, and manually set the meta tags as required. Or you can use the helper, and then use the methods provided by the package to amend the tags.
-
-### Outputting the meta tags
-See the documentation for [artesaos/seotools](https://github.com/artesaos/seotools) for more granular options, but the easiest way is shown below:
-```blade
-{{-- resources/views/layouts/site.blade.php --}}
-<html lang="en">
-<head>
-
-    {!! SEO::generate() !!}
-
-</head>
-```
-