Scully - Create A Custom Plugin

Scully follows the plugin system to process the pages at the time of the pre-rendering. It has various inbuilt plugins and community plugins.

 

In the previous article, Syntax highlighting in markdown for blog made with Scully, we have used the markdown plugin, which is the inbuilt plugin provided by Scully. While in the article, Using Copy To Clipboard Plugin To Add Copy Button In Code Snippets we have used one of the community plugins.

You can also create a custom plugin and use it in our application for handling the prerendering process. Scully has six main types of plugins.

In this article, we will see how to create a custom Scully plugin.  If you want to code along, clone or copy this GitHub repository.

 

Check out the previous Scully series articles,

• Getting Started With Scully - Angular Static Site Generator
• Create Blogging Site With Angular And Scully
• Syntax Highlighting In Markdown For Blog Made with Scully
• Using Copy To Clipboard Plugin To Add Copy Button In Code Snippets

Let's get started.

 

We will create a footer plugin, which will add the author name and blog updated date.

 

Creating a custom plugin for Scully is easy. We just need to follow the below steps:

1. Create a plugin function,
   

   // pugin.ts
   
   import { registerPlugin, getPluginConfig } from '@scullyio/scully';
   
   export const myPlugin = 'myPlugin';
   
   const myFunctionPlugin = async (html: string): Promise<string> => {
     return html;
   };
   
   const validator = async () => [];

2. Register a plugin,
   

   // plugin.ts
   
   registerPlugin('postProcessByHtml', myPlugin, myFunctionPlugin, validator);

   - postProcessByHtml is one of the plugin types.
   
   
3. Use the plugin,
   
   To use a custom plugin, we need to add it in scully.[projectName].config.ts
   

   // scully.[projectName].config.ts
   
   import { myPlugin }  from './scully/plugins/plugin';
   
   export const config: ScullyConfig = {
     ...
     defaultPostRenderers : [myPlugin],
     routes: {
       '/blog/:slug': {
         type: 'contentFolder',
         slug: {
           folder: "./blog"
         }
       },
     }
   };

At the time of Scully installation by default, it adds one plugin.ts file which we will use for creating a custom plugin.

 

Scully Plugin Types

There are six main types of plugins that allow code to be injected into various stages of the Scully process lifecycle. We can create a custom plugin for any type based on our requirements.

1. router - plugins teach Scully how to get the required data to pre-render pages from the route params.
2. postProcessByDom - is a kind of render plugin, which allows you to update the DOM. You will get the JSDOM object in the plugin function as an argument.
3. postProcessByHtml - is a also a render plugin which executes after postProcessByDom. In this plugin function, you get an HTML string as an argument.
4. fileHandler - plugin is used by the contentFolder plugin during the render process. The contentFolder plugin processes the folders for markdown files or another file type the folders may contain.
5. routeDiscoveryDone - plugins are called automatically after all routes have been collected and all router plugins have finished.
6. allDone - plugins are like routeDiscoveryDone plugins, except they are called after Scully finishes executing all its processes.

Create Footer Plugin

We will create a postProcessByDom plugin. Which will take DOM as an argument. 

// plugin.ts
import {
    registerPlugin,
    getPluginConfig,
    HandledRoute
} from '@scullyio/scully';
import {
    JSDOM
} from 'jsdom';
export const footerPlugin = 'footerPlugin';
const footerPluginFunction = async (dom: JSDOM, route: HandledRoute): Promise < JSDOM > => {
    console.log('Route Data : ', route.data);
    let document = dom.window.document;
    let footer = document.createElement('footer');
    footer.className = 'blog-footer'
    footer.innerHTML = `<span> ✍ ${route.data.author} </span>
                      <span> 📅 ${new Date().toLocaleDateString()}</span>`
    document.querySelector('body').appendChild(footer);
    return dom;
};
const validator = async () => [];
registerPlugin('postProcessByDom', footerPlugin, footerPluginFunction, validator);

Use Footer Plugin

To use this plugin we need to add it in defaultPostRenderers array of ScullyConfig, or if you want to add it for any specific routes you can set it in postRenderers, as shown below:

import { ScullyConfig, setPluginConfig } from '@scullyio/scully';
import { footerPlugin }  from './scully/plugins/plugin';

export const config: ScullyConfig = {
  projectRoot: "./src",
  projectName: "portfolio",
  outDir: './dist/static',
  routes: {
    '/blog/:slug': {
      type: 'contentFolder',
      postRenderers: [ footerPlugin ],
      slug: {
        folder: "./blog"
      }
    },
  }
};

Add author in markdown meta details:

 

Great!!! We have created the footer plugin, now take a build and test it.

 

Output

 

Take a build with the following command:

npm run scully -- --scanRoutes && npm run scully:serve

Now go to the blog page and verify the output.

 

 

Summary

 

In this article, we have seen how to create a custom Scully plugin. We have created a footer plugin that adds the blog meta details in the blog footer. You can create other plugins based on your requirement.

 

I hope you like this article. Please provide your valuable feedback and suggestions in the comment section🙂.

 

If you feel this is useful to others please like and share.