From b9f1ceeaf435d3b99a678cec0f11b45c33f1c4c2 Mon Sep 17 00:00:00 2001
From: Steve Desmond <steve@vtsv.ca>
Date: Tue, 26 Oct 2021 13:01:47 -0400
Subject: [PATCH] Add additional info to README

---
 README.md | 116 +++++++++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 102 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index c18a382..a2aad4e 100644
--- a/README.md
+++ b/README.md
@@ -1,8 +1,11 @@
 # SrcSet
 
-A CLI to create sets of responsive images for the web
+Tools to create sets of responsive images for the web
+
+[![SrcSet](https://img.shields.io/nuget/v/SrcSet?logo=nuget&label=SrcSet)](https://www.nuget.org/packages/SrcSet/)
+[![SrcSet.Statiq](https://img.shields.io/nuget/v/SrcSet.Statiq?logo=nuget&label=SrcSet.Statiq)](https://www.nuget.org/packages/SrcSet.Statiq/)
+[![SrcSet.Core](https://img.shields.io/nuget/v/SrcSet.Core?logo=nuget&label=SrcSet.Core)](https://www.nuget.org/packages/SrcSet.Core/)
 
-[![NuGet version](https://img.shields.io/nuget/v/SrcSet?logo=nuget&label=Install)](https://www.nuget.org/packages/srcset/)
 [![Build Status](https://github.com/ecoAPM/SrcSet/workflows/CI/badge.svg)](https://github.com/ecoAPM/SrcSet/actions)
 [![Coverage](https://sonarcloud.io/api/project_badges/measure?project=ecoAPM_SrcSet&metric=coverage)](https://sonarcloud.io/dashboard?id=ecoAPM_SrcSet)
 
@@ -10,28 +13,115 @@ A CLI to create sets of responsive images for the web
 [![Reliability](https://sonarcloud.io/api/project_badges/measure?project=ecoAPM_SrcSet&metric=reliability_rating)](https://sonarcloud.io/dashboard?id=ecoAPM_SrcSet)
 [![Security](https://sonarcloud.io/api/project_badges/measure?project=ecoAPM_SrcSet&metric=security_rating)](https://sonarcloud.io/dashboard?id=ecoAPM_SrcSet)
 
-## Requirements
+## Tools
+
+This repository contains 3 projects:
+- [SrcSet](#cli): a CLI utility to create sets of responsive images
+- [SrcSet.Statiq](#statiq): pipeline and helper for integrating responsive images into a Statiq site
+- [SrcSet.Core](#library): a library used by the above, also available for public consumption
+
+## CLI
+
+### Requirements
 
 - .NET SDK 5.0
 
-## Installation
+### Installation
 
-    dotnet tool install -g SrcSet
+```bash
+dotnet tool install -g SrcSet
+```
 
-## Usage
+### Usage
 
-    srcset {file or directory} [-r] [space delimited set of widths]
+```bash
+srcset {file or directory} [-r] [space delimited set of widths]
+```
 
 e.g.
 
-    srcset IMG_9687.jpg 500 1000
+```bash
+srcset IMG_9687.jpg 500 1000
+```
 
 will resize the image to 500 and 1000 pixels wide, with the filenames `IMG_9687-0500.jpg` and `IMG_9687-1000.jpg`
 
-    srcset all_images/
+```bash
+srcset all_images/
+```
 
 will resize all images in the `all_images` directory (recursively if `-r` is included) to each of the default widths
 
+## Statiq
+
+This package contains a Statiq pipeline and HTML helper method to easily integrate responsive image generation into a Statiq site.
+
+The process to accomplish this has two steps:
+1. create the set of responsive images to use (using the pipeline)
+2. reference the images in the generated HTML (using the HTML helper)
+
+### Step 1
+
+To create a set of responsive images, place the originals (to be resized) alongside your other assets, and then in your bootstrapper code, add:
+
+```c#
+bootstrapper.AddPipeline("SrcSet", new ResponsiveImages("**/*.jpg"));
+```
+
+where the optional parameter `**/*.jpg` is a glob pointing to the image assets to resize.
+
+A custom set of widths can also be passed as a second parameter:
+
+```c#
+bootstrapper.AddPipeline("SrcSet", new ResponsiveImages("**/*.jpg", new ushort[] { 100, 200, 300 }));
+```
+
+### Step 2
+
+In your Razor file, call the HTML helper to create an `<img/>` tag with the relevant attributes set:
+
+```c#
+@Html.Raw(ResponsiveImages.SrcSet("images/original.jpg"))
+```
+
+You can also customize the widths, default width, and add any other attributes here:
+
+```c#
+@Html.Raw(ResponsiveImages.SrcSet("images/original.jpg", new ushort[] { 100, 200, 300 }, 200))
+```
+
+```c#
+@Html.Raw(ResponsiveImages.SrcSet("images/original.jpg", attributes: new Dictionary<string, string>
+	{
+		{ "class", "full-width" },
+		{ "alt", "don't forget about accessibility!" }
+	}
+))
+```
+
+## Library
+
+The "Core" library can be used to incorporate SrcSet's functionality into your own app.
+
+First, create a new `SrcSetManager`:
+
+```c#
+var manager = new SrcSetManager();
+```
+
+Then invoke it's `SaveSrcSet()` method:
+
+```c#
+await manager.SaveSrcSet("file.png", SrcSetManager.DefaultSizes);
+```
+
+If you need more control than the default constructor and sizes provide, you can pass in a specific logging mechanism (other than the default `Console.WriteLine`) and list of widths:
+
+```c#
+var manager = new SrcSetManager(Image.LoadAsync, (string s) => logger.LogDebug(s));
+await manager.SaveSrcSet("file.png", new ushort[] { 100, 200, 300 });
+```
+
 ### Default widths
 
 - 240px
@@ -49,13 +139,11 @@ will resize all images in the `all_images` directory (recursively if `-r` is inc
 
 `SrcSet` uses [ImageSharp](https://imagesharp.net) under the hood, and therefore should theoretically support all file types that ImageSharp supports by entering the filename as a parameter, however when entering a directory as a parameter, file types are limited to:
 
-- jpg/jpeg
+- jpg / jpeg / jfif
 - png
-- bmp
+- bmp / bm / dip
 - gif
-- tif/tiff
-
-Feel free to contribute an update that adds more file types to `Arguments.ValidExtensions`!
+- tga / vda / icb / vst
 
 ## Contributing