![\"Markdown](\"/img/widgets-markdown.png\")
This guide will help you get started using Netlify CMS with NextJS.
\nLet's repeat some of the basics of setting up a simple NextJS project (check out nextjs.org/learn for a more detailed version).
\n# Create new directory and navigate into it\nmkdir awesome-kitties\ncd awesome-kitties\n\n# Initialize a new project\nnpm init -y\n\n# Install required dependencies\nnpm install --save react react-dom next\n\n# Install webpack loader for Markdown (Use version 3+)\nnpm install --save-dev frontmatter-markdown-loader\n\n# Create folder for pages (default for NextJS), and add a index file\nmkdir pages\ntouch pages/index.js\n\n# Create a folder for content, and a markdown file:\nmkdir content\ntouch content/home.md\n\n# Create a folder for static assets\nmkdir publicNext, we need to add some modifications to our package.json file to make it easier to run and deploy our new site:
{\n \"scripts\": {\n \"dev\": \"next\",\n \"build\": \"next build\",\n \"start\": \"next start\",\n \"export\": \"npm run build && next export\"\n }\n}There is a lot of different ways to create and display Markdown content, but to make this as easy as possible we'll be using a webpack-loader that enables us to load markdown files directly in our React components (frontmatter-markdown-loader).
\nAdd the following content to your content/home.md file:
---\ntitle: Awesome kitties\ndate: 2019-03-17T19:31:20.591Z\ncats:\n - description: 'Maru is a Scottish Fold from Japan, and he loves boxes.'\n name: Maru (まる)\n - description: Lil Bub is an American celebrity cat known for her unique appearance.\n name: Lil Bub\n - description: 'Grumpy cat is an American celebrity cat known for her grumpy appearance.'\n name: Grumpy cat (Tardar Sauce)\n---\nWelcome to my awesome page about cats of the internet.\n\nThis page is built with NextJS, and content is managed in Netlify CMSNext, we need to tell webpack how to load Markdown files. Create a new next.config.js file at the root of your project with the following content:
module.exports = {\n webpack: (cfg) => {\n cfg.module.rules.push(\n {\n test: /\\.md$/,\n loader: 'frontmatter-markdown-loader',\n options: { mode: ['react-component'] }\n }\n )\n return cfg;\n }\n}Almost there! The last thing we need to do is to add some content our pages/index.js file. With a little help of our webpack loader, we can now easilly import Markdown files:
import Head from \"next/head\"\nimport { Component } from 'react'\nimport { attributes, react as HomeContent } from '../content/home.md';\n\nexport default class Home extends Component {\n render() {\n let { title, cats } = attributes;\n return (\n <>\n <Head>\n <script src=\"https://identity.netlify.com/v1/netlify-identity-widget.js\"></script>\n </Head>\n <article>\n <h1>{title}</h1>\n <HomeContent />\n <ul>\n {cats.map((cat, k) => (\n <li key={k}>\n <h2>{cat.name}</h2>\n <p>{cat.description}</p>\n </li>\n ))}\n </ul>\n </article>\n </>\n )\n }\n}Great! We now have a page that displays content from our Markdown file. Go ahead and start your development server to test if everything is working:
\nnpm run devThere are many different ways to add Netlify CMS to your project. The easiest is probably just to embed it from a CDN, and that's exactly what we're gonna do. To avoid making this guide too complicated, we're just going to add Netlify into a subfolder inside the /public directory (which is just served as static files by Next):
# Create and navigate into static/admin folder\nmkdir public/admin\ncd public/admin\n\n# Create index.html and config.yml file\ntouch index.html\ntouch config.ymlPaste HTML for Netlify CMS into your public/admin/index.html file (check out the Add Netlify To Your Site section for more information)
<!doctype html>\n<html>\n<head>\n <meta charset=\"utf-8\" />\n <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\" />\n <title>Content Manager</title>\n <script src=\"https://identity.netlify.com/v1/netlify-identity-widget.js\"></script>\n</head>\n<body>\n <!-- Include the script that builds the page and powers Netlify CMS -->\n <script src=\"https://unpkg.com/netlify-cms@2.9.7/dist/netlify-cms.js\"></script>\n</body>\n</html>Notice that we also added the identity widget. This allows sign up when the project is hosted at Netlify.
\nPaste the following configuration into your public/admin/config.yml file:
backend:\n name: git-gateway\n branch: master\nmedia_folder: public/img\npublic_folder: img\ncollections:\n - name: \"pages\"\n label: \"Pages\"\n files:\n - label: \"Home\"\n name: \"home\"\n file: \"content/home.md\"\n fields:\n - { label: \"Title\", name: \"title\", widget: \"string\"}\n - { label: \"Publish Date\", name: \"date\", widget: \"datetime\" }\n - { label: \"Body\", name: \"body\", widget: \"markdown\"}\n - label: 'Cats'\n name: \"cats\"\n widget: list\n fields:\n - { label: \"Name\", name: \"name\", widget: \"string\"}\n - { label: \"Description\", name: \"description\", widget: \"text\"}Awesome! Netlify CMS should now be available at localhost:3000/admin/index.html.\nUnfortunately we can't edit our content just yet. First we need to move our code into a git repository, and create a new Netlify site.
Tip: If you want to test changes made to your config.yml file locally, swap out \"git-gateway\" with \"test-repo\" and navigate to localhost:3000/admin/index.html to view Netlify CMS locally (you can't make changes or read actual content from Git this way, but it's great to verify how things will look).
Create a new repository at GitHub (or one of the other supported git services) and follow the instructions on how to push existing files into your new respository.
\nNow is probably also a good time to add a .gitignore file:
.next/\nnode_modules/\n/npm-debug.log\n.DS_Store\nout/When your project is under version control, go to Netlify and select \"New Site from Git\".\nSelect GitHub (or whatever service you used in the previous step), and the repository you just pushed to.
\nUnder the final step (Build options, and deploy!), make sure you enter the following:
\n| Field | \nValue | \n
|---|---|
| Build command | \nnpm run export | \n
| Publish directory | \nout | \n
Netlify's Identity and Git Gateway services allow you to manage CMS admin users for your site without requiring them to have an account with your Git host or commit access on your repo. From your site dashboard on Netlify:
\nGreat job - you did it!\nOpen your new page via the new Netlify URL, and navigate to /admin. If you did everything correct in the previous step, you should now be able to sign up for an account, and log in.
Tip: Signing up with an external provider is the easiest. If you want to sign up by email, you'll have to set up a redirect in your index.js page (which we won't be covering in this guide). For more information, have a look at the Add To Your Site section.
\nCongratulations - you can finally manage your new list of cats!
"},"nav":{"group":[{"fieldValue":"backends","edges":[{"node":{"fields":{"slug":"/docs/backends-overview/"},"frontmatter":{"title":"Overview","group":"backends"},"tableOfContents":""}},{"node":{"fields":{"slug":"/docs/git-gateway-backend/"},"frontmatter":{"title":"Git Gateway","group":"backends"},"tableOfContents":"Components structure and Workflows
\nEditorial Workflow implementation
\ncreate-nuxt-appregisterPreviewStyleThe boolean widget translates a toggle switch input to a true/false value.
\nbooleanOptions:
\ndefault: accepts true or false; defaults to false when required is set to falseExample:
\n- {label: \"Draft\", name: \"draft\", widget: \"boolean\", default: true}The code widget provides a code editor (powered by Codemirror) with optional syntax awareness. Can output the raw code value or an object with the selected language and the raw code value.
\ncodeOptions:
\ndefault_language: optional; default language to useallow_language_selection: optional; defaults to false: allows syntax to be changedkeys: optional; sets key names for code and lang if outputting an object; defaults to { code: 'code', lang: 'lang' }output_code_only: set to true to output the string value only, defaults to falseExample:
\n- label: 'Code'\nname: 'code'\nwidget: 'code'Deprecation notice: the date widget has been deprecated and will be removed in the next major release. Please use the datetime widget instead.
\nThe date widget translates a date picker input to a date string. For saving date and time together, use the datetime widget.
\ndateOptions:
\ndefault: accepts a date string, or an empty string to accept blank input; otherwise defaults to current dateformat: optional; accepts Moment.js tokens; defaults to raw Date object (if supported by output format)dateFormat: optional; boolean or Moment.js tokens. If true use default locale format.timeFormat: optional; boolean or Moment.js tokens. If true use default locale format, false hides time-picker. Defaults to false.Example:
\n- label: 'Birthdate'\nname: 'birthdate'\nwidget: 'date'\ndefault: ''\nformat: 'MMM Do YY'The datetime widget translates a datetime picker to a datetime string. For saving the date only, use the date widget.
\ndatetimeOptions:
\ndefault: accepts a datetime string, or an empty string to accept blank input; otherwise defaults to current datetimeformat: sets storage format; accepts Moment.js tokens; defaults to raw Date object (if supported by output format)dateFormat: sets date display format in UI; boolean or Moment.js tokens. If true use default locale format.timeFormat: sets time display format in UI; boolean or Moment.js tokens. If true use default locale format, false hides time-picker.Example:
\n- label: \"Start time\"\n name: \"start\"\n widget: \"datetime\"\n default: \"\"\n dateFormat: \"DD.MM.YYYY\" # e.g. 24.12.2021\n timeFormat: \"HH:mm\" # e.g. 21:07\n format: \"LLL\"The file widget allows editors to upload a file or select an existing one from the media library. The path to the file will be saved to the field as a string.
\nfileOptions:
\ndefault: accepts a file path string; defaults to nullmedia_library: media library settings to apply when a media library is opened by the\ncurrent widgetallow_multiple: (default: true) when set to false, prevents multiple selection for any media library extension, but must be supported by the extension in useconfig: a configuration object that will be passed directly to the media library being\nused - available options are determined by the libraryExample:
\n- label: \"Manual PDF\"\n name: \"manual_pdf\"\n widget: \"file\"\n default: \"/uploads/general-manual.pdf\"\n media_library:\n config:\n multiple: trueHidden widgets do not display in the UI. In folder collections that allow users to create new items, you will often want to set a default for hidden fields, so they will be set without requiring an input.
\nhiddenOptions:
\ndefault: accepts any valid data type; recommended for collections that allow adding new itemsExample:
\n- {label: \"Layout\", name: \"layout\", widget: \"hidden\", default: \"blog\"}The image widget allows editors to upload an image or select an existing one from the media library. The path to the image file will be saved to the field as a string.
\nimageOptions:
\ndefault: accepts a file path string; defaults to nullmedia_library: media library settings to apply when a media library is opened by the\ncurrent widgetallow_multiple: (default: true) when set to false, prevents multiple selection for any media library extension, but must be supported by the extension in useconfig: a configuration object that will be passed directly to the media library being\nused - available options are determined by the libraryExample:
\n- label: \"Featured Image\"\n name: \"thumbnail\"\n widget: \"image\"\n default: \"/uploads/chocolate-dogecoin.jpg\"\n media_library:\n config:\n multiple: trueThe list widget allows you to create a repeatable item in the UI which saves as a list of widget values. map a user-provided string with a comma delimiter into a list. You can choose any widget as a child of a list widget—even other lists.
\nlistfields is specified, field containing a repeatable child widget, with controls for adding, deleting, and re-ordering the repeated widgets; if unspecified, a text input for entering comma-separated valuesOptions:
\ndefault: if fields is specified, declare defaults on the child widgets; if not, you may specify a list of strings to populate the text fieldallow_add: if added and labeled false, button to add additional widgets disappearscollapsed: if added and labeled false, the list widget's content does not collapse by defaultfield: a single widget field to be repeatedfields: a nested list of multiple widget fields to be included in each repeatable iterationExample (field/fields not specified):
- label: \"Tags\"\n name: \"tags\"\n widget: \"list\"\n default: [\"news\"]Example (allow_add marked false):
- label: \"Tags\"\n name: \"tags\"\n widget: \"list\"\n allow_add: false\n default: [\"news\"]Example (with field):
- label: \"Gallery\"\n name: \"galleryImages\"\n widget: \"list\"\n field: {label: Image, name: image, widget: image}Example (with fields):
- label: \"Testimonials\"\n name: \"testimonials\"\n widget: \"list\"\n fields:\n - {label: Quote, name: quote, widget: string, default: \"Everything is awesome!\"}\n - label: Author\n name: author\n widget: object\n fields:\n - {label: Name, name: name, widget: string, default: \"Emmet\"}\n - {label: Avatar, name: avatar, widget: image, default: \"/img/emmet.jpg\"}Example (collapsed marked false):
- label: \"Testimonials\"\n name: \"testimonials\"\n collapsed: false\n widget: \"list\"\n fields:\n - {label: Quote, name: quote, widget: string, default: \"Everything is awesome!\"}\n - {label: Author, name: author, widget: string }The map widget allows you to edit spatial data using an interactive map. Spatial data is saved as a GeoJSON string in WGS84 projection and is limited to a single geometry.
\nmapOptions:
\ndecimals: accepts a number to specify precision of saved coordinates; defaults to 7 decimalsdefault: accepts a GeoJSON string containing a single geometry; defaults to an empty stringtype: accepts one string value of Point, LineString or Polygon; defaults to PointExample:
\n- {label: \"Location\", name: \"location\", widget: \"map\" }The markdown widget provides a full fledged text editor - which is based on slate - that allows users to format text with features such as headings and blockquotes. Users are also allowed to write in markdown by simply flipping a switch.
\nPlease note: If you want to use your markdown editor to fill a markdown file contents after its frontmatter, you'll have to name the field body so the CMS recognizes it and saves the file accordingly.
markdownOptions:
\ndefault: accepts markdown contentminimal: accepts a boolean value, false by default. Sets the widget height to minimum possible.buttons: an array of strings representing the formatting buttons to display (all shown by default). Buttons include: bold, italic, code, link, heading-one, heading-two, heading-three, heading-four, heading-five, heading-six, quote, bulleted-list, and numbered-list.editorComponents: an array of strings representing the names of editor components to display (all shown by default). The image and code-block editor components are included with Netlify CMS by default, but others may be created and registered.Example:
\n- { label: 'Blog post content', name: 'body', widget: 'markdown' }This would render as:
\n
Please note: The markdown widget outputs a raw markdown string. Your static site generator may or may not render the markdown to HTML automatically. Consult with your static site generator's documentation for more information about rendering markdown.
"}},{"node":{"frontmatter":{"title":"number","label":"Number"},"html":"The number widget uses an HTML number input, saving the value as a string, integer, or floating point number.
\nnumbervalueType optionOptions:
\ndefault: accepts string or number value; defaults to empty stringvalueType: accepts int or float; any other value results in saving as a stringmin: accepts a number for minimum value accepted; unset by defaultmax: accepts a number for maximum value accepted; unset by defaultstep: accepts a number for stepping up/down values in the input; 1 by defaultExample:
\n- label: \"Puppy Count\"\n name: \"puppies\"\n widget: \"number\"\n default: 2\n valueType: \"int\"\n min: 1\n max: 101\n step: 2The object widget allows you to group multiple widgets together, nested under a single field. You can choose any widget as a child of an object widget—even other objects.
\nobjectOptions:
\ndefault: you can set defaults within each sub-field's configurationfields: (required) a nested list of widget fields to include in your widgetExample:
\n- label: \"Profile\"\n name: \"profile\"\n widget: \"object\"\n fields:\n - {label: \"Public\", name: \"public\", widget: \"boolean\", default: true}\n - {label: \"Name\", name: \"name\", widget: \"string\"}\n - label: \"Birthdate\"\n name: \"birthdate\"\n widget: \"date\"\n default: \"\"\n format: \"MM/DD/YYYY\"\n - label: \"Address\"\n name: \"address\"\n widget: \"object\"\n fields: \n - {label: \"Street Address\", name: \"street\", widget: \"string\"}\n - {label: \"City\", name: \"city\", widget: \"string\"}\n - {label: \"Postal Code\", name: \"post-code\", widget: \"string\"}The relation widget allows you to reference items from another collection. It provides a search input with a list of entries from the collection you're referencing, and the list automatically updates with matched entries based on what you've typed.
\nrelationOptions:
\ndefault: accepts any widget data type; defaults to an empty stringcollection: (required) name of the collection being referenced (string)displayFields: list of one or more names of fields in the referenced collection that will render in the autocomplete menu of the control. Defaults to valueField. For nested fields, separate each subfield with a . (E.g. name.first).searchFields: (required) list of one or more names of fields in the referenced collection to search for the typed value. Syntax to reference nested fields is similar to that of displayFields.valueField: (required) name of the field from the referenced collection whose value will be stored for the relation. Syntax to reference nested fields is similar to that of displayFields and searchFields. As valueField only allows for a single field, this parameter only accepts a string.multiple : accepts a boolean, defaults to falseoptionsLength: accepts integer to override number of options presented to user. Defaults to 20.Example (assuming a separate \"authors\" collection with \"name\" and \"twitterHandle\" fields with subfields \"first\" and \"last\" for the \"name\" field):
\n- label: \"Post Author\"\n name: \"author\"\n widget: \"relation\"\n collection: \"authors\"\n searchFields: [\"name.first\", \"twitterHandle\"]\n valueField: \"name.first\"\n displayFields: [\"twitterHandle\", \"followerCount\"]The generated UI input will search the authors collection by name and twitterHandle, and display each author's handle and follower count. On selection, the author name will be saved for the field.
\nThe select widget allows you to pick a string value from a dropdown menu.
\nselectOptions:
\ndefault: default values must be contained in options and are ignored otherwise
multiple: true enabled.label and value fields: accepts an object with label and value field or an array of such objects when multiple: true is enable. Defaults to no valueoptions: (required) a list of options for the dropdown menu; can be listed in two ways:
label and value fields: the label displays in the dropdown; the value is saved in the filemultiple: accepts a boolean; defaults to falsemin: minimum number of items; ignored if multiple is not truemax: maximum number of items; ignored if multiple is not trueExample (options as strings):
\n- label: \"Align Content\"\n name: \"align\"\n widget: \"select\"\n options: [\"left\", \"center\", \"right\"]Example (options as objects):
\n- label: \"City\"\n name: \"airport-code\"\n widget: \"select\"\n options:\n - { label: \"Chicago\", value: \"ORD\" }\n - { label: \"Paris\", value: \"CDG\" }\n - { label: \"Tokyo\", value: \"HND\" }Example (multiple):
\n- label: \"Tags\"\n name: \"tags\"\n widget: \"select\"\n multiple: true\n options: [\"Design\", \"UX\", \"Dev\"]\n default: [\"Design\"]Example (min/max):
\n- label: \"Tags\"\n name: \"tags\"\n widget: \"select\"\n multiple: true\n min: 1\n max: 3\n options: [\"Design\", \"UX\", \"Dev\"]\n default: [\"Design\"]The string widget translates a basic text input to a string value. For larger textarea inputs, use the text widget.
\nstringOptions:
\ndefault: accepts a string; defaults to an empty stringExample:
\n- {label: \"Title\", name: \"title\", widget: \"string\"}The text widget takes a multiline text field and saves it as a string. For shorter text inputs, use the string widget.
\ntextOptions:
\ndefault: accepts a string; defaults to an empty stringExample:
\n- {label: \"Description\", name: \"description\", widget: \"text\"}