Updates docs

skttl · Mar 13, 2024 · 6774159 · 6774159
1 parent 0b158b1
commit 6774159
Show file tree

Hide file tree

Showing 11 changed files with 168 additions and 94 deletions.
diff --git a/README.md b/README.md
@@ -1,95 +1,31 @@
 # ImageSharpCommunity.Providers.Remote
 
+[![Downloads](https://img.shields.io/nuget/dt/ImageSharpCommunity.Providers.Remote?color=cc9900)](https://www.nuget.org/packages/ImageSharpCommunity.Providers.Remote/)
+[![NuGet](https://img.shields.io/nuget/vpre/ImageSharpCommunity.Providers.Remote?color=0273B3)](https://www.nuget.org/packages/ImageSharpCommunity.Providers.Remote)
+[![GitHub license](https://img.shields.io/github/license/skttl/ImageSharp.Community.Providers.Remote?color=8AB803)](https://github.com/skttl/ImageSharp.Community.Providers.Remote/blob/main/LICENSE)
+
 ImageSharpCommunity.Providers.Remote is a library that provides remote image loading functionality for the ImageSharp.Web library. It allows you to load images from remote URLs and integrate them seamlessly into your ImageSharp-based applications.
 
+[A wrapper package for Umbraco, simplyfying the setup is also available!](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/umbraco-marketplace-readme.md)
+
 ## Installation
 
 You can install the library via NuGet.
 
-# [Package Manager](#tab/tabid-1)
-
-```bash
-PM > Install-Package ImageSharpCommunity.Providers.Remote -Version VERSION_NUMBER
-```
-
-# [.NET CLI](#tab/tabid-2)
-
 ```bash
 dotnet add package ImageSharpCommunity.Providers.Remote --version VERSION_NUMBER
 ```
 
-# [PackageReference](#tab/tabid-3)
-
-```xml
-<PackageReference Include="ImageSharpCommunity.Providers.Remote" Version="VERSION_NUMBER" />
-```
-
-# [Paket CLI](#tab/tabid-4)
-
-```bash
-paket add ImageSharpCommunity.Providers.Remote --version VERSION_NUMBER
-```
-
-## Usage
-
-To use the `ImageSharpCommunity.Providers.Remote` library, register the remote image provider in your application's services configuration. This can typically be done in the ConfigureServices method of your Startup class:
-
-```csharp
-public void ConfigureServices(IServiceCollection services)
-{
-    // Other services configuration...
-
-    services.AddImageSharp()
-            .Configure<RemoteImageProviderOptions>(options =>
-            {
-                options.Settings
-                    .Add(new("/remote")
-                    {
-                        AllowedDomains = new List<string>() { "*" }
-                    });
-            })
-            .InsertProvider<RemoteImageProvider>(0);
-}
-```
-
-If you are using the default `WebRootProvider`, you need to make sure the `RemoteImageProvider` is inserted before that. Hence why `InsertProvider` is used instead of `AddProvider` in the above example.
-
-By default, no domains is allowed, so you have to configure your desired `RemoteImageProviderOptions` in order to use this provider.
-
-## Configuration Options
-
-The `RemoteImageProviderOptions` class provides the following configuration options:
-
-- `Settings`: A list of the different allowed sources for images. 
-
-Each setting (`RemoteImageProviderSetting`) provides the following configuration options:
-
-- `Prefix`: Specified in the constructor, and defines the local path to prefix all remote image requests with. For example, setting this to `/remote` allows requests like `/remote/https://test.com/test.png` to pass through this provider.
-
-- `RemoteUrlPrefix` (optional): Prefixes the URL on the server. For example, setting this to `https://test.com/` allows requests like `/remote/test.png` to download `https://test.com/test.png`. Note: You still need to allow the specific domain in the `AllowedDomains` setting.
-
-- `MaxBytes`: Specifies the maximum allowable download size in bytes. By default, it is set to `4194304` bytes (4 MB).
-
-- `Timeout`: Sets the timeout for a request in milliseconds. By default, it is set to `3000` milliseconds (3 seconds).
-
-- `UserAgent`: Sets a user agent value for the request. This can be useful for interacting with social networks. By default, it is set to `"ImageSharpRemoteProvider/0.1"`.
-
-- `HttpClientName`: Sets the name of the HttpClient to use when downloading images. By default, it is set to `"ImageSharpRemoteProvider/HttpClient"`.
-
-- `AllowedDomains`: Specifies a list of allowable domains to process images from. Images from domains not listed here will be blocked. This is an empty list by default. You can add `*` to allow all domains.
-
-- `AdditionalOptions`: Allows specifying additional `RemoteImageProviderOptions` instances. This can be useful when you have multiple configurations with different prefixes or other settings.
-
-Please note that these options provide customization and control over how remote images are loaded and processed. You can adjust these options according to your specific requirements.
-
-Don't forget to configure these options in your application's services configuration as shown in the Usage section of this README.
+## Documentation
 
-Please refer to the documentation or the XML comments in the code for more information about each option and its usage.
+- [Setup](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup.md)
+- [Configuration](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)
+- [Usage](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/usage.md)
 
 ## Contributing
 
 Contributions to the `ImageSharpCommunity.Providers.Remote` library are welcome! If you encounter any issues or have suggestions for improvements, please feel free to create a new issue or submit a pull request.
 
 ## License
 
-The `ImageSharpCommunity.Providers.Remote` library is licensed under the [MIT License](https://opensource.org/licenses/MIT). Please see the [LICENSE](LICENSE) file for more details.
+The `ImageSharpCommunity.Providers.Remote` library is licensed under the [MIT License](https://opensource.org/licenses/MIT). Please see the [LICENSE](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/LICENSE) file for more details.
diff --git a/docs/README_nuget.md b/docs/README_nuget.md
diff --git a/docs/README_nuget_Umbraco.md b/docs/README_nuget_Umbraco.md
diff --git a/docs/configuration.md b/docs/configuration.md
@@ -0,0 +1,36 @@
+# Configuration Options
+
+The `RemoteImageProviderOptions` class provides the following configuration options:
+
+- `Settings`: A list of the different allowed sources for images. 
+
+Each setting (`RemoteImageProviderSetting`) provides the following configuration options:
+
+- `Prefix`: Specified in the constructor, and defines the local path to prefix all remote image requests with. For example, setting this to `/remote` allows requests like `/remote/https://test.com/test.png` to pass through this provider.
+
+- `RemoteUrlPrefix` (optional): Prefixes the URL on the server. For example, setting this to `https://test.com/` allows requests like `/remote/test.png` to download `https://test.com/test.png`. Note: You still need to allow the specific domain in the `AllowedDomains` setting.
+
+- `MaxBytes`: Specifies the maximum allowable download size in bytes. By default, it is set to `10485760` bytes (10 MB).
+
+- `Timeout`: Sets the timeout for a request in milliseconds. By default, it is set to `180000` milliseconds (180 seconds - 3 minutes).
+
+- `UserAgent`: Sets a user agent value for the request. This can be useful for interacting with social networks. By default, it is set to `"ImageSharpRemoteProvider/[current version]"`.
+
+- `HttpClientName`: Sets the name of the HttpClient to use when downloading images. By default, it is set to `"ImageSharpRemoteProvider/HttpClient"`.
+
+- `AllowedDomains`: Specifies a list of allowable domains to process images from. Images from domains not listed here will be blocked. This is an empty list by default. You can add `*` to allow all domains. This can be used instead of, or in combination with `AllowedDomainsRegex`.
+
+- `AllowedDomainsRegex`: Specifies a list of regex patterns, matching allowable domains to process images from. Images from domains not matching any of the regexes will be blocked. This is an empty list by default. This can be used instead of, or in combination with `AllowedDomains`.
+
+- `AllowAllDomains`: Boolean value. If set to true, all domains is allowed to process.
+
+- `AdditionalOptions`: Allows specifying additional `RemoteImageProviderOptions` instances. This can be useful when you have multiple configurations with different prefixes or other settings.
+
+Please note that these options provide customization and control over how remote images are loaded and processed. You can adjust these options according to your specific requirements.
+
+Don't forget to configure these options in your application's services configuration as shown in the Usage section of this README.
+
+Please refer to the documentation or the XML comments in the code for more information about each option and its usage.
+
+- [Setup](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup.md) ([Umbraco](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup-umbraco.md))
+- [Usage](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/usage.md)
diff --git a/docs/setup-umbraco.md b/docs/setup-umbraco.md
@@ -0,0 +1,33 @@
+# Setup
+
+`Umbraco.Community.ImageSharpRemoteImages` is registered automatically when Umbraco starts, you just need to configure it.
+
+You can configure using appsettings.json, and a schema file is provided for easier setup.
+
+A configuration can look like this:
+
+```json
+{
+  "Umbraco": {
+    "Community": {
+      "ImageSharpRemoteImages": {
+        "Settings": [
+          {
+            "Prefix": "/ourumb",
+            "RemoteUrlPrefix": "https://our.umbraco.com",
+            "AllowedDomains": [ "our.umbraco.com" ]
+          },
+          {
+            "Prefix": "/remote",
+            "AllowedDomains": ["*"]
+          }
+        ]
+      }
+    }
+}
+```
+
+By default, no domains is allowed, so you have to configure your desired `RemoteImageProviderOptions` in order to use this provider.
+
+- [Configuration](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)
+- [Usage](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/usage.md)
diff --git a/docs/setup.md b/docs/setup.md
@@ -0,0 +1,28 @@
+# Setup
+
+To use the `ImageSharpCommunity.Providers.Remote` library, register the remote image provider in your application's services configuration. This can typically be done in the ConfigureServices method of your Startup class:
+
+```csharp
+public void ConfigureServices(IServiceCollection services)
+{
+    // Other services configuration...
+
+    services.AddImageSharp()
+            .Configure<RemoteImageProviderOptions>(options =>
+            {
+                options.Settings
+                    .Add(new("/remote")
+                    {
+                        AllowedDomains = new List<string>() { "*" }
+                    });
+            })
+            .InsertProvider<RemoteImageProvider>(0);
+}
+```
+
+If you are using the default `WebRootProvider`, you need to make sure the `RemoteImageProvider` is inserted before that. Hence why `InsertProvider` is used instead of `AddProvider` in the above example.
+
+By default, no domains is allowed, so you have to configure your desired `RemoteImageProviderOptions` in order to use this provider.
+
+- [Configuration](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)
+- [Usage](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)
diff --git a/docs/usage.md b/docs/usage.md
@@ -0,0 +1,26 @@
+# Usage
+
+Given the [example config](setup.md) ([for Umbraco here](setup-umbraco.md)), you can now request remote images using the path `/remote/https://test.com/path/to/img.jpg`.
+
+If using the RemoteUrlPrefix option, you can omit everything stated in the config. Eg. having set RemoteUrlPrefix to `https://test.com`, you can request images at `/remote/path/to/img.jpg`, which would then resolve to `https://test.com/path/to/img.jpg`.
+
+## Resolving "local" URL by remote URL
+
+If you don't like to hardcode URLs to images like the above, there is an extension method in `ImageSharpCommunity.Providers.Remote.Helpers` you can use to resolve the local URL.
+
+You need to inject the RemoteImageProviderOptions in first, and then you call it like `uri.GetRemoteImageProviderUrl(options)`
+
+Heres an example in a Razor view:
+
+```cshtml
+@using ImageSharpCommunity.Providers.Remote;
+@using ImageSharpCommunity.Providers.Remote.Configuration;
+@inject IOptions<RemoteImageProviderOptions> RemoteImageProviderOptions;
+@{
+    var uri = new Uri("https://test.com/path/to/image.jpg");
+    var localUrl = uri.GetRemoteImageProviderUrl(RemoteImageProviderOptions.Value); // "/remote/https://test.com/path/to/img.jpg"
+}
+```
+
+- [Setup](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup.md) ([Umbraco](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup-umbraco.md))
+- [Configuration](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)
diff --git a/src/ImageSharpCommunity.Providers.Remote/Configuration/RemoteImageProviderSetting.cs b/src/ImageSharpCommunity.Providers.Remote/Configuration/RemoteImageProviderSetting.cs
@@ -35,7 +35,7 @@ public RemoteImageProviderSetting(string prefix)
     /// <summary>
     /// Sets a useragent value for the request. Useful for social networks. See http://www.useragentstring.com/ for available values.
     /// </summary>
-    public string UserAgent { get; set; } = "ImageSharpRemoteProvider/0.1";
+    public string UserAgent { get; set; } = "ImageSharpRemoteProvider/" + typeof(RemoteImageProviderSetting).Assembly.GetName().Version;
 
     /// <summary>
     /// Sets the name of the HttpClient to use when downloading images.

diff --git a/src/ImageSharpCommunity.Providers.Remote/ImageSharpCommunity.Providers.Remote.csproj b/src/ImageSharpCommunity.Providers.Remote/ImageSharpCommunity.Providers.Remote.csproj
@@ -14,7 +14,7 @@
     <PackageId>ImageSharpCommunity.Providers.Remote</PackageId>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/skttl/ImageSharpCommunity.Providers.Remote</PackageProjectUrl>
-    <PackageReadmeFile>README_nuget.md</PackageReadmeFile>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageTags>image</PackageTags>
     <Product>ImageSharpCommunity.Providers.Remote</Product>
     <RepositoryType>git</RepositoryType>
@@ -30,7 +30,7 @@
   </ItemGroup>
 
   <ItemGroup>
-    <None Include="..\..\docs\README_nuget.md">
+    <None Include="..\..\README.md">
       <Pack>True</Pack>
       <PackagePath>\</PackagePath>
     </None>

diff --git a/src/Umbraco.Community.ImageSharpRemoteImages/Umbraco.Community.ImageSharpRemoteImages.csproj b/src/Umbraco.Community.ImageSharpRemoteImages/Umbraco.Community.ImageSharpRemoteImages.csproj
@@ -14,7 +14,7 @@
     <PackageId>Umbraco.Community.ImageSharpRemoteImages</PackageId>
     <PackageLicenseExpression>MIT</PackageLicenseExpression>
     <PackageProjectUrl>https://github.com/skttl/ImageSharp.Community.Providers.Remote</PackageProjectUrl>
-    <PackageReadmeFile>README_nuget.md</PackageReadmeFile>
+    <PackageReadmeFile>README.md</PackageReadmeFile>
     <PackageTags>image umbraco umbraco-marketplace</PackageTags>
     <Product>Umbraco.Community.ImageSharpRemoteImages</Product>
     <RepositoryType>git</RepositoryType>
@@ -30,7 +30,7 @@
     <Content Include="buildTransitive\**" PackagePath="buildTransitive" />
   </ItemGroup>
   <ItemGroup>
-    <None Include="..\..\docs\README_nuget.md" Link="README_nuget.md">
+    <None Include="..\..\umbraco-marketplace-readme.md" Link="README.md">
       <PackagePath>\</PackagePath>
       <Pack>True</Pack>
     </None>

diff --git a/umbraco-marketplace-readme.md b/umbraco-marketplace-readme.md
@@ -0,0 +1,29 @@
+# Umbraco.Community.ImageSharpRemoteImages
+
+[![Downloads](https://img.shields.io/nuget/dt/Umbraco.Community.ImageSharpRemoteImages?color=cc9900)](https://www.nuget.org/packages/Umbraco.Community.ImageSharpRemoteImages/)
+[![NuGet](https://img.shields.io/nuget/vpre/Umbraco.Community.ImageSharpRemoteImages?color=0273B3)](https://www.nuget.org/packages/Umbraco.Community.ImageSharpRemoteImages)
+[![GitHub license](https://img.shields.io/github/license/skttl/ImageSharp.Community.Providers.Remote?color=8AB803)](https://github.com/skttl/ImageSharp.Community.Providers.Remote/blob/main/LICENSE)
+
+Umbraco.Community.ImageSharpRemoteImages is a package wrapping [ImageSharpCommunity.Providers.Remote](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/README.md), which is a library that provides remote image loading functionality for the ImageSharp.Web library. It allows you to load images from remote URLs and integrate them seamlessly into your ImageSharp-based applications.
+
+## Installation
+
+You can install the library via NuGet.
+
+```bash
+dotnet add package Umbraco.Community.ImageSharpRemoteImages --version VERSION_NUMBER
+```
+
+## Documentation
+
+- [Setup](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/setup-umbraco.md)
+- [Configuration](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/configuration.md)
+- [Usage](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/docs/usage.md)
+
+## Contributing
+
+Contributions to the `Umbraco.Community.ImageSharpRemoteImages` and `ImageSharpCommunity.Providers.Remote` library are welcome! If you encounter any issues or have suggestions for improvements, please feel free to create a new issue or submit a pull request.
+
+## License
+
+The `Umbraco.Community.ImageSharpRemoteImages` and `ImageSharpCommunity.Providers.Remote` library is licensed under the [MIT License](https://opensource.org/licenses/MIT). Please see the [LICENSE](https://github.com/skttl/ImageSharpCommunity.Providers.Remote/blob/main/LICENSE) file for more details.