Skip to content

Commit

Permalink
Update README and improve logging
Browse files Browse the repository at this point in the history
  • Loading branch information
@rphillips-nz
rphillips-nz committed Dec 1, 2021
1 parent e5ccafa commit d831539
Show file tree
Hide file tree
Showing 12 changed files with 257 additions and 181 deletions.
2 changes: 1 addition & 1 deletion .eleventy.js
View file
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ module.exports = function (eleventyConfig, defaultOptions) {
log(`⭐️ Starting ${blue('eleventy-plugin-cloudcannon')}`);
const context = ctx.getAll();
const config = readConfig(context, options);
const info = getInfo(context, config, options);
const info = getInfo(context, config);
const json = stringifyJson(info);
log(`🏁 Generated ${bold('_cloudcannon/info.json')} ${green('successfully')}`);
return json;
Expand Down
10 changes: 9 additions & 1 deletion .eslintrc.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,15 @@
"eslint:recommended"
],
"rules": {
"quotes": ["warn", "single"]
"indent": ["warn", "tab"],
"no-else-return": ["warn"],
"guard-for-in": ["warn"],
"eqeqeq": ["warn"],
"no-self-compare": ["warn"],
"no-duplicate-imports": ["warn"],
"no-lonely-if": ["warn"],
"quotes": ["warn", "single"],
"semi": ["warn", "always"]
},
"env": {
"es6": true,
Expand Down
282 changes: 158 additions & 124 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,42 @@ An Eleventy (11ty) plugin that creates [CloudCannon](https://cloudcannon.com/) b
***

- [Installation](#installation)
- [Configuration](#configuration)
- [Plugin options](#plugin-options)
- [Site configuration](#site-configuration)
- [Manual installation](#manual-installation)
- [License](#license)

***

## Installation

CloudCannon automatically injects this plugin before your site is built. This means you'll get new
features and fixes as they are released. You can [disable this](#manual-installation) if you need
to maintain the plugin versioning manually.
**You don't have to install anything** when building on CloudCannon. This plugin is automatically
installed before your site is built. This gives you the latest support, new features, and fixes
as they are released.

If you use custom paths for your site, you'll need to pass them to the plugin, either one of:
Although **not recommended**, you can disable the automatic installation and install the plugin
manually.

- Returning from `.eleventy.js`
- Setting `eleventyConfig.cloudcannonOptions`
<details>
<summary>Manual installation steps</summary>

<blockquote>

When installing manually, you'll have to upgrade when new versions are released.
You could also follow these steps to debug an integration issue locally.

Start by enabling the "Manage eleventy-plugin-cloudcannon plugin manually" option in CloudCannon
for your site in *Site Settings / Build*.

```bash
npm install eleventy-plugin-cloudcannon --save
```

Add the following `addPlugin` call to your `.eleventy.js` file.
The second parameter is optional, and used to pass [plugin options](#plugin-options).

```javascript
const pluginCloudCannon = require('eleventy-plugin-cloudcannon');

module.exports = function (eleventyConfig) {
const config = {
pathPrefix: '/',
Expand All @@ -35,159 +52,176 @@ module.exports = function (eleventyConfig) {
data: '_my-custom-data',
layouts: '_layouts',
includes: '_my-includes'
},
markdownItOptions: {
html: true
}
};

// Either plugin looks here for plugin options
eleventyConfig.cloudcannonOptions = config;

// Or plugin looks at what you return for plugin options
eleventyConfig.addPlugin(pluginCloudCannon, config);
return config;
};
```

If you set your custom input path with the `--input` CLI option, CloudCannon reads it automatically.

## Plugin options

The options are either set on the `eleventyConfig.cloudcannonOptions` key within your
`.eleventy.js` file, or passed to the `addPlugin` call as a second argument if you are adding the
plugin manually.
</blockquote>
</details>

Should match the return value from your `.eleventy.js` (https://www.11ty.dev/docs/config/) file.
## Configuration

<details>
<summary><code>pathPrefix</code></summary>
This plugin uses a your `cloudcannon.config.*` configuration file as a base to generate
`_cloudcannon/info.json`.

> The `pathPrefix` setting your site uses. Defaults to: `'/'`
Configuration files must be in the same directory you run `npx @11ty/eleventy`. The first file
found is used, the files supported are:

</details>
- `cloudcannon.config.json`
- `cloudcannon.config.yaml`
- `cloudcannon.config.yml`
- `cloudcannon.config.js`
- `cloudcannon.config.cjs`

<details>
<summary><code>dir</code></summary>
Example content for `cloudcannon.config.cjs`:

> Custom paths your site uses. Defaults to:
>
> ```javascript
> {
> input: '.',
> data: '_data',
> includes: '_includes',
> layouts: '_includes'
> }
> ```
```javascript
module.exports = {
// Global CloudCannon configuration
_inputs: {
title: {
type: 'text',
comment: 'The title of your page.'
}
},
_select_data: {
colors: ['Red', 'Green', 'Blue']
},

</details>
// Base path to your site source files, same as input for Eleventy
source: 'src',

<details>
<summary><code>markdownItOptions</code></summary>
// The subpath your built output files are mounted at
base_url: '/documentation',

> Options passed to markdown-it. Defaults to `{ html: true }`.
// Populates collections for navigation and metadata in the editor
collections_config: {
people: {
// Base path for files in this collection, relative to source
path: 'content/people',

</details>
// Whether this collection produces output files or not
output: true

## Site configuration
This plugin reads data from `cloudcannon` if available (i.e. `_data/cloudcannon.json` or
`_data/cloudcannon.js`).
Details on each property here are listed in the relevant parts of the
[CloudCannon documentation](https://cloudcannon.com/documentation/).
The following is an empty template as an example.
```json
{
"timezone": "",
"collections": {
"projects": {
"path": "",
"name": "",
"title": "",
"output": false,
"_sort_key": "",
"_subtext_key": "",
"_image_key": "",
"_image_size": "",
"_singular_name": "",
"_singular_key": "",
"_disable_add": false,
"_icon": "",
"_enabled_editors": null,
"_add_options": []
// Collection-level configuration
name: 'Personnel',
_enabled_editors: ['data']
},
posts: {
path: '_posts',
output: true
},
pages: {
name: 'Main pages'
}
},
"_comments": {},
"_options": {},
"_editor": {},
"_collection_groups": null,
"_source_editor": {},
"_array_structures": {},
"_enabled_editors": null,
"_select_data": {}
}

// Generates the data for select and multiselect inputs matching these names
data_config: {
// Populates data with authors from an data file with the matching name
authors: true,
offices: true
},

paths: {
// The default location for newly uploaded files, relative to source
uploads: 'assets/uploads',

// The path to site data files, relative to source
data: 'data', // defaults to _data

// The path to site layout files, relative to source
layouts: '_layouts', // defaults to _includes

// The path to site include files, relative to source
includes: '_partials' // defaults to _includes
}
};
```

## Manual installation
See the [CloudCannon documentation](https://cloudcannon.com/documentation/) for more information
on the available features you can configure.

Manually managing this plugin means you'll have to upgrade when new versions are released. You can
also follow these steps to try it or debug locally.
## Plugin options

<details>
<summary>Manual installation steps</summary>
Configuration is set in `cloudcannon.config.*`, but the plugin also automatically
reads the following from Eleventy if unset:

<blockquote>
- `paths` from `dir` in `.eleventy.js` options
- `base_url` from `pathPrefix` in `.eleventy.js` options
- `source` from the `--input` CLI option or `dir.input` in `.eleventy.js` options

Start by enabling the "Manage eleventy-plugin-cloudcannon plugin manually" option in CloudCannon
for your site in *Site Settings / Build*.
These options match Eleventy's [configuration format](https://www.11ty.dev/docs/config/) and are
set in one of three ways:

```bash
npm install eleventy-plugin-cloudcannon --save
```
<details>
<summary>Returning from <code>.eleventy.js</code> with automatic installation</summary>

Add the following `addPlugin` call to the `module.exports` function in your `.eleventy.js` file:
**Requires automatic installation**.

```javascript
const pluginCloudCannon = require('eleventy-plugin-cloudcannon');
> ```javascript
> module.exports = function (eleventyConfig) {
> return {
> pathPrefix: '/',
> dir: {
> input: '.',
> data: '_my-custom-data',
> layouts: '_layouts',
> includes: '_my-includes'
> }
> };
> };
> ```
module.exports = function (eleventyConfig) {
eleventyConfig.addPlugin(pluginCloudCannon);
};
```
</details>
If you use custom paths for your site, pass them to the plugin as well:
<details>
<summary>Setting <code>eleventyConfig.cloudcannonOptions</code></summary>
```javascript
const pluginCloudCannon = require('eleventy-plugin-cloudcannon');
**Requires automatic installation or needs to be before the call to `addPlugin`**.
module.exports = function (eleventyConfig) {
const config = {
pathPrefix: '/',
dir: {
input: '.',
data: '_my-custom-data',
layouts: '_layouts',
includes: '_my-includes'
}
};
> ```javascript
> module.exports = function (eleventyConfig) {
> eleventyConfig.cloudcannonOptions = {
> pathPrefix: '/',
> dir: {
> input: '.',
> data: '_my-custom-data',
> layouts: '_layouts',
> includes: '_my-includes'
> }
> };
> };
> ```
eleventyConfig.addPlugin(pluginCloudCannon, config);
return config;
};
```
</details>
Disabling the automatic injection prevents the `info.json` template being copied. In order to
retain this, add the following to your `.cloudcannon/prebuild` build hook:
<details>
<summary>Through <code>addPlugin</code> with manual installation</summary>
```bash
rm -rf cloudcannon
cp -R node_modules/eleventy-plugin-cloudcannon/cloudcannon .
```
> ```javascript
> const pluginCloudCannon = require('eleventy-plugin-cloudcannon');
>
> module.exports = function (eleventyConfig) {
> const config = {
> pathPrefix: '/',
> dir: {
> input: '.',
> data: '_my-custom-data',
> layouts: '_layouts',
> includes: '_my-includes'
> }
> };
>
> eleventyConfig.addPlugin(pluginCloudCannon, config);
> return config;
> };
> ```
</blockquote>
</details>
## License
Expand Down
15 changes: 0 additions & 15 deletions integration-tests/1.0.0-beta.8/site/_data/cloudcannon.json
View file

This file was deleted.

Loading

0 comments on commit d831539

Please sign in to comment.