Feature/docs (#67)

This commit is contained in:
Daniel Lautzenheiser
2022-11-04 17:41:12 -04:00
committed by GitHub
parent 7a1ec55a5c
commit 81ca566b5e
152 changed files with 1862 additions and 3832 deletions

View File

@ -4,7 +4,7 @@ title: CDN Hosting
weight: 4
---
This tutorial guides you through the steps for adding Static CMS via a public CDN to a site that's built with a common [static site generator](https://www.staticgen.com/), like Jekyll, Nest, Hugo, Hexo, or Gatsby. Alternatively, you can [start from a template](/docs/start-with-a-template) or dive right into [configuration options](/docs/configuration-options).
This tutorial guides you through the steps for adding Static CMS via a public CDN to a site that's built with a common [static site generator](https://www.staticgen.com/), like Jekyll, Next, Hugo, Hexo, or Gatsby. Alternatively, you can [start from a template](/docs/start-with-a-template) or dive right into [configuration options](/docs/configuration-options).
## App File Structure
@ -35,7 +35,7 @@ admin
└ config.yml
```
The first file, `admin/index.html`, is the entry point for the Static CMS admin interface. This means that users navigate to `yoursite.com/admin/` to access it. On the code side, it's a basic HTML starter page that loads the Static CMS JavaScript file from a public CDN. The second file, `admin/config.yml`, is the heart of your Static CMS installation, and a bit more complex. The [Configuration](#configuration) section covers the details.
The first file, `admin/index.html`, is the entry point for the Static CMS admin interface. This means that users navigate to `yoursite.com/admin/` to access it. On the code side, it's a basic HTML starter page that loads the Static CMS JavaScript file from a public CDN and initializes it. The second file, `admin/config.yml`, is the heart of your Static CMS installation, and a bit more complex. The [Configuration](#configuration) section covers the details.
In this example, we pull the `admin/index.html` file from a public CDN.
@ -67,15 +67,15 @@ Configuration is different for every site, so we'll break it down into parts. Ad
We're using [Netlify](https://www.netlify.com) for our hosting and authentication in this tutorial, so backend configuration is fairly straightforward.
For GitHub and GitLab repositories, you can start your Static CMS `config.yml` file with these lines:
For GitHub repositories, you can start your Static CMS `config.yml` file with these lines:
```yaml
backend:
title: git-gateway
name: git-gateway
branch: main # Branch to update (optional; defaults to main)
```
_(For Bitbucket repositories, use the [Bitbucket backend](/docs/bitbucket-backend) instructions instead.)_
_(For GitLab repositories, use [GitLab backend](/docs/gitlab-backend) and for Bitbucket repositories, use [Bitbucket backend](/docs/bitbucket-backend).)_
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 `main`.
@ -123,18 +123,18 @@ Given this example, our `collections` settings would look like this in your Stat
```yaml
collections:
- title: 'blog' # Used in routes, e.g., /admin/collections/blog
- name: 'blog' # Used in routes, e.g., /admin/collections/blog
label: 'Blog' # Used in the UI
folder: '_posts/blog' # The path to the folder where the documents are stored
create: true # Allow users to create new documents in this collection
slug: '{{year}}-{{month}}-{{day}}-{{slug}}' # Filename template, e.g., YYYY-MM-DD-title.md
fields: # The fields for each document, usually in front matter
- { label: 'Layout', title: 'layout', widget: 'hidden', default: 'blog' }
- { label: 'Title', title: 'title', widget: 'string' }
- { label: 'Publish Date', title: 'date', widget: 'datetime' }
- { label: 'Featured Image', title: 'thumbnail', widget: 'image' }
- { label: 'Rating (scale of 1-5)', title: 'rating', widget: 'number' }
- { label: 'Body', title: 'body', widget: 'markdown' }
- { label: 'Layout', name: 'layout', widget: 'hidden', default: 'blog' }
- { label: 'Title', name: 'title', widget: 'string' }
- { label: 'Publish Date', name: 'date', widget: 'datetime' }
- { label: 'Featured Image', name: 'thumbnail', widget: 'image' }
- { label: 'Rating (scale of 1-5)', name: 'rating', widget: 'number' }
- { label: 'Body', name: 'body', widget: 'markdown' }
```
Let's break that down:
@ -150,7 +150,7 @@ Let's break that down:
As described above, the `widget` property specifies a built-in or custom UI widget for a given field. When a content editor enters a value into a widget, that value is saved in the document front matter as the value for the `name` specified for that field. A full listing of available widgets can be found in the [Widgets doc](/docs/widgets).
Based on this example, you can go through the post types in your site and add the appropriate settings to your Static CMS `config.yml` file. Each post type should be listed as a separate node under the `collections` field. See the [Collections reference doc](/docs/configuration-options/#collections) for more configuration options.
Based on this example, you can go through the post types in your site and add the appropriate settings to your Static CMS `config.yml` file. Each post type should be listed as a separate node under the `collections` field. See the [Collections reference doc](/docs/collection-overview) for more configuration options.
## Authentication