sourcebit-target-hugo

A Sourcebit plugin for the Hugo static site generator

👩‍🏫 Introduction

This plugin writes content from any Sourcebit data source into files compatible with the Jekyll static site generator.

🏗 Installation

To install the plugin and add it to your project, run:

npm install sourcebit-target-hugo --save

💡 You don't need to run this command if you start Sourcebit using the interactive setup process, as the CLI will install the plugin for you and add it as a dependency to your project.

⚙️ Configuration

The plugin accepts the following configuration parameters. They can be supplied in any of the following ways:

• In the options object of the plugin configuration block inside sourcebit.js, with the value of the Property column as a key;
• As an environment variable named after the Env variable column, when running the sourcebit fetch command;
• As part of a .env file, with the value of the Env variable column separated by the value with an equals sign (e.g. MY_VARIABLE=my-value);
• As a CLI parameter, when running the sourcebit fetch command, using the value of the Parameter column as the name of the parameter (e.g. sourcebit fetch --my-parameter).

| Property | Type | Visibility | Default value | Env variable | Parameter | Description | | ------------------ | -------- | ---------- | ------------- | ------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | fullAssetObjects | Boolean | Public | false | | | By default, values of fields that reference assets will be written as a string containing just the asset URL. To get a full asset object instead, set fullAssetObjects to true. | | writeFile | Function | Public | | | | A function that computes the files to be created, as well as their location, format and contents (see below for more details). |

The writeFile function is invoked on each entry from the objects data bucket, with the following parameters:

• entry (Object): An entry from the objects data bucket
• utils (Object): An object containing utility methods:
  • slugify (Function): Creates a filename-friendly version of any string (e.g. utils.slugify('Hello, Sourcebit friends!') === 'hello-sourcebit-friends')

The return value of this function determines whether the entry being evaluated will be written to a file and, if so, defines the path, the format and the contents of the file.

To write a file for an entry, the return value should be an object with a content, format and path properties. The nature of these properties may vary slightly based on the value of format, as shown in the table below.

| format | content | path | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------- | | frontmatter-md | Object containing a frontmatter and body properties, which will be written to the file's frontmatter and content body, respectively | The absolute path to the file. Must end with .md. | Writes a Markdown file with a YAML frontmatter. | | yml | Object to be written as YAML | The absolute path to the file. Must end with .yaml or .yml | Writes a YAML file. | | json | Object to be written as JSON | The absolute path to the file. Must end with .json. | Writes a JSON file |

💡 If you wish to create multiple files for an entry, set the return value to an array of objects, each containing a content, format and path properties.

👀 Example configuration

sourcebit.js

module.exports = {
  plugins: [
    {
      module: require("sourcebit-target-hugo"),
      options: {
        writeFile: function(entry, utils) {
          const { __metadata: meta, ...fields } = entry;

          if (!meta) return;

          const { createdAt = "", modelName, projectId, source } = meta;

          if (
            modelName === "post" &&
            projectId === "123456789" &&
            source === "sourcebit-source-contentful"
          ) {
            const { __metadata, content, layout, ...frontmatterFields } = entry;

            return {
              content: {
                body: fields["content"],
                frontmatter: { ...frontmatterFields, layout: fields["layout"] }
              },
              format: "frontmatter-md",
              path:
                "content/posts/" +
                createdAt.substring(0, 10) +
                "-" +
                utils.slugify(fields["title"]) +
                ".md"
            };
          }
        }
      }
    }
  ]
};

🧞‍♂️ Interactive setup process

This plugin offers an interactive setup process via the npx create-sourcebit command. It asks users to categorize each of the content models present in the models data bucket as a page or data object. For each model selected, the user is asked to define the location and the source of different frontmatter values.

📥 Input

This plugin expects the following data buckets to exist:

• models: An array of content models
• objects: An array of content entries

📤 Output

This plugin creates files on disk, in locations and with formats defined by the writeFile function.