Plugins provide additional contexts while building an app with ScissorHands.NET. A plugin may add extra HTML tag elements, replace existing HTML elements with something else or convert a placeholder to something else.

Plugin Structure

Each plugin has at least the following structure:

.
├── README.md
│
├── MyAwesomePlugin.sln
│
└── MyAwesomePlugin/
    ├── MyAwesomePlugin.csproj
    ├── _Imports.razor
    ├── MyAwesomePluginComponent.razor
    └── MyAwesomePlugin.cs

• README.md: README document of the plugin
• *.sln: A solution file for the plugin
• *.csproj: A project file that contains the plugin
• _Imports.razor: Defines global using directives
• *Component.razor: Defines the UI component representing the plugin
• *Plugin.cs: Defines the placeholder replacement representing the plugin

Getting Started

1. Set environment variables for GitHub NuGet Package Registry.

   # zsh/bash
   export GH_PACKAGE_USERNAME="<GITHUB_USERNAME>"
   export GH_PACKAGE_TOKEN="<GITHUB_TOKEN>"
   

   # PowerShell
   $env:GH_PACKAGE_USERNAME = "<GITHUB_USERNAME>"
   $env:GH_PACKAGE_TOKEN = "<GITHUB_TOKEN>"
   

2. Create a Razor class library project.

   dotnet new razorclasslib -n MyAwesomePlugin
   

3. Add a NuGet package.

   dotnet add package ScissorHands.Plugin --prerelease
   

4. Create a plugin class inheriting the ScissorHands.Plugin.ContentPlugin class.

   public class MyAwesomePlugin : ContentPlugin
   {
       public override string Name => "My Awesome ScissorHands Plugin";
   
       public override async Task<ContentDocument> PreMarkdownAsync(
           ContentDocument document,
           PluginManifest plugin, 
           SiteManifest site,
           CancellationToken cancellationToken = default)
       {
           // ADD LOGIC HERE
       }
   
       public override async Task<ContentDocument> PostMarkdownAsync(
           ContentDocument document,
           PluginManifest plugin,
           SiteManifest site,
           CancellationToken cancellationToken = default)
       {
           // ADD LOGIC HERE
       }
   
       public override async Task<string> PostHtmlAsync(
           string html,
           ContentDocument document,
           PluginManifest plugin,
           SiteManifest site,
           CancellationToken cancellationToken = default)
       {
           // ADD LOGIC HERE
       }
   }
   

5. Create a plugin component inheriting the ScissorHands.Plugin.PluginComponentBase class.

   @* MyAwesomePluginComponent.razor *@
   @inherits ScissorHands.Plugin.PluginComponentBase
   
   <!-- ADD HTML ELEMENTS HERE -->
   
   @code {
       // ADD UI COMPONENT LOGIC HERE
   }
   

Properties of Plugin Component

Since a plugin component inherits ScissorHands.Plugin.PluginComponentBase, it exposes the following properties for plugin developers to use:

• Name: Parameter. Name of the plugin.
• Documents: Cascading Parameter. List of content documents – used by IndexView.razor
• Document: Cascading Parameter. Content document – used by PostView.razor and PageView.razor
• Plugins: Cascading Parameter. List of plugins defined in the Plugins section of appsettings.json
• Plugin: Plugin matches to the component, filtered by its name when it's being initialised.
• Theme: Cascading Parameter. Theme configuration defined in theme.json
• Site: Cascading Parameter. Site configuration defined in the Site section of appsettings.json

Use Plugin

To use a plugin, it MUST be configured in appsettings.json beforehand.

Plugin Configuration

Open appsettings.json and add the plugin configurations to the Plugins section:

{
  "Plugins": [
    {
      "Name": "My Awesome ScissorHands Plugin",
      "Options": {
        "Option1": "value1",
        "Option2": "value2"
      }
    }
  ]
}

NOTE: Make sure to have the same plugin name in the settings to the one defined in the plugin package.

Plugin as Component

You can add the plugin as a Razor component. Put your plugin component to MainLayout.razor, IndexView.razor, PostView.razor or PageView.razor of your theme. Here's an example putting the plugin to MainLayout.razor.

@* MainLayout.razor *@
...

<MyAwesomePluginComponent Name="My Awesome Plugin" />

...

Plugin as Placeholder

You can add the plugin as a placeholder. Put your plugin placeholder to MainLayout.razor, IndexView.razor, PostView.razor or PageView.razor of your theme. Here's an example putting the plugin to MainLayout.razor.

@* MainLayout.razor *@
...

<plugin:my-awesome-plugin />

...

Plugin as Markdown

TBD

List of Plugins

Here are the list of plugins you can currently use – either official or community contributed.

Official Plugins

• Google Analytics
• Open Graph

Community Plugins

TBD

👈 Themes | 👆 Documentation