gcg/static-cms
0
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation, better typing on media folder selection

Browse Source
This commit is contained in:
Daniel Lautzenheiser
2022-11-02 13:18:06 -04:00
parent 590681d64e
commit fdd51aefa3
20 changed files with 357 additions and 156 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
website/content/docs/azure-backend.mdx
View File

@ -3,9 +3,10 @@ group: Accounts
title: Azure
weight: 20
---
For repositories stored on Azure, the `azure` backend allows CMS users to log in directly with their Azure account. Note that all users must have write access to your content repository for this to work.
## Authentication
In order to get Static CMS working with Azure DevOps, you need a Tenant Id and an Application Id.
1. If you do not have an Azure account, [create one here](https://azure.microsoft.com/en-us/free/?WT.mc_id=A261C142F) and make sure to have a credit card linked to the account.

4
website/content/docs/bitbucket-backend.mdx
View File

@ -5,7 +5,9 @@ weight: 20
---
For repositories stored on Bitbucket, the `bitbucket` backend allows CMS users to log in directly with their Bitbucket account. Note that all users must have write access to your content repository for this to work.
To enable it:
## Authentication
To enable Bitbucket authentication it:
1. Follow the authentication provider setup steps in the [Netlify docs](https://www.netlify.com/docs/authentication-providers/#using-an-authentication-provider).
2. Add the following lines to your Static CMS `config.yml` file:

2
website/content/docs/github-backend.mdx
View File

@ -5,6 +5,8 @@ weight: 30
---
For repositories stored on GitHub, the `github` backend allows CMS users to log in directly with their GitHub account. Note that all users must have push access to your content repository for this to work.
## Authentication
Because Github requires a server for authentication, Netlify facilitates basic GitHub authentication.
To enable basic GitHub authentication:

2
website/content/docs/gitlab-backend.mdx
View File

@ -7,7 +7,7 @@ For repositories stored on GitLab, the `gitlab` backend allows CMS users to log
**Note:** GitLab default branch is protected by default, thus typically requires `maintainer` permissions in order for users to have push access.
## Authorization
## Authentication
With GitLab's PKCE authorization, users can authenticate with GitLab directly from the client. To do this:

25
website/content/docs/widget-boolean.mdx
View File

@ -6,12 +6,19 @@ weight: 10
The boolean widget translates a toggle switch input to a true/false value.
- **Name:** `boolean`
- **UI:** toggle switch
- **Data type:** boolean
- **Options:**
- `default`: accepts `true` or `false`; defaults to `false` when `required` is set to `false`
- **Example:**
```yaml
- {label: "Draft", title: "draft", widget: "boolean", default: true}
```
## Widget options
For common options, see [Common widget options](/docs/widgets#common-widget-options).
|Name|Type|Default|Description|
|----|----|-------|-----------|
|default|boolean|`false`|_Optional_. The default value for the field|
## Example
```yaml
name: draft
label: Draft
widget: boolean
default: true
```

31
website/content/docs/widget-code.mdx
View File

@ -6,18 +6,21 @@ weight: 11
The code widget provides a code editor (powered by [Codemirror](https://codemirror.net)) with optional syntax awareness. Can output the raw code value or an object with the selected language and the raw code value.
- **Name:** `code`
- **UI:** code editor
- **Data type:** string
- **Options:**
- `default_language`: optional; default language to use
- `allow_language_selection`: optional; defaults to `false`: allows syntax to be changed
- `keys`: 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 `false`
## Widget options
- **Example:**
```yaml
- label: 'Code'
title: 'code'
widget: 'code'
```
For common options, see [Common widget options](/docs/widgets#common-widget-options).
| Name | Type | Default | Description |
| ------------------------ | ------- | -------------------------------- | -------------------------------------------------------------------- |
| default_language | string | | _Optional_. Default language to use |
| allow_language_selection | boolean | `false` | _Optional_. Allows language syntax to be changed |
| keys | boolean | `{ code: 'code', lang: 'lang' }` | _Optional_. Sets key names for code and lang if outputting an object |
| output_code_only | string | `true` | _Optional_. Set to `true` to output the string value only |
## Example
```yaml
name: code
label: Code
widget: code
```

43
website/content/docs/widget-color.mdx
View File

@ -6,18 +6,31 @@ weight: 12
The color widget translates a color picker to a color string.
- **Name:** `color`
- **UI:** color picker
- **Data type:** string
- **Options:**
- `default`: accepts a string; defaults to an empty string. Sets the default value
- `allow_input`: accepts a boolean, defaults to `false`. Allows manual editing of the color input value
- `enable_alpha`: accepts a boolean, defaults to `false`. Enables Alpha editing
- **Example:**
```yaml
- { label: 'Color', title: 'color', widget: 'color' }
```
- **Example:**
```yaml
- { label: 'Color', title: 'color', widget: 'color', enable_alpha: true, allow_input: true }
```
## Widget options
For common options, see [Common widget options](/docs/widgets#common-widget-options).
| Name | Type | Default | Description |
| ------------ | ------- | ------- | ---------------------------------------------------------- |
| default | string | `''` | _Optional_. The default value for the field |
| allow_input | boolean | `false` | _Optional_. Allows manual editing of the color input value |
| enable_alpha | boolean | `false` | _Optional_. Enables Alpha editing |
## Examples
### Basic
```yaml
name: color
label: Color
widget: color
```
### Kitchen Sink
```yaml
name: color
label: Color
widget: color
enable_alpha: true
allow_input: true
```

66
website/content/docs/widget-datetime.mdx
View File

@ -6,23 +6,49 @@ weight: 13
The datetime widget translates a datetime picker to a datetime string.
- **Name:** `datetime`
- **UI:** datetime picker
- **Data type:** Moment.js-formatted datetime string
- **Options:**
- `default`: accepts a datetime string, or an empty string to accept blank input; otherwise defaults to current datetime
- `format`: sets storage format; accepts Moment.js [tokens](https://momentjs.com/docs/#/parsing/string-format/); defaults to raw Date object (if supported by output format)
- `date_format`: sets date display format in UI; boolean or Moment.js [tokens](https://momentjs.com/docs/#/parsing/string-format/). If `true` use default locale format.
- `time_format`: sets time display format in UI; boolean or Moment.js [tokens](https://momentjs.com/docs/#/parsing/string-format/). If `true` use default locale format, `false` hides time-picker.
- `picker_utc`: _(default: `false`)_ when set to `true`, the datetime picker will display times in UTC. When `false`, the datetime picker will display times in the user's local timezone. When using date-only formats, it can be helpful to set this to `true` so users in all timezones will see the same date in the datetime picker.
- **Example:**
```yaml
- label: "Start time"
title: "start"
widget: "datetime"
default: ""
date_format: "DD.MM.YYYY" # e.g. 24.12.2021
time_format: "HH:mm" # e.g. 21:07
format: "LLL"
picker_utc: false
```
## Widget options
For common options, see [Common widget options](/docs/widgets#common-widget-options).
| Name | Type | Default | Description |
| ----------- | ---------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| default | string | `Current Date and Time` | _Optional_. The default value for the field. Accepts a datetime string, or an empty string to accept blank input. |
| format | string | `yyyy-MM-dd'T'HH:mm:ss.SSSXXX` | _Optional_. Sets storage format. Accepts [date-fns tokens](https://date-fns.org/v2.29.3/docs/format) |
| date_format | string<br />\| boolean | `true` | _Optional_. Sets date display format in UI.<ul><li>`string` - Accepts [date-fns tokens](https://date-fns.org/v2.29.3/docs/format)</li><li>`true` - Uses default locale format</li><li>`false` - If `time_format` is `true` or a string, then date picker is hidden</li></ul> |
| time_format | string<br />\| boolean | `true` | _Optional_. Sets time display format in UI.<ul><li>`string` - Accepts [date-fns tokens](https://date-fns.org/v2.29.3/docs/format)</li><li>`true` - Uses default locale format</li><li>`false` - Hides the time picker</li></ul> |
| picker_utc | boolean | `false` | _Optional_. <ul><li>`true` - The datetime picker will display times in UTC</li><li>`false` - The datetime picker will display times in the user's local timezone</li></ul> When using date-only formats, it can be helpful to set this to `true` so users in all timezones will see the same date in the datetime picker |
## Examples
### Date Time Picker
```yaml
name: 'datetime'
label: 'Datetime'
widget: 'datetime'
date_format: 'dd.MM.yyyy' # e.g. 24.12.2022
time_format: 'HH:mm' # e.g. 21:07
format: 'yyyy-MM-dd HH:mm' # e.g. 2022-12-24 21:07
```
### Date Picker
```yaml
name: 'date'
label: 'Date'
widget: 'datetime'
date_format: 'dd.MM.yyyy' # e.g. 24.12.2022
time_format: false
format: 'yyyy-MM-dd' # e.g. 2022-12-24
```
### Time Picker
```yaml
name: 'date'
label: 'Date'
widget: 'datetime'
date_format: false
time_format: 'HH:mm' # e.g. 21:07
format: 'HH:mm' # e.g. 21:07
```

35
website/content/docs/widgets.mdx
View File

@ -4,23 +4,34 @@ title: Overview
weight: 0
---
Widgets define the data type and interface for entry fields. Static CMS comes with several built-in widgets. Click the widget names in the sidebar to jump to specific widget details. We're always adding new widgets, and you can also [create your own](/docs/custom-widgets)!
Widgets define the data type and interface for entry fields. Static CMS comes with several built-in widgets. Click the widget names in the sidebar to jump to specific widget details. You can also [create your own](/docs/custom-widgets)!
Widgets are specified as collection fields in the Static CMS `config.yml` file. Note that [YAML syntax](https://en.wikipedia.org/wiki/YAML#Basic_components) allows lists and objects to be written in block or inline style, and the code samples below include a mix of both.
To see working examples of all of the built-in widgets, try making a 'Kitchen Sink' collection item on the [CMS demo site](https://cms-demo.netlify.com). (No login required: click the login button and the CMS will open.) You can refer to the demo [configuration code](https://github.com/StaticJsCMS/static-cms/blob/main/dev-test/config.yml) to see how each field was configured.
To see working examples of all of the built-in widgets, try making a 'Kitchen Sink' collection item on the [CMS demo site](https://static-cms-demo.netlify.com). (No login required: click the login button and the CMS will open.) You can refer to the demo [configuration code](https://github.com/StaticJsCMS/static-cms/blob/main/dev-test/config.yml) to see how each field was configured.
## Common widget options
The following options are available on all fields:
- `required`: specify as `false` to make a field optional; defaults to `true`
- `hint`: optionally add helper text directly below a widget. Useful for including instructions. Accepts markdown for bold, italic, strikethrough, and links.
- `pattern`: add field validation by specifying a list with a [regex pattern](https://regexr.com/) and an error message; more extensive validation can be achieved with [custom widgets](/docs/custom-widgets/#advanced-field-validation)
- **Example:**
```yaml
label: "Title"
title: "title"
widget: "string"
pattern: ['.{12,}', "Must have at least 12 characters"]
```
| Name | Type | Default | Description |
| ------------- | ----------------------------------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | | The name of the field |
| widget | string | `'string'` | _Optional_. The type of widget to render for the field |
| label | string | `name` | _Optional_. The display name of the field |
| required | boolean | `true` | _Optional_. Specify as `false` to make a field optional |
| hint | string | | _Optional_. Adds helper text directly below a widget. Useful for including instructions. Accepts markdown for bold, italic, strikethrough, and links. |
| pattern | string | | _Optional_. Adds field validation by specifying a list with a [regex pattern](https://regexr.com/) and an error message; more extensive validation can be achieved with [custom widgets](/docs/custom-widgets/#advanced-field-validation) |
| i18n | boolean<br />\|'translate'<br />\|'duplicate'<br />\|'none' | | _Optional_. <img src="https://img.shields.io/badge/-Beta%20Feature-blue" alt="Beta Feature" /><ul><li>`translate` - Allows translation of the field</li><li>`duplicate` - Duplicates the value from the default locale</li><li>`true` - Accept parent values as default</li><li>`none` or `false` - Exclude field from translations</li></ul> |
| media_folder | string | | _Optional_. Specifies the folder path where uploaded files should be saved, relative to the base of the repo |
| public_folder | string | | _Optional_. Specifies the folder path where the files uploaded by the media library will be accessed, relative to the base of the built site |
| comment | string | | _Optional_. Adds comment before the field (only supported for yaml) |
### Example
```yaml
name: title
label: Title
widget: string
pattern: ['.{12,}', 'Must have at least 12 characters']
```