Reader

Creates CloudCannon build information for sites made with any static site generator.

This tool runs after your SSG build, reading your configuration to find pages, collections, and data files to create a JSON file used to automatically integrate the site with CloudCannon. This JSON file is written to _cloudcannon/info.json.

• Installation
• Configuration
• Documentation
  • Source
  • Output
  • Data
  • Collections
  • CloudCannon
• Parsers
• Development
• License

Installation

You don't have to install anything when building on CloudCannon. This tool is automatically installed before your site is built. This gives you the latest support, new features, and fixes as they are released.

If required, you can install the tool manually to test the integration and diagnose issues.

npm install --global @cloudcannon/reader

This gives you access to the cloudcannon-reader binary.

Configuration

Configuration files should be in the root directory (or the same directory you run cloudcannon-reader). The first supported file found in this order is used:

• cloudcannon.config.json
• cloudcannon.config.yaml
• cloudcannon.config.yml
• cloudcannon.config.js
• cloudcannon.config.cjs

Alternatively, use a specific file with the CLOUDCANNON_CONFIG_PATH environment variable or the --config command line option:

$ CLOUDCANNON_CONFIG_PATH=src/cloudcannon.config.js cloudcannon-reader
$ cloudcannon-reader --config "src/cloudcannon.config.js"

Your global CloudCannon configuration is set in this file as well, as it's used as a base to generate _cloudcannon/info.json (used to integrate your site with CloudCannon).

Example content for cloudcannon.config.cjs:

module.exports = {
  // Global CloudCannon configuration
  _inputs: {
    title: {
      type: 'text',
      comment: 'The title of your page.'
    }
  },
  _select_data: {
    colors: ['Red', 'Green', 'Blue']
  },

  // Read from ./src instead of .
  source: 'src',

  // Write to ./output/_cloudcannon/info.json instead of ./_cloudcannon/info.json
  output: 'output',

  // Populates the sidebar navigation and provides metadata for the editor
  collections_config: {
    people: {
      // Reads the contents of each file in this directory
      path: 'content/people',

      // The URL template for items in this collection
      url: '/people/{department|slugify}/[slug]/',

      // Tells CloudCannon this collection produces output files
      output: true

      // CloudCannon collection-level configuration
      name: 'Personnel',
      _enabled_editors: ['data']
    },
    posts: {
      // Reads the contents of each file in this directory
      path: '_posts',

      // How to parse the files in this collection
      parser: 'front-matter',

      // The URL function for items in this collection
      url: (filePath, parsed, { filters }) => {
        const year = new Date(parsed.date).getFullYear();
        const slug = filters.slugify(parsed.title || '');
        return `/posts/${year}/${slug}/`;
      },

      // Tells CloudCannon this collection produces output files
      output: true
    },
    pages: {
      // Tells CloudCannon to navigate to this path for this collection
      path: '',

      // Limits files read to these patterns (relative to path)
      glob: ['**/*.md', '*.html'],

      // Tells CloudCannon to only show successfully parsed files for this collection
      // Useful for excluding other collections when using '' as path
      filter: 'strict',

      // Tells CloudCannon this collection produces output files
      output: true
    },
    data: {
      // Reads the contents of each file in this directory
      path: 'data',

      // How to parse the files in this collection
      parser: (filePath, raw, { parsers, filters }) => {
        const parsed = parsers['front-matter'].parse(raw);
        const slug = filters.slugify(parsed.title || '');
        return { ...data, slug };
      }
    }
  },

  // Generates the data for select and multiselect inputs matching these names
  data_config: {
    authors: {
      // Reads the contents of this file
      path: 'data/authors.csv'
    },
    offices: {
      // Reads the contents of each file in this directory
      path: 'data/offices',
      parser: 'json'
    }
  }
};

Documentation

The _cloudcannon/info.json file is initially populated with the contents of your configuration. cloudcannon-reader then generates values for collections, data, time, version, and cloudcannon.

Source

The source settings changes where to read from another folder. The path value for collection items is relative to source. Defaults to '.'.

Output

The output settings changes where to write the _cloudcannon folder containing info.json. Defaults to '.'.

Data

The data_config defines how data files should be read and parsed into the JSON representation. Defaults to {}.

{
  "data_config": {
    "locations": {
      "path": "data/locations.csv"
    },
    "offices": {
      "path": "data/offices",
      "parser": "front-matter"
    }
  }
}

The available keys in each data set configuration are:

Collections

The collections_config object defines how collections and their files should be read and parsed into the JSON representation. Defaults to {}.

{
  "collections_config": {
    "posts": {
      "path": "content/posts",
      "parser": "yaml",
      "url": "/posts/{category|slugify}/[slug].html"
    }
  }
}

Matches the collection-level configuration format for CloudCannon, which is also set here (e.g. name, _enabled_editors, add_options).

The keys available in each collection configuration are:

CloudCannon

Set global CloudCannon configuration as top level keys in your cloudcannon-reader configuration and they'll be copied across to _cloudcannon/info.json.

CloudCannon then reads these in the app and applies them to your editing interface. These include:

• collection_groups
• editor
• source_editor
• _enabled_editors
• _inputs
• _editables
• _select_data
• _structures

Parsers

Parsers define how cloudcannon-reader processes your files into the JSON written to info.json. You can set the parser for data and collections under data_config and collections_config.

These are the available parsers and default file extensions covered:

• csv (.csv)
• front-matter (.md, .mkd, .markdown, .html, .htm)
• json (.json)
• properties (.properties)
• toml (.toml)
• yaml (.yaml, .yml)

Functions are are supported with .js or .cjs files. Given file path, raw file content and an object with parsers and filters as arguments. The return value should be an object representing this file.

cloudcannon-reader exits in error if no suitable parser is found.

Development

Install dependencies:

$ npm i

Run tests:

$ npm test
$ npm run test:watch
$ npm run test:coverage

Lint code:

$ npm run lint

Link this package locally to test it on a site folder, then run it within your site folder:

$ npm link
$ cd ../my-ssg-site
$ cloudcannon-reader

License

ISC