Contentful Hugo Extractor

This tool extracts all content from your Contentful space and makes it easily consumable by Hugo. You can run it locally or as part of a CI server like Travis.

Install

Go Install Method

Assuming Go (1.10 +) is installed as well as dep

go get -u "github.com/friends-of-hugo/contentful-export"
cd "$GOPATH/src/github.com/friends-of-hugo/contentful-export"
dep ensure
go install

Usage

contentful-hugo [Flags]

Flags:
 -space-id=value      "Id of the contentful space from which to extract content. If not present will default to an environment variable named `$CONTENTFUL_API_SPACE`"
 -api-token=value     "API Key used to authenticate with contentful for content delivery. If not present will default to an environment variable named `$CONTENTFUL_API_KEY`. The preview API key should be provided if -p is used."
 -config-file=value   "Path to the config TOML file to load. Defauls to `./extract-config.tml`"
 -p                   "If present, the contentful preview API will be used so that draft content will be included as part of the export."

The tool requires two parameters to work, a contentful space id and API key. These can be provided as command line flags or as environment variables

As environment vars...

export CONTENTFUL_API_KEY=YOUR-CONTENT-DELIVERY-API-ACCESS-TOKEN-HERE
export CONTENTFUL_API_SPACE=YOUR-SPACE-ID-HERE

contentful-hugo

As flags...

contentful-hugo -space-id=[YOUR-ID-HERE] -api-token=[YOUR-ACCESS-KEY-HERE] -config-file="./export-conf.toml"

Expected output

Contentful Hugo Extractor stores all content under the /content directory. For each content type, it makes a subdirectory. For each item, it creates a markdown file with the all properties in TOML format.

Special cases:

Items of type Homepage are stored as /content/_index
- Note that there can only be one such item
Fields named mainContent are used for the main content of the markdown file
File names are based on the ID of the item to make it easily referencable from related items (for the machine, not humans)

Configuration

Use the --config-file command line flag to provide the location of a TOML configuration to laod or ensure that there is a extract-config.toml file in the work directory of contentful-hugo

Configure YAML output

While the default output is in TOML format, it is also possible to output content in YAML format. Use the following key in your config file:

encoding = "yaml"

Configure Hugo Page Bundles

contentful-hugo will export each content type in contentful into its own content directory ./content/ and, since hugo treats each rootlevel content directory as a Section, you will end up having a hugo section for each contentful content type. Hugo allows you to provide Section level configuration for its Page Bundles by dropping a file named _index.md in the section's content directory. It is likely that you'll want to provide such configuration for some sections.

For example, let's say you need to make a section headless. Pretend that you have a contentful content type with the id question and you have some questions in your contentful content model which you intend to reference in a seperate FAQ page. After a contentful-hugo export, you might the following directory structure:

./
|   content
|   |   _index.md
|   |   question
|   |   |   12h3jk213n.md   //question 1
|   |   |   sdfer343sn.md   //question 2
|   |   page
|   |   |   sdf234dd32.md   //FAQ page - refs questions in its frontmatter
|   layouts
|   |   _default
|   |   |   single.html
|   |   page
|   |   |   single.html //question refs are loaded via .Site.GetPage

Without any further confuguration, hugo would generate a HTML file for the page using the ./layouts/page/single.html layout template but it would aslo generate HTML files for the questions using the ./layouts/_default/single.html layout template. To prevent this from happening you would create the following file under the path ./content/question/index.md:

+++
headless = true
+++

If you need this kind of configuration, the contentful-hugo export process can generate this index.md file for you. Simply provide the TOML to use in your config file:

encoding = "toml"
[section]
[section.question]
 headless = true

You can nest as many tables as you need under the [sections] and if the nested table name matches a contentful content type id than the configuration provided will be propagated to the section's index.md frontmatter.

bram-rongen/contentful-export