feat(test): add docs linter to PR workflow actions (#4321)
This commit is contained in:
silverwebb925
GitHub
@ -3,7 +3,6 @@ group: Intro
|
||||
weight: 3
|
||||
title: Add to Your Site
|
||||
---
|
||||
|
||||
You can adapt Netlify CMS to a wide variety of projects. It works with any content written in markdown, JSON, YAML, or TOML files, stored in a repo on [GitHub](https://github.com/), [GitLab](https://about.gitlab.com/), or [Bitbucket](https://bitbucket.org). You can also create your own custom backend.
|
||||
|
||||
This tutorial guides you through the steps for adding Netlify CMS to a site that's built with a common [static site generator](https://www.staticgen.com/), like Jekyll, Hugo, Hexo, or Gatsby. Alternatively, you can [start from a template](../start-with-a-template) or dive right into [configuration options](../configuration-options).
|
||||
@ -12,8 +11,8 @@ This tutorial guides you through the steps for adding Netlify CMS to a site that
|
||||
|
||||
A static `admin` folder contains all Netlify CMS files, stored at the root of your published site. Where you store this folder in the source files depends on your static site generator. Here's the static file location for a few of the most popular static site generators:
|
||||
|
||||
| These generators ... | store static files in |
|
||||
| -------------------------------------------| --------------------- |
|
||||
| These generators | store static files in |
|
||||
| ------------------------------------------ | --------------------- |
|
||||
| Jekyll, GitBook | `/` (project root) |
|
||||
| Hugo, Gatsby, Nuxt, Gridsome, Zola, Sapper | `/static` |
|
||||
| Next | `/public` |
|
||||
@ -52,6 +51,7 @@ The first file, `admin/index.html`, is the entry point for the Netlify CMS admin
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
In the code above the `script` is loaded from the `unpkg` CDN. Should there be any issue, `jsDelivr` can be used as an alternative source. Simply set the `src` to `https://cdn.jsdelivr.net/npm/netlify-cms@^2.0.0/dist/netlify-cms.js`
|
||||
|
||||
The second file, `admin/config.yml`, is the heart of your Netlify CMS installation, and a bit more complex. The [Configuration](#configuration) section covers the details.
|
||||
@ -90,7 +90,7 @@ backend:
|
||||
branch: master # Branch to update (optional; defaults to master)
|
||||
```
|
||||
|
||||
_(For Bitbucket repositories, use the [Bitbucket backend](/docs/bitbucket-backend) instructions instead.)_
|
||||
*(For Bitbucket repositories, use the [Bitbucket backend](/docs/bitbucket-backend) instructions instead.)*
|
||||
|
||||
The configuration above specifies your backend protocol and your publication branch. Git Gateway is an open source API that acts as a proxy between authenticated users of your site and your site repo. (We'll get to the details of that in the [Authentication section](#authentication) below.) If you leave out the `branch` declaration, it defaults to `master`.
|
||||
|
||||
@ -277,4 +277,4 @@ If you left your site registration open, or for return visits after confirming a
|
||||
|
||||
**Note:** No matter where you access Netlify CMS — whether running locally, in a staging environment, or in your published site — it always fetches and commits files in your hosted repository (for example, on GitHub), on the branch you configured in your Netlify CMS config.yml file. This means that content fetched in the admin UI matches the content in the repository, which may be different from your locally running site. It also means that content saved using the admin UI saves directly to the hosted repository, even if you're running the UI locally or in staging.
|
||||
|
||||
Happy posting!
|
||||
Happy posting!
|
||||
@ -1,9 +1,8 @@
|
||||
---
|
||||
title: Configuration Options
|
||||
group: Configuration
|
||||
weight: 10
|
||||
title: Configuration Options
|
||||
---
|
||||
|
||||
## Configuration File
|
||||
|
||||
All configuration options for Netlify CMS are specified in a `config.yml` file, in the folder where you access the editor UI (usually in the `/admin` folder).
|
||||
@ -44,7 +43,7 @@ publish_mode: editorial_workflow
|
||||
|
||||
From a technical perspective, the workflow translates editor UI actions into common Git commands:
|
||||
|
||||
| Actions in Netlify UI ... | Perform these Git actions |
|
||||
| Actions in Netlify UI | Perform these Git actions |
|
||||
| ------------------------- | ----------------------------------------------------------------------------------------------------------------- |
|
||||
| Save draft | Commits to a new branch (named according to the pattern `cms/collectionName/entrySlug`), and opens a pull request |
|
||||
| Edit draft | Pushes another commit to the draft branch/pull request |
|
||||
@ -420,4 +419,4 @@ Defaults to an empty list.
|
||||
- label: Drafts
|
||||
field: draft
|
||||
pattern: true
|
||||
```
|
||||
```
|
||||
@ -1,9 +1,8 @@
|
||||
---
|
||||
title: Jekyll
|
||||
group: Guides
|
||||
weight: 30
|
||||
title: Jekyll
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
This section will help you integrate Netlify CMS with a new or existing Jekyll project.
|
||||
@ -87,13 +86,14 @@ collections:
|
||||
|
||||
A few things to note.
|
||||
|
||||
- We set the `slug` to `'{{year}}-{{month}}-{{day}}-{{slug}}'` because [Jekyll requires this format for blog posts](https://jekyllrb.com/docs/posts/#creating-posts). `year`, `month`, and `day` will be extracted from the `date` field, and `slug` will be generated from the `title` field.
|
||||
- We added `editor` configuration with a field `preview: false`. This will eliminate the preview pane. Because Jekyll uses Liquid templates, there currently isn't a good way to provide a preview of pages as you update the content.
|
||||
- The `layout` field default is set to `post` so Jekyll knows to use `_layouts/post.html` when it renders a post. This field is hidden because we want all posts to use the same layout.
|
||||
- The `date` and `title` field will be used by the `slug` - as noted above, Jekyll relies on the filename to determine a post's publish date, but Netlify CMS does not pull date information from the filename and requires a frontmatter `date` field. **Note** Changing the `date` or `title` fields in Netlify CMS will not update the filename. This has a few implications...
|
||||
- If you change the `date` or `title` fields in Netlify CMS, Jekyll won't notice
|
||||
- You don't necessarily need to change the `date` and `title` fields for existing posts, but if you don't the filenames and frontmatter will disagree in a way that might be confusing
|
||||
- If you want to avoid these issues, use a regular Jekyll collection instead of the special `_posts` directory
|
||||
* We set the `slug` to `'{{year}}-{{month}}-{{day}}-{{slug}}'` because [Jekyll requires this format for blog posts](https://jekyllrb.com/docs/posts/#creating-posts). `year`, `month`, and `day` will be extracted from the `date` field, and `slug` will be generated from the `title` field.
|
||||
* We added `editor` configuration with a field `preview: false`. This will eliminate the preview pane. Because Jekyll uses Liquid templates, there currently isn't a good way to provide a preview of pages as you update the content.
|
||||
* The `layout` field default is set to `post` so Jekyll knows to use `_layouts/post.html` when it renders a post. This field is hidden because we want all posts to use the same layout.
|
||||
* The `date` and `title` field will be used by the `slug` - as noted above, Jekyll relies on the filename to determine a post's publish date, but Netlify CMS does not pull date information from the filename and requires a frontmatter `date` field. **Note** Changing the `date` or `title` fields in Netlify CMS will not update the filename. This has a few implications:
|
||||
|
||||
* If you change the `date` or `title` fields in Netlify CMS, Jekyll won't notice
|
||||
* You don't necessarily need to change the `date` and `title` fields for existing posts, but if you don't the filenames and frontmatter will disagree in a way that might be confusing
|
||||
* If you want to avoid these issues, use a regular Jekyll collection instead of the special `_posts` directory
|
||||
|
||||
### Author Collection
|
||||
|
||||
@ -294,4 +294,4 @@ Finally, add the following to the collections array in `config.yml`
|
||||
- {label: Link, name: link, widget: string}
|
||||
```
|
||||
|
||||
Now you can add, rename, and rearrange the navigation items on your blog.
|
||||
Now you can add, rename, and rearrange the navigation items on your blog.
|
||||
@ -1,27 +1,28 @@
|
||||
---
|
||||
label: "Image"
|
||||
title: image
|
||||
label: Image
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
- **Name:** `image`
|
||||
- **UI:** file picker button opens media gallery allowing image files (jpg, jpeg, webp, gif, png, bmp, tiff, svg) only; displays selected image thumbnail
|
||||
- **Data type:** file path string
|
||||
- **Options:**
|
||||
- `default`: accepts a file path string; defaults to null
|
||||
- `media_library`: media library settings to apply when a media library is opened by the
|
||||
* **Name:** `image`
|
||||
* **UI:** file picker button opens media gallery allowing image files (jpg, jpeg, webp, gif, png, bmp, tiff, svg) only; displays selected image thumbnail
|
||||
* **Data type:** file path string
|
||||
* **Options:**
|
||||
|
||||
* `default`: accepts a file path string; defaults to null
|
||||
* `media_library`: settings to apply when opening a media library is opened by the
|
||||
current widget
|
||||
- `allow_multiple`: _(default: `true`)_ when set to `false`, prevents multiple selection for any media library extension, but must be supported by the extension in use
|
||||
- `config`: a configuration object that will be passed directly to the media library being
|
||||
used - available options are determined by the library
|
||||
- **Example:**
|
||||
```yaml
|
||||
- label: "Featured Image"
|
||||
name: "thumbnail"
|
||||
widget: "image"
|
||||
default: "/uploads/chocolate-dogecoin.jpg"
|
||||
media_library:
|
||||
config:
|
||||
multiple: true
|
||||
```
|
||||
|
||||
* `allow_multiple`: *(default: `true`)* when set to `false`, if the media library extension supports it, multiple selection will be disabled
|
||||
* `config`: a configuration object passed directly to the media library; check the documentation of your media library extension for available `config` options.
|
||||
* **Example:**
|
||||
|
||||
```yaml
|
||||
- label: "Featured Image"
|
||||
name: "thumbnail"
|
||||
widget: "image"
|
||||
default: "/uploads/chocolate-dogecoin.jpg"
|
||||
media_library:
|
||||
config:
|
||||
multiple: true
|
||||
```
|
||||
@ -1,77 +1,83 @@
|
||||
---
|
||||
label: "List"
|
||||
title: list
|
||||
label: List
|
||||
---
|
||||
|
||||
The 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.
|
||||
|
||||
- **Name:** `list`
|
||||
- **UI:** if `fields` 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 values
|
||||
- **Data type:** list of widget values
|
||||
- **Options:**
|
||||
- `default`: if `fields` is specified, declare defaults on the child widgets; if not, you may specify a list of strings to populate the text field
|
||||
- `allow_add`: if added and set to `false`, hides the button to add additional items
|
||||
- `collapsed`: if added and set to `false`, the list widget's content does not collapse by default
|
||||
- `summary`: allows customization of a collapsed list item object in a similar way to a [collection summary](/docs/configuration-options/?#summary)
|
||||
- `minimize_collapsed`: if added and set to `true`, the list widget's content will be completely hidden instead of only collapsed if the list widget itself is collapsed
|
||||
- `label_singular`: singular label to show as a part of the add button
|
||||
- `field`: a single widget field to be repeated
|
||||
- `fields`: a nested list of multiple widget fields to be included in each repeatable iteration
|
||||
- **Example** (`field`/`fields` not specified):
|
||||
```yaml
|
||||
- label: "Tags"
|
||||
name: "tags"
|
||||
widget: "list"
|
||||
default: ["news"]
|
||||
```
|
||||
- **Example** (`allow_add` marked `false`):
|
||||
```yaml
|
||||
- label: "Tags"
|
||||
name: "tags"
|
||||
widget: "list"
|
||||
allow_add: false
|
||||
default: ["news"]
|
||||
```
|
||||
- **Example** (with `field`):
|
||||
```yaml
|
||||
- label: "Gallery"
|
||||
name: "galleryImages"
|
||||
widget: "list"
|
||||
summary: '{{fields.image}}'
|
||||
field: {label: Image, name: image, widget: image}
|
||||
```
|
||||
- **Example** (with `fields`):
|
||||
```yaml
|
||||
- label: "Testimonials"
|
||||
name: "testimonials"
|
||||
widget: "list"
|
||||
summary: '{{fields.quote}} - {{fields.author.name}}'
|
||||
fields:
|
||||
- {label: Quote, name: quote, widget: string, default: "Everything is awesome!"}
|
||||
- label: Author
|
||||
name: author
|
||||
widget: object
|
||||
fields:
|
||||
- {label: Name, name: name, widget: string, default: "Emmet"}
|
||||
- {label: Avatar, name: avatar, widget: image, default: "/img/emmet.jpg"}
|
||||
```
|
||||
- **Example** (`collapsed` marked `false`):
|
||||
```yaml
|
||||
- label: "Testimonials"
|
||||
name: "testimonials"
|
||||
collapsed: false
|
||||
widget: "list"
|
||||
fields:
|
||||
- {label: Quote, name: quote, widget: string, default: "Everything is awesome!"}
|
||||
- {label: Author, name: author, widget: string }
|
||||
```
|
||||
- **Example** (`minimize_collapsed` marked `true`):
|
||||
```yaml
|
||||
- label: "Testimonials"
|
||||
name: "testimonials"
|
||||
minimize_collapsed: true
|
||||
widget: "list"
|
||||
fields:
|
||||
- {label: Quote, name: quote, widget: string, default: "Everything is awesome!"}
|
||||
- {label: Author, name: author, widget: string }
|
||||
```
|
||||
* **Name:** `list`
|
||||
* **UI:** without any `fields` specified, the list widget defaults to a text input for entering comma-separated values; with `fields` specified, the list widget contains a repeatable child widget, with controls for adding, deleting, and re-ordering the repeated widgets.
|
||||
* **Data type:** list of widget values
|
||||
* **Options:**
|
||||
|
||||
* `default`: you may specify a list of strings to populate the basic text field, but declare defaults on the child widgets if you are specifying `fields`;
|
||||
* `allow_add`: `false` hides the button to add additional items
|
||||
* `collapsed`: when `true`, the entries collapse by default
|
||||
* `summary`: specify the label displayed on collapsed entries
|
||||
* `minimize_collapsed`: when `true`, collapsing the list widget will hide all of it's entries instead of showing summaries
|
||||
* `label_singular`: the text to show on the add button
|
||||
* `field`: a single widget field to be repeated
|
||||
* `fields`: a nested list of multiple widget fields to be included in each repeatable iteration
|
||||
* **Example** (`field`/`fields` not specified):
|
||||
|
||||
```yaml
|
||||
- label: "Tags"
|
||||
name: "tags"
|
||||
widget: "list"
|
||||
default: ["news"]
|
||||
```
|
||||
* **Example** (`allow_add` marked `false`):
|
||||
|
||||
```yaml
|
||||
- label: "Tags"
|
||||
name: "tags"
|
||||
widget: "list"
|
||||
allow_add: false
|
||||
default: ["news"]
|
||||
```
|
||||
* **Example** (with `field`):
|
||||
|
||||
```yaml
|
||||
- label: "Gallery"
|
||||
name: "galleryImages"
|
||||
widget: "list"
|
||||
summary: '{{fields.image}}'
|
||||
field: {label: Image, name: image, widget: image}
|
||||
```
|
||||
* **Example** (with `fields`):
|
||||
|
||||
```yaml
|
||||
- label: "Testimonials"
|
||||
name: "testimonials"
|
||||
widget: "list"
|
||||
summary: '{{fields.quote}} - {{fields.author.name}}'
|
||||
fields:
|
||||
- {label: Quote, name: quote, widget: string, default: "Everything is awesome!"}
|
||||
- label: Author
|
||||
name: author
|
||||
widget: object
|
||||
fields:
|
||||
- {label: Name, name: name, widget: string, default: "Emmet"}
|
||||
- {label: Avatar, name: avatar, widget: image, default: "/img/emmet.jpg"}
|
||||
```
|
||||
* **Example** (`collapsed` marked `false`):
|
||||
|
||||
```yaml
|
||||
- label: "Testimonials"
|
||||
name: "testimonials"
|
||||
collapsed: false
|
||||
widget: "list"
|
||||
fields:
|
||||
- {label: Quote, name: quote, widget: string, default: "Everything is awesome!"}
|
||||
- {label: Author, name: author, widget: string }
|
||||
```
|
||||
* **Example** (`minimize_collapsed` marked `true`):
|
||||
|
||||
```yaml
|
||||
- label: "Testimonials"
|
||||
name: "testimonials"
|
||||
minimize_collapsed: true
|
||||
widget: "list"
|
||||
fields:
|
||||
- {label: Quote, name: quote, widget: string, default: "Everything is awesome!"}
|
||||
- {label: Author, name: author, widget: string }
|
||||
```
|
||||
@ -1,18 +1,19 @@
|
||||
---
|
||||
title: map
|
||||
label: "Map"
|
||||
label: Map
|
||||
---
|
||||
The map widget allows you to edit spatial data using an interactive map. Spatial data for a single piece of geometry saves as a GeoJSON string in WGS84 projection.
|
||||
|
||||
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.
|
||||
* **Name:** `map`
|
||||
* **UI:** interactive map
|
||||
* **Data type:** GeoJSON string
|
||||
* **Options:**
|
||||
|
||||
- **Name:** `map`
|
||||
- **UI:** interactive map
|
||||
- **Data type:** GeoJSON string
|
||||
- **Options:**
|
||||
- `decimals`: accepts a number to specify precision of saved coordinates; defaults to 7 decimals
|
||||
- `default`: accepts a GeoJSON string containing a single geometry; defaults to an empty string
|
||||
- `type`: accepts one string value of `Point`, `LineString` or `Polygon`; defaults to `Point`
|
||||
- **Example:**
|
||||
```yaml
|
||||
- {label: "Location", name: "location", widget: "map" }
|
||||
```
|
||||
* `decimals`: accepts a number to specify precision of saved coordinates; defaults to 7 decimals
|
||||
* `default`: accepts a GeoJSON string containing a single geometry; defaults to an empty string
|
||||
* `type`: accepts one string value of `Point`, `LineString` or `Polygon`; defaults to `Point`
|
||||
* **Example:**
|
||||
|
||||
```yaml
|
||||
- {label: "Location", name: "location", widget: "map" }
|
||||
```
|
||||
@ -1,22 +1,22 @@
|
||||
---
|
||||
label: 'Markdown'
|
||||
title: markdown
|
||||
label: Markdown
|
||||
---
|
||||
The markdown widget provides a full fledged text editor allowing users to format text with features such as headings and blockquotes. Users can change their editing view with a handy toggle button.
|
||||
|
||||
The markdown widget provides a full fledged text editor - which is based on [slate](https://github.com/ianstormtaylor/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.
|
||||
*Please 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.
|
||||
|
||||
_Please 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.
|
||||
* **Name:** `markdown`
|
||||
* **UI:** full text editor
|
||||
* **Data type:** markdown
|
||||
* **Options:**
|
||||
|
||||
- **Name:** `markdown`
|
||||
- **UI:** full text editor
|
||||
- **Data type:** markdown
|
||||
- **Options:**
|
||||
- `default`: accepts markdown content
|
||||
- `minimal`: 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`.
|
||||
- `editor_components`: 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](/docs/custom-widgets/#registereditorcomponent).
|
||||
- `modes`: an array of strings representing the names of allowed editor modes. Possible modes are `raw` and `rich_text`. If both modes are allowed, they can be toggled via a toggle button in the toolbar.
|
||||
- **Example:**
|
||||
* `default`: accepts markdown content
|
||||
* `minimal`: 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`.
|
||||
* `editor_components`: an array of strings representing the names of editor components to display (all shown by default). Netlify CMS includes `image` and `code-block` editor components by default, and custom components may be [created and registered](/docs/custom-widgets/#registereditorcomponent).
|
||||
* `modes`: an array of strings representing the names of allowed editor modes. Possible modes are `raw` and `rich_text`. A toggle button appears in the toolbar when more than one mode is available.
|
||||
* **Example:**
|
||||
|
||||
```yaml
|
||||
- { label: 'Blog post content', name: 'body', widget: 'markdown' }
|
||||
@ -26,4 +26,4 @@ This would render as:
|
||||
|
||||
|
||||
|
||||
_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.
|
||||
*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.
|
||||
@ -1,36 +1,37 @@
|
||||
---
|
||||
label: "Object"
|
||||
title: object
|
||||
label: Object
|
||||
---
|
||||
|
||||
The 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.
|
||||
|
||||
- **Name:** `object`
|
||||
- **UI:** a field containing one or more child widgets
|
||||
- **Data type:** list of child widget values
|
||||
- **Options:**
|
||||
- `default`: you can set defaults within each sub-field's configuration
|
||||
- `collapsed`: if added and labeled `true`, the widget's content is collapsed by default
|
||||
- `fields`: (**required**) a nested list of widget fields to include in your widget
|
||||
- **Example:**
|
||||
```yaml
|
||||
- label: "Profile"
|
||||
name: "profile"
|
||||
widget: "object"
|
||||
fields:
|
||||
- {label: "Public", name: "public", widget: "boolean", default: true}
|
||||
- {label: "Name", name: "name", widget: "string"}
|
||||
- label: "Birthdate"
|
||||
name: "birthdate"
|
||||
widget: "date"
|
||||
default: ""
|
||||
format: "MM/DD/YYYY"
|
||||
- label: "Address"
|
||||
name: "address"
|
||||
widget: "object"
|
||||
collapsed: true
|
||||
fields:
|
||||
- {label: "Street Address", name: "street", widget: "string"}
|
||||
- {label: "City", name: "city", widget: "string"}
|
||||
- {label: "Postal Code", name: "post-code", widget: "string"}
|
||||
```
|
||||
* **Name:** `object`
|
||||
* **UI:** a field containing one or more child widgets
|
||||
* **Data type:** list of child widget values
|
||||
* **Options:**
|
||||
|
||||
* `default`: you can set defaults within each sub-field's configuration
|
||||
* `collapsed`: if added and labeled `true`, collapse the widget's content by default
|
||||
* `fields`: (**required**) a nested list of widget fields to include in your widget
|
||||
* **Example:**
|
||||
|
||||
```yaml
|
||||
- label: "Profile"
|
||||
name: "profile"
|
||||
widget: "object"
|
||||
fields:
|
||||
- {label: "Public", name: "public", widget: "boolean", default: true}
|
||||
- {label: "Name", name: "name", widget: "string"}
|
||||
- label: "Birthdate"
|
||||
name: "birthdate"
|
||||
widget: "date"
|
||||
default: ""
|
||||
format: "MM/DD/YYYY"
|
||||
- label: "Address"
|
||||
name: "address"
|
||||
widget: "object"
|
||||
collapsed: true
|
||||
fields:
|
||||
- {label: "Street Address", name: "street", widget: "string"}
|
||||
- {label: "City", name: "city", widget: "string"}
|
||||
- {label: "Postal Code", name: "post-code", widget: "string"}
|
||||
```
|
||||
@ -1,23 +1,23 @@
|
||||
---
|
||||
label: "Relation"
|
||||
title: relation
|
||||
label: Relation
|
||||
---
|
||||
|
||||
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.
|
||||
|
||||
- **Name:** `relation`
|
||||
- **UI:** text input with search result dropdown
|
||||
- **Data type:** data type of the value pulled from the related collection item
|
||||
- **Options:**
|
||||
- `collection`: (**required**) name of the collection being referenced (string)
|
||||
- `value_field`: (**required**) name of the field from the referenced collection whose value will be stored for the relation. For nested fields, separate each subfield with a `.` (e.g. `name.first`). For list fields use a wildcard `*` to target all list items (e.g. `categories.*`).
|
||||
- `search_fields`: (**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 *value_field*.
|
||||
- `file`: allows referencing a specific file when the collection being referenced is a files collection (string)
|
||||
- `display_fields`: list of one or more names of fields in the referenced collection that will render in the autocomplete menu of the control. Defaults to `value_field`. Syntax to reference nested fields is similar to that of *value_field*.
|
||||
- `default`: accepts any widget data type; defaults to an empty string
|
||||
- `multiple` : accepts a boolean, defaults to `false`
|
||||
- `options_length`: accepts integer to override number of options presented to user. Defaults to `20`.
|
||||
- **Referencing a folder collection example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field):
|
||||
* **Name:** `relation`
|
||||
* **UI:** text input with search result dropdown
|
||||
* **Data type:** data type of the value pulled from the related collection item
|
||||
* **Options:**
|
||||
|
||||
* `collection`: (**required**) name of the referenced collection (string)
|
||||
* `value_field`: (**required**) name of the field from the referenced collection whose value will be stored for the relation. For nested fields, separate each subfield with a `.` (e.g. `name.first`). For list fields use a wildcard `*` to target all list items (e.g. `categories.*`).
|
||||
* `search_fields`: (**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 *value_field*.
|
||||
* `file`: allows referencing a specific file when the referenced collection is a files collection (string)
|
||||
* `display_fields`: list of one or more names of fields in the referenced collection that will render in the autocomplete menu of the control. Defaults to `value_field`. Syntax to reference nested fields is similar to that of *value_field*.
|
||||
* `default`: accepts any widget data type; defaults to an empty string
|
||||
* `multiple` : accepts a boolean, defaults to `false`
|
||||
* `options_length`: accepts integer to override number of options presented to user. Defaults to `20`.
|
||||
* **Referencing a folder collection example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field):
|
||||
|
||||
```yaml
|
||||
- label: "Post Author"
|
||||
@ -29,9 +29,9 @@ The relation widget allows you to reference items from another collection. It pr
|
||||
display_fields: ["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.
|
||||
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's name is saved for the field.
|
||||
|
||||
- **String templates example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field):
|
||||
* **String templates example** (assuming a separate "authors" collection with "name" and "twitterHandle" fields with subfields "first" and "last" for the "name" field):
|
||||
|
||||
```yaml
|
||||
- label: "Post Author"
|
||||
@ -43,9 +43,9 @@ The generated UI input will search the authors collection by name and twitterHan
|
||||
display_fields: ["{{twitterHandle}} - {{followerCount}}"]
|
||||
```
|
||||
|
||||
The generated UI input will search the authors collection by name, and display each author's handle and follower count. On selection, the author entry slug will be saved for the field.
|
||||
The generated UI input will search the authors collection by name, and display each author's handle and follower count. On selection, the author entry slug is saved for the field.
|
||||
|
||||
- **Referencing a file collection list field example** (assuming a separate "relation_files" collection with a file named "cities" with a list field "cities" with subfields "name" and "id"):
|
||||
* **Referencing a file collection list field example** (assuming a separate "relation_files" collection with a file named "cities" with a list field "cities" with subfields "name" and "id"):
|
||||
|
||||
```yaml
|
||||
- label: "City"
|
||||
@ -58,4 +58,4 @@ The generated UI input will search the authors collection by name, and display e
|
||||
value_field: "cities.*.id"
|
||||
```
|
||||
|
||||
The generated UI input will search the cities file by city name, and display each city's name. On selection, the city id will be saved for the field.
|
||||
The generated UI input will search the cities file by city name, and display each city's name. On selection, the city id is saved for the field.
|
||||
@ -1,57 +1,75 @@
|
||||
---
|
||||
label: "Select"
|
||||
title: select
|
||||
label: Select
|
||||
---
|
||||
|
||||
The select widget allows you to pick a string value from a dropdown menu.
|
||||
|
||||
- **Name:** `select`
|
||||
- **UI:** select input
|
||||
- **Data type:** string or array
|
||||
- **Options:**
|
||||
- `default`: default values must be contained in `options` and are ignored otherwise
|
||||
- string values: accepts a string; defaults to an empty string. Accepts an array of strings and defaults to an empty array with `multiple: true` enabled.
|
||||
- object with `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 value
|
||||
- `options`: (**required**) a list of options for the dropdown menu; can be listed in two ways:
|
||||
- string values: the label displayed in the dropdown is the value saved in the file
|
||||
- object with `label` and `value` fields: the label displays in the dropdown; the value is saved in the file
|
||||
- `multiple`: accepts a boolean; defaults to `false`
|
||||
- `min`: minimum number of items; ignored if **multiple** is not `true`
|
||||
- `max`: maximum number of items; ignored if **multiple** is not `true`
|
||||
- **Example** (options as strings):
|
||||
```yaml
|
||||
- label: "Align Content"
|
||||
name: "align"
|
||||
widget: "select"
|
||||
options: ["left", "center", "right"]
|
||||
```
|
||||
- **Example** (options as objects):
|
||||
```yaml
|
||||
- label: "City"
|
||||
name: "airport-code"
|
||||
widget: "select"
|
||||
options:
|
||||
- { label: "Chicago", value: "ORD" }
|
||||
- { label: "Paris", value: "CDG" }
|
||||
- { label: "Tokyo", value: "HND" }
|
||||
```
|
||||
- **Example** (multiple):
|
||||
```yaml
|
||||
- label: "Tags"
|
||||
name: "tags"
|
||||
widget: "select"
|
||||
multiple: true
|
||||
options: ["Design", "UX", "Dev"]
|
||||
default: ["Design"]
|
||||
```
|
||||
- **Example** (min/max):
|
||||
```yaml
|
||||
- label: "Tags"
|
||||
name: "tags"
|
||||
widget: "select"
|
||||
multiple: true
|
||||
min: 1
|
||||
max: 3
|
||||
options: ["Design", "UX", "Dev"]
|
||||
default: ["Design"]
|
||||
```
|
||||
* **Name:** `select`
|
||||
* **UI:** select input
|
||||
* **Data type:** string or array
|
||||
* **Options:**
|
||||
|
||||
* `default`: `options` must contain any default values
|
||||
|
||||
* string values: accepts a string; defaults to an empty string. Accepts an array of strings and defaults to an empty array with `multiple: true` enabled.
|
||||
* object with `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 value
|
||||
* `options`: (**required**) there are two ways to list of options for the dropdown menu:
|
||||
|
||||
* string values: the dropdown displays the value directly
|
||||
* object with `label` and `value` fields: the label displays in the dropdown; the value saves in the file
|
||||
* `multiple`: accepts a boolean; defaults to `false`
|
||||
* `min`: minimum number of items; ignored if **multiple** is `false`
|
||||
* `max`: maximum number of items; ignored if **multiple** is `false`
|
||||
* **Example** (options as strings):
|
||||
|
||||
```yaml
|
||||
- label: "Align Content"
|
||||
name: "align"
|
||||
widget: "select"
|
||||
options: ["left", "center", "right"]
|
||||
```
|
||||
|
||||
Selecting the `center` option, will save the value as:
|
||||
|
||||
```yaml
|
||||
align: "center"
|
||||
```
|
||||
* **Example** (options as objects):
|
||||
|
||||
```yaml
|
||||
- label: "City"
|
||||
name: "airport-code"
|
||||
widget: "select"
|
||||
options:
|
||||
- { label: "Chicago", value: "ORD" }
|
||||
- { label: "Paris", value: "CDG" }
|
||||
- { label: "Tokyo", value: "HND" }
|
||||
```
|
||||
|
||||
Selecting the `Chicago` option, will save the value as:
|
||||
|
||||
```yaml
|
||||
airport-code: "ORD"
|
||||
```
|
||||
* **Example** (multiple):
|
||||
|
||||
```yaml
|
||||
- label: "Tags"
|
||||
name: "tags"
|
||||
widget: "select"
|
||||
multiple: true
|
||||
options: ["Design", "UX", "Dev"]
|
||||
default: ["Design"]
|
||||
```
|
||||
* **Example** (min/max):
|
||||
|
||||
```yaml
|
||||
- label: "Tags"
|
||||
name: "tags"
|
||||
widget: "select"
|
||||
multiple: true
|
||||
min: 1
|
||||
max: 3
|
||||
options: ["Design", "UX", "Dev"]
|
||||
default: ["Design"]
|
||||
```
|
||||
@ -1,261 +0,0 @@
|
||||
---
|
||||
title: Writing Style Guide
|
||||
weight: 30
|
||||
group: Contributing
|
||||
---
|
||||
|
||||
# Netlify CMS Style Guide
|
||||
_Adapted from the [Kubernetes Style Guide](https://kubernetes.io/docs/contribute/style/style-guide)_
|
||||
|
||||
## Documentation Formatting Standards
|
||||
|
||||
### Use angle brackets for placeholders
|
||||
|
||||
Use angle brackets for placeholders. Tell the reader what a placeholder represents.
|
||||
|
||||
1. Display information about a cli command:
|
||||
|
||||
```
|
||||
npm install <package-name>
|
||||
```
|
||||
|
||||
where `<package-name>` is the name of a package.
|
||||
|
||||
### Use bold for user interface elements
|
||||
|
||||
Do: Click **Save**.
|
||||
|
||||
Don't: Click "Save".
|
||||
_____
|
||||
|
||||
Do: Select **Log Out**.
|
||||
|
||||
Don't: Select 'Log Out'.
|
||||
_____
|
||||
|
||||
### Use italics to define or introduce new terms
|
||||
|
||||
Do: A _collection_ is a set of entries ...
|
||||
|
||||
Don't: A "collection" is a set of entries ...
|
||||
_____
|
||||
|
||||
Do: These components form the _control pane_.
|
||||
|
||||
Don't: These components form the **control pane**.
|
||||
_____
|
||||
|
||||
### Use code style for filenames, directories, and paths
|
||||
|
||||
Do: Open the `config.yaml` file.
|
||||
|
||||
Don't: Open the config.yaml file.
|
||||
_____
|
||||
|
||||
Do: Go to the `/docs/guides` directory.
|
||||
|
||||
Don't: Go to the /docs/guides directory.
|
||||
_____
|
||||
|
||||
Do: Open the `/admin/index.html` file.
|
||||
|
||||
Don't: Open the /admin/index.html file.
|
||||
_____
|
||||
|
||||
### Use the international standard for punctuation inside quotes
|
||||
|
||||
Do: Branch names begin with "cms".
|
||||
|
||||
Don't: Branch names begin with "stage."
|
||||
_____
|
||||
|
||||
Do: The copy is called a "fork".
|
||||
|
||||
Don't: The copy is called a "fork."
|
||||
_____
|
||||
|
||||
## Inline code formatting
|
||||
|
||||
### Use code style for inline code and commands
|
||||
|
||||
For inline code in an HTML document, use the `<code>` tag. In a Markdown document, use the backtick (`).
|
||||
|
||||
Do: The `yarn start` command starts the development server.
|
||||
|
||||
Don't: The "yarn start" command starts the development server.
|
||||
_____
|
||||
|
||||
Do: For a production build, use `yarn build`.
|
||||
|
||||
Don't: For a production build, use "yarn build".
|
||||
_____
|
||||
|
||||
Do: Enclose code samples with triple backticks. `(```)`
|
||||
|
||||
Don't:Enclose code samples with any other syntax.
|
||||
_____
|
||||
|
||||
### Use code style for object field names
|
||||
|
||||
Do: Set the value of the `media_folder` field in the configuration file.
|
||||
|
||||
Don't: Set the value of the "media_folder" field in the configuration file.
|
||||
_____
|
||||
|
||||
Do: The value of the `name` field is a string.
|
||||
|
||||
Don't: The value of the "name" field is a string.
|
||||
_____
|
||||
|
||||
### Use normal style for string and integer field values
|
||||
|
||||
For field values of type string or integer, use normal style without quotation marks.
|
||||
|
||||
Do: Set the value of `publish_mode` to editorial_workflow.
|
||||
|
||||
Don't: Set the value of `imagePullPolicy` to "Always".
|
||||
_____
|
||||
|
||||
Do: Set the value of `image` to nginx:1.8.
|
||||
|
||||
Don't: Set the value of `image` to `nginx:1.8`.
|
||||
_____
|
||||
|
||||
Do: Set the value of the `replicas` field to 2.
|
||||
|
||||
Don't: Set the value of the `replicas` field to 2.
|
||||
_____
|
||||
|
||||
## Code snippet formatting
|
||||
|
||||
### Don’t include the command prompt
|
||||
|
||||
Do: yarn start
|
||||
|
||||
Don't: $ yarn start
|
||||
|
||||
## Content best practices
|
||||
|
||||
This section contains suggested best practices for clear, concise, and consistent content.
|
||||
|
||||
### Use present tense
|
||||
|
||||
Do: This command starts a proxy.
|
||||
|
||||
Don't: This command will start a proxy.
|
||||
|
||||
Exception: Use future or past tense if it is required to convey the correct meaning.
|
||||
|
||||
### Use active voice
|
||||
|
||||
Do: You can explore the API using a browser.
|
||||
|
||||
Don't: The API can be explored using a browser.
|
||||
_____
|
||||
|
||||
Do: The YAML file specifies the collection name.
|
||||
|
||||
Don't: The collection name is specified in the YAML file.
|
||||
_____
|
||||
|
||||
Exception: Use passive voice if active voice leads to an awkward construction.
|
||||
|
||||
### Use simple and direct language
|
||||
|
||||
Use simple and direct language. Avoid using unnecessary phrases, such as saying “please.”
|
||||
|
||||
Do: To create an entry, ...
|
||||
|
||||
Don't: In order to create an entry, ...
|
||||
_____
|
||||
|
||||
Do: See the configuration file.
|
||||
|
||||
Don't: Please see the configuration file.
|
||||
_____
|
||||
|
||||
Do: View the fields.
|
||||
|
||||
Don't: With this next command, we'll view the fields.
|
||||
_____
|
||||
|
||||
### Address the reader as “you”
|
||||
|
||||
Do: You can create a Deployment by ...
|
||||
|
||||
Don't: We'll create a Deployment by ...
|
||||
_____
|
||||
|
||||
Do: In the preceding output, you can see...
|
||||
|
||||
Don't: In the preceding output, we can see ...
|
||||
|
||||
### Avoid Latin phrases
|
||||
|
||||
Prefer English terms over Latin abbreviations.
|
||||
|
||||
Do: For example, ...
|
||||
|
||||
Don't: e.g., ...
|
||||
_____
|
||||
|
||||
Do: That is, ...
|
||||
|
||||
Don't: i.e., ...
|
||||
_____
|
||||
|
||||
Exception: Use “etc.” for et cetera.
|
||||
|
||||
## Patterns to avoid
|
||||
|
||||
### Avoid using “we”
|
||||
|
||||
Using “we” in a sentence can be confusing, because the reader might not know whether they’re part of the “we” you’re describing.
|
||||
|
||||
Do: Version 1.4 includes ...
|
||||
|
||||
Don't: In version 1.4, we have added ...
|
||||
_____
|
||||
|
||||
Do: Netlify CMS provides a new feature for ...
|
||||
|
||||
Don't: We provide a new feature ...
|
||||
_____
|
||||
|
||||
Do: This page teaches you how to use Widgets.
|
||||
|
||||
Don't: In this page, we are going to learn about Widgets.
|
||||
_____
|
||||
|
||||
### Avoid jargon and idioms
|
||||
|
||||
Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
|
||||
|
||||
Do: Internally
|
||||
|
||||
Don't: Under the hood, ...
|
||||
_____
|
||||
|
||||
Do: Create a new cluster.
|
||||
|
||||
Don't: Turn up a new cluster.
|
||||
_____
|
||||
|
||||
### Avoid statements about the future
|
||||
|
||||
Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.
|
||||
|
||||
### Avoid statements that will soon be out of date
|
||||
|
||||
Avoid words like “currently” and “new.” A feature that is new today might not be considered new in a few months.
|
||||
|
||||
Do: In version 1.4, ...
|
||||
|
||||
Don't: In the current version, ...
|
||||
_____
|
||||
|
||||
Do: The Federation feature provides ...
|
||||
|
||||
Don't: The new Federation feature provides ...
|
||||
_____
|
||||
|
||||
Reference in New Issue
Block a user