This repository has been archived by the owner on Nov 26, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 32
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #20 from contentful-labs/refactor
Refactor the plugin, add docs and test coverage
- Loading branch information
Showing
31 changed files
with
1,635 additions
and
357 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,3 +1,4 @@ | ||
| [*.js] | ||
| indent_style = space | ||
| indent_size = 2 | ||
| insert_final_newline = true |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| { | ||
| "extends": "standard" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1 +1,4 @@ | ||
| node_modules | ||
| .vscode | ||
| test/build | ||
| .nyc_output |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| .*.swp | ||
| ._* | ||
| .DS_Store | ||
| .git | ||
| .hg | ||
| .npmrc | ||
| .lock-wscript | ||
| .svn | ||
| .wafpickle-* | ||
| config.gypi | ||
| CVS | ||
| npm-debug.log | ||
| *.spec.js | ||
| test | ||
| .vscode | ||
| .nyc_output |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,20 @@ | ||
| sudo: false | ||
| language: node_js | ||
| notifications: | ||
| email: false | ||
| node_js: | ||
| - '6' | ||
| - '5' | ||
| - '4' | ||
| before_install: | ||
| - npm i -g npm@latest | ||
| before_script: | ||
| - npm prune | ||
| after_success: | ||
| - 'curl -Lo travis_after_all.py https://git.io/travis_after_all' | ||
| - python travis_after_all.py | ||
| - export $(cat .to_export_back) &> /dev/null | ||
| - npm run semantic-release | ||
| branches: | ||
| except: | ||
| - /^v\d+\.\d+\.\d+$/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,178 +1,136 @@ | ||
| # contentful-metalsmith | ||
| [](https://travis-ci.org/contentful-labs/contentful-metalsmith) | ||
| [](https://coveralls.io/github/contentful-labs/contentful-metalsmith?branch=refactor) | ||
|
|
||
| A Metalsmith's plugin to get content from [Contentful](http://www.contentful.com) | ||
| A Metalsmith' plugin to generate files using content from [Contentful](http://www.contentful.com) | ||
|
|
||
| [](http://unmaintained.tech/) | ||
| ## About | ||
|
|
||
| ## Deprecation notice | ||
| This plugin for [metalsmith](http://www.metalsmith.io) allows you to build a static site using the data stored at [Contentful](http://www.contentful.com). It is built on top of the [Contentful JavaScript Client](https://github.com/contentful/contentful.js). | ||
|
|
||
| This project has not been maintained for some time and won't be maintained moving forward. | ||
| ## Getting started | ||
|
|
||
| While it might work with some older versions of metalsmith, it's known not to work with more recent versions. | ||
| ### Install | ||
|
|
||
| ## About | ||
| ```bash | ||
| $ npm install contentful-metalsmith | ||
| ``` | ||
|
|
||
| This plugin for [metalsmith](http://www.metalsmith.io) allows you to build a static site using the data stored at [Contentful](http://www.contentful.com). This | ||
| plugin is built on top of the [Contentful JavaScript Client](https://github.com/contentful/contentful.js). | ||
| ### Configure required globals | ||
|
|
||
| ## TL;DR | ||
| When you use metalsmith using the [cli](https://github.com/metalsmith/metalsmith#cli) edit your `metalsmith.json` and add `contentful-metalsmith` in the plugins section. | ||
|
|
||
| 1. Install it | ||
| ```javascript | ||
| // metalsmith.json | ||
|
|
||
| ```javascript | ||
| $ npm install contentful-metalsmith | ||
| ``` | ||
| 2. Configure it (example for [metalsmith CLI](https://github.com/segmentio/metalsmith#cli)) | ||
| { | ||
| "source": "src", | ||
| "destination": "build", | ||
| "plugins": { | ||
| "contentful-metalsmith": { | ||
| "access_token": "YOUR_CONTENTFUL_ACCESS_TOKEN", | ||
| "space_id": "YOUR_CONTENTFUL_SPACE_ID" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ```javascript | ||
| $ vim metalsmith.json | ||
| When you use the [JavaScript Api](https://github.com/metalsmith/metalsmith#api) add `contentful-metalsmith` to the used plugins. | ||
|
|
||
| ---- | ||
| ```javascript | ||
| metalsmith.source('src') | ||
| metalsmith.destination('build') | ||
|
|
||
| { | ||
| "source": "src", | ||
| "destination": "build", | ||
| "plugins": { | ||
| ..., | ||
| "contentful-metalsmith": { | ||
| "accessToken" : "YOUR_CONTENTFUL_ACCESS_TOKEN" | ||
| }, | ||
| ... | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| 3. Create a source file | ||
|
|
||
| ```html | ||
|
|
||
| --- | ||
| title: OMG metalsmith-contentful | ||
| contentful: | ||
| space_id: AN_SPACE_ID | ||
| template: entries.html | ||
| --- | ||
|
|
||
| [OPTIONAL CONTENT] | ||
| ``` | ||
|
|
||
| 4. Create the template (handlebarsjs on this case) | ||
|
|
||
| ```html | ||
| <!doctype html> | ||
|
|
||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="utf-8"> | ||
|
|
||
| <title>Contentful-metalsmith plugin example</title> | ||
| <meta name="description" content="No description"> | ||
| <meta name="author" content="Contentful"> | ||
|
|
||
| </head> | ||
|
|
||
| <body> | ||
|
|
||
| {{contents}} | ||
| <table> | ||
| <thead> | ||
| <tr> | ||
| <th>Type</th> | ||
| <th>Id</th> | ||
| <th>Updated</th> | ||
| </tr> | ||
| </thead> | ||
| <tbody> | ||
| {{#each contentful.entries}} | ||
| <tr> | ||
| <td> | ||
| {{this.data.sys.contentType.sys.id}} | ||
| </td> | ||
| <td> | ||
| {{this.data.sys.id}} | ||
| </td> | ||
| <td> | ||
| {{this.data.sys.updatedAt}} | ||
| </td> | ||
| </tr> | ||
| {{/each}} | ||
| </tbody> | ||
| </table> | ||
| </body> | ||
| </html> | ||
| ``` | ||
|
|
||
| 5. Enjoy | ||
|
|
||
| # Usage | ||
|
|
||
| The first thing that you have to do to use this plugin is to install and configure it (see the TL;DR section for that). Once you have done this you can create and setup source files to fetch data from [Contentful](http://www.contentful.com). | ||
|
|
||
| ## Setup a source file | ||
|
|
||
| To fetch data from [Contentful](http://www.contentful.com) you have to include some extra metadata in a metalsmith source file. The available configuration parameters are the following: | ||
|
|
||
| * `space_id` (**required**), the id of the space from where you want to get entries. | ||
| * `entry_template` (optional), the template that will be used to render each individual entry. | ||
| * `filter` (optional), this parameter has to include some of the [filtering options](https://www.contentful.com/developers/documentation/content-delivery-api/http/#search) offered by the [Contentful's Content Delivery API](https://www.contentful.com/developers/documentation/content-delivery-api/). | ||
|
|
||
| All this parameters have to be nested under the key `contentful`. | ||
|
|
||
|
|
||
| An example: | ||
|
|
||
| ```yaml | ||
|
|
||
| --- | ||
| title: OMG metalsmith-contentful | ||
| contentful: | ||
| space_id: cfexampleapi | ||
| content_type: cat | ||
| filter: | ||
| sys.id[in]: 'finn,jake' | ||
| entry_template: entry.html | ||
| template: example.html | ||
| --- | ||
| metalsmith.use(require('contentful-metalsmith')({ 'access_token' : 'YOUR_CONTENTFUL_ACCESS_TOKEN' })) | ||
| ``` | ||
|
|
||
| ## Using the fetched entries on the templates | ||
| **Global parameters:** | ||
|
|
||
| - `acccess_token` | ||
| - `space_id` | ||
|
|
||
| You can find the `access_token` and `space_id` in your [app](https://app.contentful.com) at `APIs -> Content delivery API Keys`. | ||
|
|
||
| We have to make a distinction between two types of templates: | ||
| ------------------------------ | ||
|
|
||
| * The template rendered for the source file. | ||
| * And the template rendered for each individual entry. | ||
| To read more on all global parameters and settings read the [global settings documentation](./docs/global-settings.md). | ||
|
|
||
| In the context of the template rendered for the source file you will have access to a property named `contentful`. This property holds the following properties: | ||
| ### Create files based on the files defined in your source folder | ||
|
|
||
| * `entries`, an array with all the fetched entries. The structure of each of this entry objects will be the same as the explained below for the entry template. | ||
| * `contentTypes`, an object with the id of the fetched [contentTypes](https://www.contentful.com/developers/documentation/content-delivery-api/http/#content-types) as keys. Under each key there will be an array with all the entries belonging to that particular contentType. | ||
| We're considering that you use [metalsmith-layouts](https://github.com/superwolff/metalsmith-layouts) for file rendering. That for the `layout` key is used for rendered source files and child templates. | ||
|
|
||
| In the context of the template rendered for an individual entry you will have access to the following properties under the property `data`: | ||
| *`source/posts.html`* | ||
|
|
||
| * `id`, a shortcut to the entry's id. | ||
| * `contentType`, a shortcut to the entry's contentType. | ||
| * `data`, the body of the entry as returned by [Contentful's Content Delivery API](https://www.contentful.com/developers/documentation/content-delivery-api/) | ||
| ```markdown | ||
| --- | ||
| title: metalsmith-contentful file | ||
| contentful: | ||
| content_type: post | ||
| layout: post.html | ||
| layout: posts.html | ||
| --- | ||
|
|
||
| ## Entry filename config | ||
| Following from the example above there are some options to help with getting the structure output: | ||
| ```yaml | ||
| --- | ||
| title: OMG metalsmith-contentful | ||
| contentful: | ||
| space_id: cfexampleapi | ||
| content_type: cat | ||
| entry_template: entry.html | ||
| entry_filename_pattern: :sys.locale/:fields.slug | ||
| permalink_style: true | ||
| use_template_extension: true | ||
| template: example.html | ||
| --- | ||
| [OPTIONAL CONTENT] | ||
| ``` | ||
|
|
||
| * `entry_filename_pattern` takes a pattern similar to the permalink plugin where you can reference Contentful system and user entered fields, prefixed `sys.` and `field.` respectively. | ||
| * `permalink_style` will name a directory with the last part of the pattern and add an `index.html` for the file content. e.g. `my/file/path.html` vs. `my/file/path/index.html`. | ||
| * `use_template_extension` is only required if you want the extension to match the template extension. `.html` is used by default. | ||
| *`layouts/posts.html`* | ||
|
|
||
| ```html | ||
| <!doctype html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="utf-8"> | ||
| <title>{{title}}</title> | ||
| <meta name="description" content="No description"> | ||
| <meta name="author" content="Contentful"> | ||
| <link rel="stylesheet" href="scss/style.css?v=1.0"> | ||
| </head> | ||
| <body> | ||
| <ul> | ||
| <!-- available data fetched from contentful --> | ||
| {{#each data.entries }} | ||
| <li> | ||
| <h2>{{fields.title}}</h2> | ||
| <p>{{fields.description}}</p> | ||
| <p><a href="{{_fileName}}">Read more</a></p> | ||
| </li> | ||
| {{/each}} | ||
| </ul> | ||
| {{contents}} | ||
| </body> | ||
| </html> | ||
| ``` | ||
|
|
||
| *`layouts/post.html`* | ||
|
|
||
| ```html | ||
| <!doctype html> | ||
| <html lang="en"> | ||
| <head> | ||
| <meta charset="utf-8"> | ||
| <title>{{data.fields.title}}</title> | ||
| <meta name="description" content="No description"> | ||
| <meta name="author" content="Contentful"> | ||
| <link rel="stylesheet" href="scss/style.css?v=1.0"> | ||
| </head> | ||
| <body> | ||
| <h1>{{data.fields.title}}<h1> | ||
| <p>{{data.fields.description}}</p> | ||
|
|
||
| {{contents}} | ||
| </body> | ||
| </html> | ||
| ``` | ||
|
|
||
| **This example will** | ||
|
|
||
| - render `posts.html` providing data of the entries of content type `post` | ||
| - render several single files with the template `post.html` providing the data of a particular post | ||
|
|
||
| ------------------------------ | ||
|
|
||
| To read more on source file parameters and settings read the [source file documentation](./docs/source-file-settings.md). | ||
|
|
||
| # License | ||
| MIT | ||
|
|
||
| MIT |
Oops, something went wrong.