@cloudcannon/reader
v1.1.6
Published
Parses config, files and folder structures to create a JSON file with information about sites made with any static site generator.
Downloads
8,160
Readme
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
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.
To generate a JSON file at _cloudcannon/info.json
:
$ cloudcannon-reader
To print usage details:
$ cloudcannon-reader --help
Usage
$ cloudcannon-reader [options]
Options
--version Print the current version
--config, -c Use a specific configuration file
--output, -o Write to a different location than .
--quiet, -q Disable logging
Environment
CLOUDCANNON_CONFIG_PATH Use a specific configuration file
Examples
$ cloudcannon-reader --config "cloudcannon.dev.config.json"
$ cloudcannon-reader --output "public"
$ CLOUDCANNON_CONFIG_PATH=src/cloudcannon.config.js cloudcannon-reader
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:
The
path
is a reference to either:
- The top-most folder where the files in this data set are stored.
- The file containing the data.
Both options are relative to
source
.
The
parser
field should state which Parser you want to use to read the file or files in this data set.
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:
The
path
is the top-most folder where the files in this collection are stored. It is relative tosource
.
The
glob
is a string or array of strings containing patterns to filter the files parsed into this collection. Globs are relative topath
. Patterns are matched with picomatch. If set as an array, files only have to match one glob pattern to be parsed.glob: ['**/*.md', '**/*.html'] // All .md and .html files
This is used to find files instead of
path
, but path is still required as a base path for the collection.
'./src/*.md'
matches.md
files in thesrc
folder.'**/*.html'
matches.html
files in any folder or subfolder.['**/*.md', './pages/*.html']
matches.md
files in any folder, or.html
files in thepages
folder.
The
url
is used to build theurl
field for items in the collection. Similar to permalink in many SSGs. Can be a string or a function. Defaults to''
.Functions are are supported with
.js
or.cjs
files. Given file path, parsed file content and an object with filters, thebuildUrl
function and thecollection_config
entry as arguments. The return value should be the slash-prefixed URL string.url: (filePath, content, { filters, buildUrl, collectionConfig }) => { if (content.permalink) { // Returns a lower case permalink front matter field return filters.lowercase(content.permalink); } // Falls back to processing a default url template // Takes filePath, content, and a collections_config entry return buildUrl(filePath, content, { ...collectionsConfig, url: '/[slug]/' }); }
Strings are used as a template to build the URL. There are two types of placeholders available, file and data. Placeholders resulting in empty values are supported. Sequential slashes in URLs are condensed to one.
url: '/blog/{date|year}/[slug]/'
File placeholders are always available, and provided by
cloudcannon-reader
:
[path]
is the full path of the file, relative tosource
.[base_path]
is the path of the file excluding filename, relative to sitesource
.[slug]
is the filename, excluding extension. Is an empty string if this results in "index".[filename]
is the filename, including extension.[ext]
is the last extension, including.
.[relative_path]
is the full path of the file, relative to the collectionpath
.[relative_base_path]
is the path of the file excluding filename, relative to the collectionpath
.[full_slug]
is an alias for[relative_base_path]/[slug]
Data placeholders are populated from front matter or data values in the file, and support a number of filters:
{title}
is thetitle
from inside the file.{id}
is theid
from inside the file.{title|lowercase}
istitle
from inside the file, lower cased.{category|slugify}
iscategory
from inside the file, slugified.{tag|slugify|uppercase}
istag
from inside the file, slugified, then upper cased.{date|year}
isdate
from inside the file, with the 4-digit year extracted.{date|month}
isdate
from inside the file, with the 2-digit month extracted.{date|day}
isdate
from inside the file, with the 2-digit day extracted.
The
parser
field should state which Parser you want to use to read the files in this collection.parser: 'front-matter'
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