npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@jungvonmatt/contentful-ssg

v1.14.2

Published

[![NPM version][npm-image]][npm-url] [![Build Status][ci-image]][ci-url] [![Coverage][coveralls-image]][coveralls-url]

Downloads

526

Readme

NPM version Build Status Coverage

JvM Contentful export for static site generators

Export contentful entries to filesystem (md/yaml) for static site generators (hugo/grow/...)

Automatically removes all files from the configured output directory that are not part of the exported entries. When a .gitignore file is found only ignored files are removed.

Getting started

Install

npm install --save-dev @jungvonmatt/contentful-ssg

Commands

help

npx cssg help [command]

init

npx cssg init

Initializes contentful-ssg and stores the config values in the contentful-ssg.config.js file.

Contentful SSG ships with built in typescript support. Add --typescript to generate a typescript configuration file.

npx cssg init --typescript

Configuration values

| Name | Type | Default | Description | | ------------------ | --------------------------------------------------------------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | accessToken | string | undefined | Content Delivery API - access token | | previewAccessToken | string | undefined | Content Preview API - access token | | spaceId | string | undefined | Contentful Space id | | environmentId | string | 'master' | Contentful Environment id | | format | string|function|object | 'yaml' | File format ( yaml, toml, md, json) You can add a function returning the format or you can add a mapping object like {yaml: [glob pattern]} (pattern should match the directory) | | plugins | [string]|[[string, options]]|[{resolve:'string', options:{}}] | [] | Add plugins to contentful-ssg. See Plugins | | directory | string | './content' | Base directory for content files. | | validate | function | undefined | Pass function(transformContext, runtimeContext){...} to validate an entry. Return false to skip the entry completely. Without a validate function entries with a missing required field are skipped. | | transform | function | undefined | Pass function(transformContext, runtimeContext){...} to modify the stored object. Return undefined to skip the entry completely. (no file will be written) | | mapDirectory | function | undefined | Pass function(transformContext, runtimeContext, defaultValue){...} to customize the directory per content-type relative to the base directory. | | mapFilename | function | undefined | Pass function(transformContext, runtimeContext, defaultValue){...} to customize the filename per entry | | mapAssetLink | function | undefined | Pass function(transformContext, runtimeContext, defaultValue){...} to customize how asset links are stored | | mapEntryLink | function | undefined | Pass function(transformContext, runtimeContext, defaultValue){...} to customize how entry links are stored | | mapMetaFields | function | undefined | Pass function(transformContext, runtimeContext, defaultValue){...} to customize the meta fields per entry | | richTextRenderer | boolean|object|function | {} | We use the contentful rich-text-html-renderer to render the html. You can pass a configuration object or you can pass function(document){...} to use your own richtext renderer or you can turn it off by passing false to get a mirrored version of the JSON output | | before | function | undefined | Runs function(runtimeContext){...} before processing the content right after pulling data from contentful | | after | function | undefined | Runs function(runtimeContext){...} after processing the content right before the cleanup |

Plugins

You can add plugins to contentful-ssg by adding the package name or a local path to the plugins array of your configuration.

plugins: ['my-plugin-package', './plugins/my-local-plugin]

All plugins can have options specified by wrapping the name and an options object in an array inside your config or by using a more verbose object notation.

For specifying no options, these are all equivalent:

{
  "plugins": ["my-plugin", ["my-plugin"], ["my-plugin", {}], {resolve: "my-plugin", options: {}}]
}

To specify an option, pass an object with the keys as the option names.

{
  "plugins": [
    [
      "my-plugin-a",
      {
        "option": "value"
      }
    ],
    {
      resolve: "my-plugin-b",
      options: {
        "option": "value"
      }
    }
  ]
}

Runtime Hooks

before

import
(runtimeContext) => {
  // Do things before processing the localized contentful entries
  // The return value should be an object which is merged with the runtime context.
  return { key: 'test' };
}

after

(runtimeContext) => {
  // Do things after processing the localized contentful entries before cleanup
  // We have access to values added to the context in the before hook
  console.log(runtimeContext.key); // -> 'test'
};

Transform Hooks

transform

(transformContext, runtimeContext) => {
  const { content } = transformContext;
  // modify content and
  // return object
  return content;
};

mapFilename

(transformContext, runtimeContext, defaultValue) => {
  // customize the filename on entry level
  // return string
  return defaultValue;
};

mapDirectory

(transformContext, runtimeContext, defaultValue) => {
  // customize the directory on entry level
  // return string
  return defaultValue;
};

mapAssetLink

(transformContext, runtimeContext, defaultValue) => {
  const {asset} = transformContext;
  // customize the asset representation in front matter
  // return object
  return { ...defaultValue, ... };
}

mapEntryLink

(transformContext, runtimeContext, defaultValue) => {
  const {entry} = transformContext;
  // customize how the entry is added to your front matter
  // return object
  return { ...defaultValue, ... };
}

mapMetaFields

(transformContext, runtimeContext, defaultValue) => {
  const {entry} = transformContext;
  // customize how the sys meta data is added to your front matter
  // return object
  return { ...defaultValue, ... };
}

Helper functions

collectValues

Get values from linked pages to e.g. build an url out of parent slugs.

{
  transform: (context) => {
    const { utils } = context;
    const slugs = utils.collectValues('fields.slug', {
      linkField: 'fields.parentPage',
    });

    return { ...content, url: '/' + slugs.join('/') };
  };
}
collectParentValues

The same as collectValues just without the value from the current entry

waitFor

Wait for specific entry to be transformed. Be aware that this can lead to deadlocks when you're awaiting something which itself is waiting for the current entry to be transformed.

{
  transform: (context) => {
    const { utils } = context;
    try {
      // You can overwrite the default wait timeout of 20000ms using the second parameter
      const linkedContext = await utils.waitFor('<contentful-id>', 5000);

      // Do something usefull with the transformed data
      // which you can't do with context.entryMap.get('<contentful-id>')
    } catch (error) {
      // Entry isn't available, the transform method for the entry throws an error
      // or we encountered a cyclic dependency
    }

    return { ...content };
  };
}

fetch

Fetch all content entries and store them as yaml in the configured directory

npx cssg fetch

To see all available command line options call

npx cssg help fetch

watch

Same as fetch but also starts a webserver listening for changes and registers a contentful webhook

npx cssg watch

To see all available command line options call

npx cssg help watch

Example configuration

Grow

See cssg-plugin-grow

Hugo

See cssg-plugin-hugo