{"_id":"@birdyboy18/contentful-hugo","_rev":"1-f7306ba15706b6d217bf7c3715cebec4","name":"@birdyboy18/contentful-hugo","dist-tags":{"latest":"1.6.0"},"versions":{"1.6.0":{"name":"@birdyboy18/contentful-hugo","version":"1.6.0","description":"Node module that pulls data from Contentful and turns it into markdown files for Hugo. Can be used with other Static Site Generators, but has some Hugo specific features.","main":"index.js","repository":{"typ":"git","url":"git+https://github.com/ModiiMedia/contentful-hugo.git"},"keywords":["hugo","contentful","blog","markdown","yaml","ssg","website","static-site-generator","jamstack","frontmatter","static-site"],"author":{"name":"Joshua Sosso","email":"josh@modiimedia.com","url":"https://www.modiimedia.com"},"contributors":[{"name":"Paul Bird","email":"paulbird1993@gmail.com","url":"http://paulbird.co"}],"scripts":{"test":"echo \"Error: no test specified\" && exit 1","lint":"eslint .","lint:fix":"eslint . --fix"},"license":"ISC","dependencies":{"@contentful/rich-text-plain-text-renderer":"^13.4.0","contentful":"^7.9.1","dotenv":"^7.0.0","js-yaml":"^3.13.1","json-to-pretty-yaml":"^1.2.2","mkdirp":"^0.5.1","yargs":"^15.0.2"},"bin":{"contentful-hugo":"./cli.js"},"devDependencies":{"eslint":"^6.6.0","eslint-config-prettier":"^6.7.0","eslint-config-standard":"^14.1.0","eslint-plugin-import":"^2.18.2","eslint-plugin-node":"^10.0.0","eslint-plugin-promise":"^4.2.1","eslint-plugin-standard":"^4.0.1","prettier":"^1.19.1"},"gitHead":"d2e9c52d52f5d5520d069ee301a7a5f776af24c0","bugs":{"url":"https://github.com/ModiiMedia/contentful-hugo/issues"},"homepage":"https://github.com/ModiiMedia/contentful-hugo#readme","_id":"@birdyboy18/contentful-hugo@1.6.0","_nodeVersion":"10.15.0","_npmVersion":"6.9.0","dist":{"integrity":"sha512-xmDfq5BQJNzT5GhiCogvUJHSD6X3mI53kyhYk+C0ZcQrf4DdV0bKHUWtWhpfuLkVFowaSWLxSHPLv7zGj0MelA==","shasum":"c2408815b59190895a9da815ca7a2e3516c82c07","tarball":"https://registry.npmjs.org/@birdyboy18/contentful-hugo/-/contentful-hugo-1.6.0.tgz","fileCount":11,"unpackedSize":63716,"npm-signature":"-----BEGIN PGP SIGNATURE-----\r\nVersion: OpenPGP.js v3.0.4\r\nComment: https://openpgpjs.org\r\n\r\nwsFcBAEBCAAQBQJeHchBCRA9TVsSAnZWagAAv40P/2dUQOOktEYfBnVxbrIl\nKxcDhApIhqS7rJmMdfdqaiopvyWYqx+kFhlAOHB6JRyTyrA4000qWNYdh8l1\n1fJRyXGywwl2A6qlMqs++L9Zuvwbsz0X7hngelfvhK0rcG9LC0GB+hdCdr8s\nf2+ATKWpCll6ykCseLNwV3Y4lQ+s6Ei+Iy5wRht1uL3kitqOFVqUtjao+Poc\nX7cQDWIC7cjLmfPqbh1NW1Yc86eVOArwJC3wU1/S/tSuOtX6078GKoeOdBXY\nwtQiD20JdaB71VhoTzOQdBnHfJH/3Q/KtaCt2MScPJuVC/qQwyMk7a+rEvL3\nF2cNfGztWZtZGeY7Ss1OzHLOmlSx5YFRacr/+iDg//EEzIiWB4fC+WNo+hNX\npyJQdjJkCbodKEDGgnwN9ec/6G8lvnE0quiToPZoyjA6/z5r9hCBA75+dnnR\nNpQWmfTlRuoVAs7neTfCzuozU0fRhKo9sZj2nIhplw7ybBQK22AYxvdZvpUy\nZT1MJle/i8m4pzWsNDU+u7s703r7PBrMjboDOgVAA5w1TAYgpCV1VZtcwwoN\nRjXdWQ5k3KNQ9nkPJDOwJWSmh7gypbshGq8P137Hx9aXGXZYcY51biH+qu6P\ncCJWchPGh/V+lt3jJSC5FRJB++DpS0tkvQCTxiwlOvkfSfYUtUXFZeKRFldy\nHI5s\r\n=arLO\r\n-----END PGP SIGNATURE-----\r\n","signatures":[{"keyid":"SHA256:jl3bwswu80PjjokCgh0o2w5c2U4LhQAE57gj9cz1kzA","sig":"MEYCIQCtUZiXuUjHiU/Z/jp+VChRtVvS1bqnOyrklHPZto2RRQIhAJtyGnmLJdB4SW0YStrKDNpWUTLReaeNwVn+I58bT4iJ"}]},"maintainers":[{"name":"birdyboy18","email":"paulbird1993@gmail.com"}],"_npmUser":{"name":"birdyboy18","email":"paulbird1993@gmail.com"},"directories":{},"_npmOperationalInternal":{"host":"s3://npm-registry-packages","tmp":"tmp/contentful-hugo_1.6.0_1579010113395_0.9745485738896729"},"_hasShrinkwrap":false}},"time":{"created":"2020-01-14T13:55:13.365Z","1.6.0":"2020-01-14T13:55:13.550Z","modified":"2022-04-04T18:55:59.157Z"},"maintainers":[{"name":"birdyboy18","email":"paulbird1993@gmail.com"}],"description":"Node module that pulls data from Contentful and turns it into markdown files for Hugo. Can be used with other Static Site Generators, but has some Hugo specific features.","homepage":"https://github.com/ModiiMedia/contentful-hugo#readme","keywords":["hugo","contentful","blog","markdown","yaml","ssg","website","static-site-generator","jamstack","frontmatter","static-site"],"repository":{"typ":"git","url":"git+https://github.com/ModiiMedia/contentful-hugo.git"},"contributors":[{"name":"Paul Bird","email":"paulbird1993@gmail.com","url":"http://paulbird.co"}],"author":{"name":"Joshua Sosso","email":"josh@modiimedia.com","url":"https://www.modiimedia.com"},"bugs":{"url":"https://github.com/ModiiMedia/contentful-hugo/issues"},"license":"ISC","readme":"# Contentful Hugo\n\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/281eacf31e864217953437f66b7e3a72)](https://www.codacy.com/app/joshmossas/contentful-hugo?utm_source=github.com&utm_medium=referral&utm_content=ModiiMedia/contentful-hugo&utm_campaign=Badge_Grade)\n\nThis is a simple Node.js CLI tool that pulls data from Contentful CMS and turns it into Markdown or YAML files for use with a static site generator. It can be used with any static site generator that uses Markdown with YAML frontmatter, but it has some features that are specific to [Hugo](https://gohugo.io).\n\n## Table of Contents\n\n-   [Prerequisites](#Prerequisites)\n-   [Installation](#Installation)\n-   [Usage](#Usage)\n-   [Configuration](#Configuration)\n-   [Expected Output](#Expected-Output)\n-   [Known Issues](#Known-Issues)\n\n## Prerequisites\n\nInstall [Node.js](https://nodejs.org)\n\n## Installation\n\nwith NPM\n\n```powershell\nnpm install contentful-hugo\n```\n\nwith Yarn\n\n```powershell\nyarn add contentful-hugo\n```\n\n## Usage\n\n### Terminal Commands\n\nComplete [configuration](#configuration) then run the following command(s) in the terminal\n\n#### When Installed Globally\n\n```powershell\ncontentful-hugo\n```\n\n#### When Installed Locally\n\n```powershell\nnpx contentful-hugo\n```\n\n### Optional Flags\n\n| flag      | aliases | description                                                                              |\n| --------- | ------- | ---------------------------------------------------------------------------------------- |\n| --preview | -P      | runs in preview mode, which pulls both published and unpublished entries from Contentful |\n\n#### Preview Mode Example\n\n```powershell\ncontentful-hugo --preview\n```\n\n### Example Package.json\n\n```JSON\n{\n  \"name\": \"my-hugo-project\",\n  \"scripts\": {\n    \"prestart\": \"contentful-hugo\",\n    \"start\": \"hugo server\",\n    \"prebuild\": \"contentful-hugo\",\n    \"build\": \"hugo --minify\"\n  }\n}\n```\n\nIn this example when you run `npm start` it will first use contentful-hugo to pull Contentful data then start hugo server. In the same way when you do the command `npm run build` it will first use contentful-hugo to pull Contentful data then run `hugo --minify` to build a minified version of your hugo site.\n\n### Error Messages\n\nTrying to use this package before completing configuration will return an error in the console\n\n![Environment Variables not set](https://raw.githubusercontent.com/ModiiMedia/contentful-hugo/master/images/environment-variables-missing.jpg)\n\n![Config file not found](https://raw.githubusercontent.com/ModiiMedia/contentful-hugo/master/images/config-file-not-found.jpg)\n\n## Configuration\n\n### Environment Variables\n\nBefore using you must first set the following environment variables. CONTENTFUL_SPACE, and CONTENTFUL_TOKEN. You can also add the CONTENTFUL_PREVIEW_TOKEN variable to use the --preview flag.\n\nThis can be done with a **.env** file in the root directory of your project.\n\n```TOML\nCONTENTFUL_SPACE = '<space-id>'\nCONTENTFUL_TOKEN = '<content-accessToken>'\n\n# optional but required for preview mode\nCONTENTFUL_PREVIEW_TOKEN = '<preview-accessToken>'\n```\n\nYou can also declare the environment variables in the command line\n\n**Powershell:**\n\n```powershell\n$env:CONTENTFUL_SPACE=\"<contentful_space_id>\"\n$env:CONTENTFUL_TOKEN=\"<contentful_acessToken>\"\n$env:CONTENTFUL_PREVIEW_TOKEN=\"<contentful_preview_accessToken>\"\n```\n\n**Bash:**\n\n```bash\nexport CONTENTFUL_SPACE=\"<contentful_space_id>\"\nexport CONTENTFUL_TOKEN=\"<contentful_accessToken>\"\nexport CONTENTFUL_PREVIEW_TOKEN=\"<contentful_preview_accessToken>\"\n```\n\n### Config File\n\nIn order to pull the data you want you will need to create a **contentful-settings.yaml** file in the root of your repository.\n\nExample **contentful-settings.yaml** file (see below for complete configuration options)\n\n```yaml\nsingleTypes:\n    # fetches only the most recently updated entry in a particular content type\n    # Generated file will be named after the fileName setting\n    - id: homepage\n      directory: /content/\n      fileName: _index\n      fileExtension: md\n\n      # this will generate a file named \"_index.md\" in the \"content\" directory\n    - id: siteSettings\n      directory: /data/\n      fileName: settings\n      fileExtension: yaml\n      # this will generate a file named settings.yaml in the \"data\" directory\n\nrepeatableTypes:\n    # fetches all the entries of a content type and places them in a directory.\n    # Generated files will be named after their Entry ID in Contentful.\n    - id: posts\n      directory: /content/posts/\n      fileExtension: md\n      mainContent: content\n\n    - id: seoFields\n      isHeadless: true\n      directory: /content/seo-fields/\n\n    - id: reviews\n      directory: /content/reviews/\n      mainContent: reviewBody\n\n    - id: staff\n      isHeadless: true\n      directory: /content/staff/\n```\n\n**Configuration Options**\n\n| field          | required                         | description                                                                                                                                          |\n| -------------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |\n| id             | required                         | contentful content type ID goes here                                                                                                                 |\n| directory      | required                         | directory where you want the file(s) to be generated (leading and trailing slashes required for the time being)                                      |\n| fileName       | required (single types only)     | name of the file generated                                                                                                                           |\n| fileExtension  | optional                         | can be \"md\", \"yml\", or \"yaml\" (defaults to \"md\")                                                                                                     |\n| isHeadless     | optional (repeatable types only) | turns all entries in a content type into headless leaf bundles (see [hugo docs](https://gohugo.io/content-management/page-bundles/#headless-bundle)) |\n| mainContent    | optional                         | field ID for field you want to be the main Markdown content. (Does not work with rich text fields)                                                   |\n| type           | optional                         | Allows a type to be set enabling a different layout to be used (see [hugo docs](https://gohugo.io/content-management/types/))                        |\n| resolveEntries | optional                         | Allows you to target entry fields that are references to other content and have them resolve to the given `to` key instead                           |\n\n## Expected Output\n\nFiles will be generated in the directory specified in the **contentful-settings.yaml** file. Front matter will be in YAML format. Files of single types will be named after fileName specified in the config file. Files of repeatable types will be named after their entry ID in Contenful, which makes it easy to link files together.\n\n### Default Date and Time Fields\n\nThe following fields will always appear in your frontmatter:\n\n```yaml\nupdated: # the last time this entry was update in Contentful\ncreatedAt: # when the entry was created in Contentful\ndate: # defaults to creation date unless you have a field with the id \"date\" then it get's overwritten\n```\n\n### Asset Information\n\nAssets like images and videos come with some extra information that makes it easy to implement things like alt text or layouts that rely on knowing the image dimensions. The fields are as follows:\n\n```yaml\nassetFieldName:\n    assetType: # indicates the asset type such as \"image\" \"video\" \"audio\" ect.\n    url: # url of the asset\n    title: # title of the asset written in Contentful\n    description: # description of the asset written in Contentful\n    width: # width of the asset (images only)\n    height: # height of the asset (images only )\n```\n\nIf you're using Hugo you can access the information like below:\n\n```html\n<img\n\tsrc=\"{{ .Params.assetFieldName.url }}\"\n\twidth=\"{{ .Params.assetFieldName.width }}\"\n/>\n```\n\nThis same information will also appear in asset arrays like a gallery:\n\n```yaml\nmyGallery:\n    - assetType: 'image/jpg'\n      url: '//link-to-image.jpg'\n      title: 'Image 1'\n      description: 'Image 1 Description'\n      width: 500\n      height: 500\n    - assetType: 'image/jpg'\n      url: '//link-to-image-2.jpg'\n      title: 'Image 2'\n      description: 'Image 2 Description'\n      width: 1920\n      height: 1080\n```\n\n### Entries\n\nLinked entries will include fields for it's id and it's content type id.\n\n```yaml\nlinkedEntry:\n    id: <contentful-entry-id>\n    typeId: <content-type-ID>\n\n#example with array of linked entries\n\nrelatedArticles:\n    - id: '41UFfIhszbS1kh95bomMj7'\n      typeId: 'articles'\n    - id: '85UFfIhsacS1kh71bpqMj7'\n      typeId: 'articles'\n```\n\nAll files are named after their entry id in Contentful making it easy to retrieve it using .Site.GetPage in Hugo\n\n```go\n{{ with .Site.GetPage \"<path-to-file>/<entry-id>.md\" }}\n    {{ .Title }}\n{{ end }}\n```\n\n#### Resolve Entries\n\nSometimes it might be desirable to override the above default behaviour. Instead you might like to be able to have it resolve to just one of the known fields in the entry. This becomes useful if you want to take advantage of Hugo's built in taxonomy features. Since Hugo taxonomies can't be an array of multiple key values. You can use this to get arround it.\n\nYou use it by declaring an array of key value pairs suggesting what entry field you want to target in the current content type and what it should resolve to when fetching the related entry.\n\n```yaml\nresolveEntries:\n  -\n    - target: <target-field>\n    - to: <linked-entry-field>\n\n# example in contentful-settings\nresolveEntries:\n  -\n    - target: productCategories\n    - to: slug\n\n# example above as seen in the front matter\nproductCategories:\n  - boots\n```\n\nThis works well for a page that would be responsible for listing products of one specific category.\n\nCategories could be a content model in Contentful which you can make and manage. \n\nA Product content model could then have a reference field that links to either number of these Categories. This way all categories are managed through contentful and you can gurantee better consistency and less errors.\n\n### Rich Text Fields\n\nA Rich text field will produce nested arrays mirroring the JSON structure that they have in the API. Each node will need to be looped through and produce HTML depending on the nodeType field.\n\n```yaml\nrichTextField:\n    - nodeType: 'paragraph'\n      data: {}\n      content:\n          - data: {}\n            marks: []\n            value: 'This is a simple paragraph.'\n            nodeType: 'text'\n    - nodeType: 'paragraph'\n      data: {}\n      content:\n          - data: {}\n            marks: []\n            value: 'This is a paragraph with '\n            nodeType: 'text'\n          - data: {}\n            marks:\n                - type: 'italic'\n            value: 'italicized text.'\n            nodeType: 'text'\n    - nodeType: 'embedded-asset-block'\n      data:\n          assetType: 'image/jpeg'\n          url: '//images.ctfassets.net/some-image-url.jpg'\n          title: 'Image title will appear here'\n          description: 'Image description will appear here'\n          width: 1920\n          height: 1080\n      content: []\n```\n\nIn addition a plaintext version of the field will be generated using the field ID appended with \"\\_plaintext\". This allows you to quickly fetch the text by itself without any of the other data. A simple use case would be using the plaintext output to automatically generate a meta description for a webpage.\n\n```yaml\nrichTextField_plaintext: 'This is a simple paragraph. This is a paragraph with italicized text.'\n```\n\n## Known Issues\n\nThese are some known issues.\n\n-   **Date & Time Field w/o Timezone**: Date fields that include time but do not have a specified timezone will have a timezone set based on whatever machine the script is run on. So using a date field in contentful with this setting could lead to unexpected results when formatting dates. Date fields that don't include time (ex: YYYY-MM-DD) are not effected by this.\n-   **Fetching Data Before Contentful CDN Updates**: Sometimes when triggering a build from a webhook, it won't always get the latest data. This is because it sometimes takes a couple seconds for the latest data to get distrubuted across Contentful's CDN. If you run into this issue it might be worth it to create a \"wait function\" just to delay fetching the data by a couple seconds. You could include it in the script you use contentful-hugo by doing something like the following `\"node wait.js && contentful-hugo\"`\n","readmeFilename":"readme.md"}