build readme;

Author: RyanNutt

README.md

@@ -1,23 +1,9 @@
 ![](./.github/laravel-breadcrumbs.png)
 
-# Quick and easy breadcrumbs for Laravel
-
-**Note:** This is very much a work in progress and should not be used on any live site. 
-
 [![Latest Version on Packagist](https://img.shields.io/packagist/v/aelora/laravel-breadcrumbs.svg?style=flat-square)](https://packagist.org/packages/aelora/laravel-breadcrumbs)
-[![GitHub Tests Action Status](https://img.shields.io/github/workflow/status/aelora/laravel-breadcrumbs/run-tests?label=tests)](https://github.com/aelora/laravel-breadcrumbs/actions?query=workflow%3Arun-tests+branch%3Amain)
-[![GitHub Code Style Action Status](https://img.shields.io/github/workflow/status/aelora/laravel-breadcrumbs/Check%20&%20fix%20styling?label=code%20style)](https://github.com/aelora/laravel-breadcrumbs/actions?query=workflow%3A"Check+%26+fix+styling"+branch%3Amain)
 [![Total Downloads](https://img.shields.io/packagist/dt/aelora/laravel-breadcrumbs.svg?style=flat-square)](https://packagist.org/packages/aelora/laravel-breadcrumbs)
 
-This is where your description should go. Limit it to a paragraph or two. Consider adding a small example.
-
-## Support us
-
-[<img src="https://github-ads.s3.eu-central-1.amazonaws.com/laravel-breadcrumbs.jpg?t=1" width="419px" />](https://spatie.be/github-ad-click/laravel-breadcrumbs)
-
-We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us).
-
-We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards).
+Quickly build breadcrumb trails for your pages in Laravel and automatically output the HTML and JSON-LD schema metadata. 
 
 ## Installation
 
@@ -30,35 +16,107 @@ composer require aelora/laravel-breadcrumbs
 You can publish the config file with:
 
 ```bash
-php artisan vendor:publish --tag="laravel-breadcrumbs-config"
+php artisan vendor:publish --tag="breadcrumbs-config"
 ```
 
 This is the contents of the published config file:
 
 ```php
 return [
+    'home' => [
+
+        // Should the home link be automatically included in the breadcrumbs? You can also manually include
+        // or exclude the home link when you build the breadcrumb class.
+        'include' => true,
+
+        'text' => 'Home',
+
+        'url' => url('/'),
+
+        'image' => '',
+    ],
+
+    // Which blade template to use. Currently only tailwind is supported. 
+    'theme' => 'tailwind',
+
+    // View to use to generate the HTML breadcrumbs. If defined, this will
+    // override the theme above.
+    'view' => '',
+
+    // Character to use as a separator between crumbs. Use and encoded entity
+    // if you want something like > 
+    'separator' => '/',
 ];
 ```
 
 Optionally, you can publish the views using
 
 ```bash
-php artisan vendor:publish --tag="laravel-breadcrumbs-views"
+php artisan vendor:publish --tag="breadcrumbs-views"
 ```
 
+Currently the only two views are `jsonld.blade.php` which is used for the Schema metadata and `breadcrumbs-tailwind.blade.css`.
+
 ## Usage
 
 ```php
-$breadcrumbs = new Aelora\Breadcrumbs();
-echo $breadcrumbs->echoPhrase('Hello, Aelora!');
+// In your controller
+use Aelora\Breadcrumbs\Breadcrumbs;
+$breadcrumbs = Breadcrumbs::create()
+    ->add('Page #1', url('/page-1'))
+    ->add('Page #2', url('/page-2'))
+    ->add('Current Page');
+
+return view('some.view.file', ['breadcrumbs' => $breadcrumbs]);
 ```
 
-## Testing
-
-```bash
-composer test
+```php
+// In your view where ever your want the breadcrumbs
+{!! $breadcrumbs !!}
 ```
 
+You can also call `$breadcrumbs->generate()` for the same effect. `Breadcrumbs` implements `Stringable` and has a `__toString()` method, so you don't need to. The `__toString()` calls `generate()`. 
+
+Note that we're using `{!!` and `!!}` instead of `{{` and `}}`. We don't want the contents of the breadcrumbs to be escaped. 
+
+### Home Page
+
+You don't need to explicitly add your home page to the breadcrumbs. With the default config, it will be added automatically as the first element before output. If you don't want to include the home page link you can set `home.include` to `false` in the config file or call `setHome(false)` when you're creating the breadcrumbs. 
+
+## Methods
+
+`public function add(string $title, string $url = '', string $image = '')`
+
+Adds a new breadcrumb link on the end of the current stack. 
+
+The only required parameter is `$title`. Breadcrumbs will only be links if `$url` is not empty. If it is, `$title` will display unlinked. `$image` is a link to an image for the breadcrumb. It's currently only used in the schema metadata and not in the visible HTML output, although it could be if you build your own view. 
+
+`public function count()`
+
+Returns the number of breadcrumb items, not counting the home link.
+
+`public static function create()`
+
+Returns a new instance so you can build on one line without having to call `new Breadcrumbs()`.
+
+`public function generate($echo = false)`
+
+Returns the generated breadcrumbs, both the visible HTML and schema metadata. If `$echo` is `true` then the breadcrumbs will also be echoed prior to return. 
+
+`public function reset()`
+
+Clears the breadcrumb trail. 
+
+`public function reverse()`
+
+Reverses the internal breadcrumb trail. Sometimes it's easier to build the trail backwards and then flip it at the end. 
+
+`public function setHome($title, string $url = '', string $image = '')`
+
+Allows you to change the home link for individual pages without having to change the config file. Parameters are the same as the `add` method. 
+
+If `$title` is `false` then the home link will not be included. Otherwise it should be a `string`. 
+
 ## Changelog
 
 Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.
@@ -67,10 +125,6 @@ Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed re
 
 Please see [CONTRIBUTING](https://github.com/RyanNutt/.github/blob/main/CONTRIBUTING.md) for details.
 
-## Security Vulnerabilities
-
-Please review [our security policy](../../security/policy) on how to report security vulnerabilities.
-
 ## Credits
 
 - [Ryan Nutt](https://github.com/RyanNutt)

composer.json

@@ -6,7 +6,7 @@
         "laravel",
         "laravel-breadcrumbs"
     ],
-    "homepage": "https://github.com/aelora/laravel-breadcrumbs",
+    "homepage": "https://github.com/RyanNutt/laravel-breadcrumbs",
     "license": "MIT",
     "authors": [
         {

src/Breadcrumbs.php

@@ -115,6 +115,8 @@ public function generate(bool $echo = false): string
 
         $out .= view('breadcrumbs::jsonld', ['jsonld' => $jsonld, 'crumbs' => $this->crumbs])->render();
 
+        if ($echo) echo $out;
+
         return $out;
     }