Anonymous View
Skip to content

Writing a Plugin

Jump to bottom
James Messinger edited this page Mar 10, 2020 · 9 revisions

CodeEngine

Tutorial

Your First Plugin

Plugins are what makes CodeEngine so powerful and versatile. CodeEngine's plugin API allows you to customize every part of the run lifecycle and transform files however you want.

Step 1: Setup

We need to create a CodeEngine generator so we can use the plugin that we're about to create. So start-off by creating a new folder anywhere on your computer named "my-generator". In that folder, you'll create the following file structure:

my-generator
  |-- index.ts
  |-- plugins
       |-- footer.ts
  |
  |-- src
       |-- index.html
       |-- img
            |-- photo1.jpg
            |-- photo2.jpg
            |-- photo3.jpg

NOTE: We'll be using TypeScript for this tutorial, since CodeEngine natively supports TypeScript (no build step needed) and it allows us to use the latest ECMAScript module syntax. Notice that the index.ts and footer.ts files above have .ts extensions rather than .js extensions.

my-generator/index.ts
This file is This is your CodeEngine generator. See "Creating a Generaor" for details about how generators work.

This generator just tells CodeEngine to use your plugin.

export default {
  plugins: [
    "./plugins/footer.ts"
  ]
};

my-generator/plugins/footer.ts
This file is your CodeEngine plugin. The simplest CodeEngine plugin is just a function that accepts a File object. The function can do whatever it wants to the file before returning it, such as changing its contents or metadata.

Our plugin checks if the file is an HTML file, then it inserts a <footer> tag just before the closing </body> tag. The footer contains a copyright notice with the current year.

const currentYear = new Date().getFullYear();

/**
 * This is a CodeEngine plugin that adds a copyright footer to all HTML pages.
 */
export default function appendFooter(file) {
  if (file.extension === ".html") {
    file.text = file.text.replace(
      "</body>",
      `<footer>Copyright © ${currentYear}</footer></body>`
    );
  }

  return file;
}

my-generator/src/index.html
This is an HTML page that shows a photo library. Notice that there is no <footer> in this file. Our plugin (above) will insert a footer for us.

<html>
  <body>
    <h1>My Photo Library</h1>
    <ul>
      <li><img src="img/photo1.jpg"></li>
      <li><img src="img/photo2.jpg"></li>
      <li><img src="img/photo3.jpg"></li>
    </ul>
  </body>
</html>

my-generator/src/img
Copy any 3 image files that you have available into this folder. Or snag some photos here. Make sure you save the photos with the names photo1.jpg, photo2.jpg, and photo3.jpg.

Step 2: Run It!

Open a terminal window and navigate to your "my-generator" directory. In that directory, run the code-engine command without any arguments.

The output should look something like this:

my-generator $: code-engine
 ______            __          ______
|   ___|          |  |        |   ___|               __
|  |     _____  __|  | _____  |  |_    __ __  _____ |__| __ __  _____
|  |    |  _  ||  _  ||  __ | |   _|  |  \  ||  _  ||  ||  \  ||  __ |
|  |___ | |_| || |_| ||  __|  |  |___ |     || |_| ||  ||     ||  __|
|______||_____||_____||_____| |______||__\__||___  ||__||__\__||_____|
                                             |_____|
           build tool | code generator | static site builder
                                v0.0.6

input:  4 files (255.61 KB)
output: 4 files (255.61 KB)
time:   0.0130 seconds

And now if you check your "my-generator" folder, you'll see that there's a new sub-folder named "dist", which contains a copy of everything from your "src" directory. If you open the dist/index.html, you'll see that your plugin worked! It added the <footer> tag to the end of the file.

my-generator/dist/index.html

<html>
  <body>
    <h1>My Photo Library</h1>
    <ul>
      <li><img src="img/photo1.jpg"></li>
      <li><img src="img/photo2.jpg"></li>
      <li><img src="img/photo3.jpg"></li>
    </ul>
  <footer>Copyright © 2019</footer></body>
</html>

Customization

API Reference

Clone this wiki locally