SEO Assistant

The SEO Assistant module generates SEO page metadata automatically through the use of AI. It comes configured for use with the OpenAI models. It is also possible to configure your own providers, see related section.

Installation

This initial version of the @apostrophecms-pro/seo-assistant extension depends on the @apostrophecms-pro/automatic-translation extension. In future versions, the requirements supplied by this extension will be migrated to the Apostrophe core or an AI-core extension.

To install the module, use the command line to run this command in an Apostrophe project's root directory:

npm install @apostrophecms-pro/seo-assistant @apostrophecms-pro/automatic-translation @apostrophecms/seo

The SEO extension is also required, if not already present, for the SEO Assistant module to work.

Find the minimum required versions below:

{
  "@apostrophecms-pro/automatic-translation": "^1.1.0",
  "@apostrophecms/seo": "^1.0.0",
  "apostrophe": "^4.3.2"
}

Configuration

Initial setup

You need to set an environment variable OPENAI_API_KEY with your OpenAI API key.

export OPENAI_API_KEY=your-openai-api-key

Configure the SEO Assistant module in the app.js file:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms-pro/automatic-translation': {
      options: {
        enabled: false
      }
    },
    '@apostrophecms/seo': {},
    '@apostrophecms-pro/seo-assistant': {
      options: {
        provider: 'openai'
      }
    },
    '@apostrophecms-pro/seo-assistant-openai': {}
  }
});

Note: The @apostrophecms-pro/seo and @apostrophecms-pro/automatic-translation modules are required for the SEO Assistant module to work. If you already have these modules configured in your project, you can keep the existing configuration in the app.js file. However, it's important to register the @apostrophecms-pro/seo-assistant module AFTER the @apostrophecms-pro/seo module.

Although it's not recommended, you can also set the OpenAI API key directly in the module configuration:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    // ...
    '@apostrophecms-pro/seo-assistant-openai': {
      options: {
        apiKey: 'your-openai-api-key'
      }
    
    }
  }
});

Additional configuration

You can provide a minimum page context length restriction by configuring the module:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    // ...
    '@apostrophecms-pro/seo-assistant-openai': {
      options: {
        minContextLength: 100
      }
    }
  }
});

When minContextLength is set to a number, the module will not generate metadata for pages with a text content length less than the specified value. The default behavior is no restriction.

OpenAI provider configuration

The OpenAI module @apostrophecms-pro/seo-assistant-openai provides an additional model configuration option:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    // ...
    '@apostrophecms-pro/seo-assistant-openai': {
      model: 'gpt-3.5-turbo',
    }
  }
});

You can change it to any of the supported OpenAI models. The default model is gpt-4o.

How to use the SEO Assistant

The SEO Assistant module provides a field indicator UI for the SEO Title and Description fields in the page/piece editor. When the user clicks on the indicator, the module will offer an action to generate metadata suggestions based on the current page content and pre-configured AI prompt. The editor can accept the suggestion (and edit it if needed), retry the suggestion, or edit the prompt and retry the suggestion.

SEO Assistant context menu:

SEO Assistant suggestion:

SEO Assistant edit prompt:

SEO Assistant use the suggestion (after clicking the "Use this suggestion" button):

Custom provider

You can create a custom provider to fit your project needs. To do so, create a new module and follow this example:

// modules/my-provider/index.js
module.exports = {
  init(self) {
    self.apos.modules['@apostrophecms-pro/seo-assistant']
      .registerProvider(self, {
        name: 'my-provider',
        label: 'My Provider'
      });
    // Do whatever you need to do here
  },

  // `field` is the schema definition of `seoTitle` or `seoDescription`.
  // Return a text prompt, used in `generatePrompt` method, editable by a site editor.
  async getEditorPromptFor(req, field) {},
  // `editorPrompt` is the text prompt returned by `getEditorPromptFor` method.
  // `field` is the schema definition of `seoTitle` or `seoDescription`.
  // `context` is the extracted text from the page, array of objects with 
  // `name` (field name) and `text` properties. 
  // Return a text prompt in the shape required by your `generateSuggestion` method.
  async generatePrompt(req, { context, field, editorPrompt }) {},
  // `prompt` is the result returned by `generatePrompt` method.
  // Return the suggestion text.
  async generateSuggestion(req, prompt) {}
};

Be sure to register your module as shown in the init() section above. You can set the name and label properties to whatever you want. As usual, your module needs to be added to the project app.js file.

The getEditorPromptFor method should return a text prompt, based on the current field (seoTitle or seoDescription), that is going to be editable by a site editor. The generatePrompt method should return a prompt for the AI model to generate metadata. The generateSuggestion method should consume the prompt generated by the generatePrompt method and return the metadata suggestion.

Custom icons and labels

You can customize the icon of the button used to trigger the assistant in the SEO Assistant module. The new icon and optional label and class properties are passed through the triggerAssistantButton option:

require('apostrophe')({
  shortName: 'my-project',
  modules: {
    '@apostrophecms-pro/automatic-translation': {
      options: {
        enabled: false
      }
    },
    '@apostrophecms/seo': {},
    '@apostrophecms-pro/seo-assistant': {
      icons: {
        'panda-icon': 'Panda'
      },
      options: {
        provider: 'openai',
        triggerAssistantButton: {
          icon: 'panda-icon',
          label: 'Generate with AI',
          class: [ 'blue-yellow' ]
        }
      }
    },
    '@apostrophecms-pro/seo-assistant-openai': {}
  }
});

By using the class blue-yellow, you can add the following CSS selector to customize the trigger assistant button

.apos-button.apos-button--blue-yellow {
  background-color: yellow;
  border: 4px solid blue;
}

Changing the position of the meta label

You can position the meta label on the left (default) or right side.

// modules/@apostrophecms/seo-assistant-doc-type/index.js
module.exports = {
  options: {
    seoAssistantMetaPosition: 'right'
  }
};

See the README for the @apostrophecms/automatic-translation module for information on changing the meta label text.