Feature/docs (#67)
This commit is contained in:
Daniel Lautzenheiser
committed by
GitHub
GitHub
parent
7a1ec55a5c
commit
81ca566b5e
@ -1,56 +1,13 @@
|
||||
---
|
||||
group: Configuration
|
||||
title: Beta Features!
|
||||
group: Intro
|
||||
title: Beta Features
|
||||
weight: 200
|
||||
---
|
||||
We run new functionality in an open beta format from time to time. That means that this functionality is totally available for use, and we *think* it might be ready for primetime, but it could break or change without notice.
|
||||
|
||||
Static CMS runs new functionality in an open beta format from time to time. That means that this functionality is totally available for use, an it might be ready for primetime, but it could break or change without notice.
|
||||
|
||||
**Use these features at your own risk.**
|
||||
|
||||
## Working with a Local Git Repository
|
||||
|
||||
You can connect Static CMS to a local Git repository, instead of working with a live repo.
|
||||
|
||||
1. Navigate to a local Git repository configured with the CMS.
|
||||
2. Add the top-level property `local_backend` configuration to your `config.yml`:
|
||||
|
||||
```yaml
|
||||
backend:
|
||||
title: git-gateway
|
||||
|
||||
# when using the default proxy server port
|
||||
local_backend: true
|
||||
```
|
||||
|
||||
3. Run `npx @staticcms/proxy-server` from the root directory of the above repository.
|
||||
|
||||
* If the default port (8081) is in use, the proxy server won't start and you will see an error message. In this case, follow [these steps](#configure-the-@staticcms/proxy-server-port-number) before proceeding.
|
||||
4. Start your local development server (e.g. run `gatsby develop`).
|
||||
5. Open `http://localhost:<port>/admin` to verify that your can administer your content locally. Replace `<port>` with the port of your local development server. For example Gatsby's default port is `8000`
|
||||
|
||||
**Note:** `@staticcms/proxy-server` runs an unauthenticated express server. As any client can send requests to the server, it should only be used for local development.
|
||||
|
||||
### Configure the Static CMS proxy server port number
|
||||
|
||||
1. Create a `.env` file in the project's root folder and define the PORT you'd like the proxy server to use
|
||||
|
||||
```ini
|
||||
PORT=8082
|
||||
```
|
||||
|
||||
2. Update the `local_backend` object in `config.yml` and specify a `url` property to use your custom port number
|
||||
|
||||
```yaml
|
||||
backend:
|
||||
title: git-gateway
|
||||
|
||||
local_backend:
|
||||
# when using a custom proxy server port
|
||||
url: http://localhost:8082/api/v1
|
||||
# when accessing the local site from a host other than 'localhost' or '127.0.0.1'
|
||||
allowed_hosts: ['192.168.0.1']
|
||||
```
|
||||
|
||||
## i18n Support
|
||||
|
||||
The CMS can provide a side by side interface for authoring content in multiple languages.
|
||||
@ -78,7 +35,7 @@ i18n:
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
- title: i18n_content
|
||||
- name: i18n_content
|
||||
# same as the top level, but all fields are optional and defaults to the top level
|
||||
# can also be a boolean to accept the top level defaults
|
||||
i18n: true
|
||||
@ -88,20 +45,20 @@ When using a file collection, you must also enable i18n for each individual file
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
- title: pages
|
||||
- name: pages
|
||||
label: Pages
|
||||
# Configure i18n for this collection.
|
||||
i18n:
|
||||
structure: single_file
|
||||
locales: [en, de, fr]
|
||||
files:
|
||||
- title: about
|
||||
- name: about
|
||||
label: About Page
|
||||
file: site/content/about.yml
|
||||
# Enable i18n for this file.
|
||||
i18n: true
|
||||
fields:
|
||||
- { label: Title, title: title, widget: string, i18n: true }
|
||||
- { label: Title, name: title, widget: string, i18n: true }
|
||||
```
|
||||
|
||||
### Field level configuration
|
||||
@ -109,17 +66,17 @@ collections:
|
||||
```yaml
|
||||
fields:
|
||||
- label: Title
|
||||
title: title
|
||||
name: title
|
||||
widget: string
|
||||
# same as 'i18n: translate'. Allows translation of the title field
|
||||
i18n: true
|
||||
- label: Date
|
||||
title: date
|
||||
name: date
|
||||
widget: datetime
|
||||
# The date field will be duplicated from the default locale.
|
||||
i18n: duplicate
|
||||
- label: Body
|
||||
title: body
|
||||
name: body
|
||||
# The markdown field will be omitted from the translation.
|
||||
widget: markdown
|
||||
```
|
||||
@ -132,22 +89,22 @@ i18n:
|
||||
locales: [en, de, fr]
|
||||
|
||||
collections:
|
||||
- title: posts
|
||||
- name: posts
|
||||
label: Posts
|
||||
folder: content/posts
|
||||
create: true
|
||||
i18n: true
|
||||
fields:
|
||||
- label: Title
|
||||
title: title
|
||||
name: title
|
||||
widget: string
|
||||
i18n: true
|
||||
- label: Date
|
||||
title: date
|
||||
name: date
|
||||
widget: datetime
|
||||
i18n: duplicate
|
||||
- label: Body
|
||||
title: body
|
||||
name: body
|
||||
widget: markdown
|
||||
```
|
||||
|
||||
@ -159,96 +116,29 @@ collections:
|
||||
|
||||
```yaml
|
||||
- label: 'Object'
|
||||
title: 'object'
|
||||
name: 'object'
|
||||
widget: 'object'
|
||||
i18n: true
|
||||
fields:
|
||||
- { label: 'String', title: 'string', widget: 'string', i18n: true }
|
||||
- { label: 'Date', title: 'date', widget: 'datetime', i18n: duplicate }
|
||||
- { label: 'Boolean', title: 'boolean', widget: 'boolean', i18n: duplicate }
|
||||
- { label: 'String', name: 'string', widget: 'string', i18n: true }
|
||||
- { label: 'Date', name: 'date', widget: 'datetime', i18n: duplicate }
|
||||
- { label: 'Boolean', name: 'boolean', widget: 'boolean', i18n: duplicate }
|
||||
- {
|
||||
label: 'Object',
|
||||
title: 'object',
|
||||
name: 'object',
|
||||
widget: 'object',
|
||||
i18n: true,
|
||||
field: { label: 'String', title: 'string', widget: 'string', i18n: duplicate },
|
||||
field: { label: 'String', name: 'string', widget: 'string', i18n: duplicate },
|
||||
}
|
||||
```
|
||||
|
||||
## Folder Collections Path
|
||||
|
||||
By default the CMS stores folder collection content under the folder specified in the collection setting.
|
||||
See [Folder Collections Path](/docs/collection-types#folder-collections-path).
|
||||
|
||||
For example configuring `folder: posts` for a collection will save the content under `posts/post-title.md`.
|
||||
## Nested Collections
|
||||
|
||||
You can now specify an additional `path` template (similar to the `slug` template) to control the content destination.
|
||||
|
||||
This allows saving content in subfolders, e.g. configuring `path: '{{year}}/{{slug}}'` will save the content under `posts/2019/post-title.md`.
|
||||
|
||||
## Folder Collections Media and Public Folder
|
||||
|
||||
By default the CMS stores media files for all collections under a global `media_folder` directory as specified in the configuration.
|
||||
|
||||
When using the global `media_folder` directory any entry field that points to a media file will use the absolute path to the published file as designated by the `public_folder` configuration.
|
||||
|
||||
For example configuring:
|
||||
|
||||
```yaml
|
||||
media_folder: static/media
|
||||
public_folder: /media
|
||||
```
|
||||
|
||||
And saving an entry with an image named `image.png` will result in the image being saved under `static/media/image.png` and relevant entry fields populated with the value of `/media/image.png`.
|
||||
|
||||
Some static site generators (e.g. Gatsby) work best when using relative image paths.
|
||||
|
||||
This can now be achieved using a per collection `media_folder` configuration which specifies a relative media folder for the collection.
|
||||
|
||||
For example, the following configuration will result in media files being saved in the same directory as the entry, and the image field being populated with the relative path to the image.
|
||||
|
||||
```yaml
|
||||
media_folder: static/media
|
||||
public_folder: /media
|
||||
collections:
|
||||
- title: posts
|
||||
label: Posts
|
||||
label_singular: 'Post'
|
||||
folder: content/posts
|
||||
path: '{{slug}}/index'
|
||||
media_folder: ''
|
||||
public_folder: ''
|
||||
fields:
|
||||
- label: Title
|
||||
title: title
|
||||
widget: string
|
||||
- label: 'Cover Image'
|
||||
title: 'image'
|
||||
widget: 'image'
|
||||
```
|
||||
|
||||
More specifically, saving an entry with a title of `example post` with an image named `image.png` will result in a directory structure of:
|
||||
|
||||
```bash
|
||||
content
|
||||
posts
|
||||
example-post
|
||||
index.md
|
||||
image.png
|
||||
```
|
||||
|
||||
And for the image field being populated with a value of `image.png`.
|
||||
|
||||
**Note: When specifying a `path` on a folder collection, `media_folder` defaults to an empty string.**
|
||||
|
||||
**Available template tags:**
|
||||
|
||||
Supports all of the [`slug` templates](/docs/configuration-options#slug) and:
|
||||
|
||||
* `{{dirname}}` The path to the file's parent directory, relative to the collection's `folder`.
|
||||
* `{{filename}}` The file name without the extension part.
|
||||
* `{{extension}}` The file extension.
|
||||
* `{{media_folder}}` The global `media_folder`.
|
||||
* `{{public_folder}}` The global `public_folder`.
|
||||
Seed [Nested Collections](/docs/collection-types#nested-collections).
|
||||
|
||||
## List Widget: Variable Types
|
||||
|
||||
@ -264,9 +154,9 @@ To use variable types in the list widget, update your field configuration as fol
|
||||
|
||||
### Additional list widget options
|
||||
|
||||
* `types`: a nested list of object widgets. All widgets must be of type `object`. Every object widget may define different set of fields.
|
||||
* `typeKey`: the name of the field that will be added to every item in list representing the name of the object widget that item belongs to. Ignored if `types` is not defined. Default is `type`.
|
||||
* `summary`: allows customization of a collapsed list item object in a similar way to a [collection summary](/docs/configuration-options/?#summary)
|
||||
- `types`: a nested list of object widgets. All widgets must be of type `object`. Every object widget may define different set of fields.
|
||||
- `typeKey`: the name of the field that will be added to every item in list representing the name of the object widget that item belongs to. Ignored if `types` is not defined. Default is `type`.
|
||||
- `summary`: allows customization of a collapsed list item object in a similar way to a [collection summary](/docs/configuration-options/?#summary)
|
||||
|
||||
### Example Configuration
|
||||
|
||||
@ -275,27 +165,27 @@ either a "carousel" or a "spotlight". Each type has a unique name and set of fie
|
||||
|
||||
```yaml
|
||||
- label: 'Home Section'
|
||||
title: 'sections'
|
||||
name: 'sections'
|
||||
widget: 'list'
|
||||
types:
|
||||
- label: 'Carousel'
|
||||
title: 'carousel'
|
||||
name: 'carousel'
|
||||
widget: object
|
||||
summary: '{{fields.header}}'
|
||||
fields:
|
||||
- { label: Header, title: header, widget: string, default: 'Image Gallery' }
|
||||
- { label: Template, title: template, widget: string, default: 'carousel.html' }
|
||||
- { label: Header, name: header, widget: string, default: 'Image Gallery' }
|
||||
- { label: Template, name: template, widget: string, default: 'carousel.html' }
|
||||
- label: Images
|
||||
title: images
|
||||
name: images
|
||||
widget: list
|
||||
field: { label: Image, title: image, widget: image }
|
||||
field: { label: Image, name: image, widget: image }
|
||||
- label: 'Spotlight'
|
||||
title: 'spotlight'
|
||||
name: 'spotlight'
|
||||
widget: object
|
||||
fields:
|
||||
- { label: Header, title: header, widget: string, default: 'Spotlight' }
|
||||
- { label: Template, title: template, widget: string, default: 'spotlight.html' }
|
||||
- { label: Text, title: text, widget: text, default: 'Hello World' }
|
||||
- { label: Header, name: header, widget: string, default: 'Spotlight' }
|
||||
- { label: Template, name: template, widget: string, default: 'spotlight.html' }
|
||||
- { label: Text, name: text, widget: text, default: 'Hello World' }
|
||||
```
|
||||
|
||||
### Example Output
|
||||
@ -367,7 +257,7 @@ init()
|
||||
init({
|
||||
config: {
|
||||
backend: {
|
||||
title: 'git-gateway',
|
||||
name: 'git-gateway',
|
||||
},
|
||||
},
|
||||
})
|
||||
@ -383,17 +273,17 @@ init({
|
||||
init({
|
||||
config: {
|
||||
backend: {
|
||||
title: 'git-gateway',
|
||||
name: 'git-gateway',
|
||||
},
|
||||
load_config_file: false,
|
||||
media_folder: "static/images/uploads",
|
||||
public_folder: "/images/uploads",
|
||||
collections: [
|
||||
{ label: "Blog", title: "blog", folder: "_posts/blog", create: true, fields: [
|
||||
{ label: "Title", title: "title", widget: "string" },
|
||||
{ label: "Publish Date", title: "date", widget: "datetime" },
|
||||
{ label: "Featured Image", title: "thumbnail", widget: "image" },
|
||||
{ label: "Body", title: "body", widget: "markdown" },
|
||||
{ label: "Blog", name: "blog", folder: "_posts/blog", create: true, fields: [
|
||||
{ label: "Title", name: "title", widget: "string" },
|
||||
{ label: "Publish Date", name: "date", widget: "datetime" },
|
||||
{ label: "Featured Image", name: "thumbnail", widget: "image" },
|
||||
{ label: "Body", name: "body", widget: "markdown" },
|
||||
]},
|
||||
],
|
||||
},
|
||||
@ -422,22 +312,22 @@ backend:
|
||||
|
||||
Static CMS generates the following commit types:
|
||||
|
||||
| Commit type | When is it triggered? | Available template tags |
|
||||
| --------------- | ---------------------------------------- | ----------------------------------------------------------- |
|
||||
| `create` | A new entry is created | `slug`, `path`, `collection`, `author-login`, `author-name` |
|
||||
| `update` | An existing entry is changed | `slug`, `path`, `collection`, `author-login`, `author-name` |
|
||||
| `delete` | An existing entry is deleted | `slug`, `path`, `collection`, `author-login`, `author-name` |
|
||||
| `uploadMedia` | A media file is uploaded | `path`, `author-login`, `author-name` |
|
||||
| `deleteMedia` | A media file is deleted | `path`, `author-login`, `author-name` |
|
||||
| Commit type | When is it triggered? | Available template tags |
|
||||
| ------------- | ---------------------------- | ----------------------------------------------------------- |
|
||||
| `create` | A new entry is created | `slug`, `path`, `collection`, `author-login`, `author-name` |
|
||||
| `update` | An existing entry is changed | `slug`, `path`, `collection`, `author-login`, `author-name` |
|
||||
| `delete` | An existing entry is deleted | `slug`, `path`, `collection`, `author-login`, `author-name` |
|
||||
| `uploadMedia` | A media file is uploaded | `path`, `author-login`, `author-name` |
|
||||
| `deleteMedia` | A media file is deleted | `path`, `author-login`, `author-name` |
|
||||
|
||||
Template tags produce the following output:
|
||||
|
||||
* `{{slug}}`: the url-safe filename of the entry changed
|
||||
* `{{collection}}`: the name of the collection containing the entry changed
|
||||
* `{{path}}`: the full path to the file changed
|
||||
* `{{message}}`: the relevant message based on the current change (e.g. the `create` message when an entry is created)
|
||||
* `{{author-login}}`: the login/username of the author
|
||||
* `{{author-name}}`: the full name of the author (might be empty based on the user's profile)
|
||||
- `{{slug}}`: the url-safe filename of the entry changed
|
||||
- `{{collection}}`: the name of the collection containing the entry changed
|
||||
- `{{path}}`: the full path to the file changed
|
||||
- `{{message}}`: the relevant message based on the current change (e.g. the `create` message when an entry is created)
|
||||
- `{{author-login}}`: the login/username of the author
|
||||
- `{{author-name}}`: the full name of the author (might be empty based on the user's profile)
|
||||
|
||||
## Image widget file size limit
|
||||
|
||||
@ -447,7 +337,7 @@ Example config:
|
||||
|
||||
```yaml
|
||||
- label: 'Featured Image'
|
||||
title: 'thumbnail'
|
||||
name: 'thumbnail'
|
||||
widget: 'image'
|
||||
default: '/uploads/chocolate-dogecoin.jpg'
|
||||
media_library:
|
||||
@ -463,18 +353,18 @@ Example config:
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
- title: 'posts'
|
||||
- name: 'posts'
|
||||
label: 'Posts'
|
||||
folder: '_posts'
|
||||
summary: "{{title | upper}} - {{date | date('YYYY-MM-DD')}} – {{body | truncate(20, '***')}}"
|
||||
fields:
|
||||
- { label: 'Title', title: 'title', widget: 'string' }
|
||||
- { label: 'Publish Date', title: 'date', widget: 'datetime' }
|
||||
- { label: 'Body', title: 'body', widget: 'markdown' }
|
||||
- { label: 'Title', name: 'title', widget: 'string' }
|
||||
- { label: 'Publish Date', name: 'date', widget: 'datetime' }
|
||||
- { label: 'Body', name: 'body', widget: 'markdown' }
|
||||
```
|
||||
|
||||
The above config will transform the title field to uppercase and format the date field using `YYYY-MM-DD` format.
|
||||
Available transformations are `upper`, `lower`, `date('<format>')`, `default('defaultValue')`, `ternary('valueForTrue','valueForFalse')` and `truncate(<number>)`/`truncate(<number>, '<string>')`
|
||||
Available transformations are `upper`, `lower`, `date('<format>')`, `default('defaultValue')`, `ternary('valueForTrue','valueForFalse')` and `truncate(<number>)`/`truncate(<number>, '<string>')`
|
||||
|
||||
## Registering to CMS Events
|
||||
|
||||
@ -484,7 +374,7 @@ Example usage:
|
||||
|
||||
```javascript
|
||||
CMS.registerEventListener({
|
||||
title: 'prePublish',
|
||||
name: 'prePublish',
|
||||
handler: ({ author, entry }) => console.info(JSON.stringify({ author, data: entry.data })),
|
||||
});
|
||||
```
|
||||
@ -493,7 +383,7 @@ Supported events are `prePublish`, `postPublish`, `preSave` and `postSave`. The
|
||||
|
||||
```javascript
|
||||
CMS.registerEventListener({
|
||||
title: 'preSave',
|
||||
name: 'preSave',
|
||||
handler: ({ entry }) => {
|
||||
return entry.data.set('title', 'new title');
|
||||
},
|
||||
@ -508,23 +398,23 @@ For example given the configuration:
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
- title: posts
|
||||
- name: posts
|
||||
label: Posts
|
||||
folder: content/posts
|
||||
create: true
|
||||
fields:
|
||||
- label: Title
|
||||
title: title
|
||||
name: title
|
||||
widget: string
|
||||
- label: Object
|
||||
title: object
|
||||
name: object
|
||||
widget: object
|
||||
fields:
|
||||
- label: Title
|
||||
title: title
|
||||
name: title
|
||||
widget: string
|
||||
- label: body
|
||||
title: body
|
||||
name: body
|
||||
widget: markdown
|
||||
```
|
||||
|
||||
@ -534,45 +424,3 @@ will open the editor for a new post with the `title` field populated with `first
|
||||
with `second` and the markdown `body` field with `# content`.
|
||||
|
||||
**Note:** URL Encoding might be required for certain values (e.g. in the previous example the value for `body` is URL encoded).
|
||||
|
||||
## Nested Collections
|
||||
|
||||
Allows a folder collection to show a nested structure of entries and edit the locations of the entries.
|
||||
|
||||
Example configuration:
|
||||
|
||||
```yaml
|
||||
collections:
|
||||
- title: pages
|
||||
label: Pages
|
||||
label_singular: 'Page'
|
||||
folder: content/pages
|
||||
create: true
|
||||
# adding a nested object will show the collection folder structure
|
||||
nested:
|
||||
depth: 100 # max depth to show in the collection tree
|
||||
summary: '{{title}}' # optional summary for a tree node, defaults to the inferred title field
|
||||
fields:
|
||||
- label: Title
|
||||
title: title
|
||||
widget: string
|
||||
- label: Body
|
||||
title: body
|
||||
widget: markdown
|
||||
```
|
||||
|
||||
Nested collections expect the following directory structure:
|
||||
|
||||
```bash
|
||||
content
|
||||
└── pages
|
||||
├── authors
|
||||
│ ├── author-1
|
||||
│ │ └── index.md
|
||||
│ └── index.md
|
||||
├── index.md
|
||||
└── posts
|
||||
├── hello-world
|
||||
│ └── index.md
|
||||
└── index.md
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user