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

Feature/rebrand (#27)

Browse Source
This commit is contained in:
Daniel Lautzenheiser
2022-10-02 20:06:20 -04:00
committed by GitHub
parent 11a684f372
commit 8a59f850d1
117 changed files with 2398 additions and 2272 deletions
Download Patch File Download Diff File Expand all files Collapse all files

36
website/content/docs/add-to-your-site.md
View File

@ -3,13 +3,13 @@ group: Intro
weight: 3
title: Add to Your Site
---
You can adapt Simple 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.
You can adapt Static 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 Simple 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).
This tutorial guides you through the steps for adding Static 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).
## App File Structure
A static `admin` folder contains all Simple 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:
A static `admin` folder contains all Static 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 |
| ------------------------------------------------------- | --------------------- |
@ -26,7 +26,7 @@ A static `admin` folder contains all Simple CMS files, stored at the root of you
| preact-cli | `/src/static` |
| Docusaurus | `/static` |
If your generator isn't listed here, you can check its documentation, or as a shortcut, look in your project for a `css` or `images` folder. The contents of folders like that are usually processed as static files, so it's likely you can store your `admin` folder next to those. (When you've found the location, feel free to add it to these docs by [filing a pull request](https://github.com/SimpleCMS/simple-cms/blob/main/CONTRIBUTING.md#pull-requests)!)
If your generator isn't listed here, you can check its documentation, or as a shortcut, look in your project for a `css` or `images` folder. The contents of folders like that are usually processed as static files, so it's likely you can store your `admin` folder next to those. (When you've found the location, feel free to add it to these docs by [filing a pull request](https://github.com/StaticJsCMS/static-cms/blob/main/CONTRIBUTING.md#pull-requests)!)
Inside the `admin` folder, you'll create two files:
@ -36,7 +36,7 @@ admin
└ config.yml
```
The first file, `admin/index.html`, is the entry point for the Simple 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 Simple CMS JavaScript file. The second file, `admin/config.yml`, is the heart of your Simple 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. 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.
@ -49,26 +49,26 @@ In this example, we pull the `admin/index.html` file from a public CDN.
<title>Content Manager</title>
</head>
<body>
<!-- Include the script that builds the page and powers Simple CMS -->
<script src="https://unpkg.com/@simplecms/simple-cms-core@%5E0.1.0/dist/simple-cms-core.js"></script>
<!-- Include the script that builds the page and powers Static CMS -->
<script src="https://unpkg.com/@staticcms/core@%5E0.1.0/dist/static-cms-core.js"></script>
</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/@simplecms/simple-cms-core@%5E0.1.0/dist/simple-cms-core.js`
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/@staticcms/core@%5E0.1.0/dist/static-cms-core.js`
### Installing with npm
You can also use Simple CMS as an npm module. Wherever you import Simple CMS, it automatically runs, taking over the current page. Make sure the script that imports it only runs on your CMS page. First install the package and save it to your project:
You can also use Static CMS as an npm module. Wherever you import Static CMS, it automatically runs, taking over the current page. Make sure the script that imports it only runs on your CMS page. First install the package and save it to your project:
```bash
npm install @simplecms/simple-cms-core --save
npm install @staticcms/core --save
```
Then import it (assuming your project has tooling for imports):
```js
import CMS from '@simplecms/simple-cms-core'
import CMS from '@staticcms/core'
// Initialize the CMS object
CMS.init()
// Now the registry is available via the CMS object.
@ -83,7 +83,7 @@ Configuration is different for every site, so we'll break it down into parts. A
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 Simple CMS `config.yml` file with these lines:
For GitHub and GitLab repositories, you can start your Static CMS `config.yml` file with these lines:
```yaml
backend:
@ -97,7 +97,7 @@ The configuration above specifies your backend protocol and your publication bra
### Media and Public Folders
Simple CMS allows users to upload images directly within the editor. For this to work, the CMS needs to know where to save them. If you already have an `images` folder in your project, you could use its path, possibly creating an `uploads` sub-folder, for example:
Static CMS allows users to upload images directly within the editor. For this to work, the CMS needs to know where to save them. If you already have an `images` folder in your project, you could use its path, possibly creating an `uploads` sub-folder, for example:
```yaml
# This line should *not* be indented
@ -116,7 +116,7 @@ public_folder: "/images/uploads" # The src attribute for uploaded media will beg
The configuration above adds a new setting, `public_folder`. While `media_folder` specifies where uploaded files are saved in the repo, `public_folder` indicates where they are found in the published site. Image `src` attributes use this path, which is relative to the file where it's called. For this reason, we usually start the path at the site root, using the opening `/`.
*If `public_folder` is not set, Simple CMS defaults to the same value as `media_folder`, adding an opening `/` if one is not included.*
*If `public_folder` is not set, Static CMS defaults to the same value as `media_folder`, adding an opening `/` if one is not included.*
### Collections
@ -136,7 +136,7 @@ rating: 5
This is the post body, where I write about our last chance to party before the Y2K bug destroys us all.
```
Given this example, our `collections` settings would look like this in your Simple CMS `config.yml` file:
Given this example, our `collections` settings would look like this in your Static CMS `config.yml` file:
```yaml
collections:
@ -194,7 +194,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](../widgets).
Based on this example, you can go through the post types in your site and add the appropriate settings to your Simple CMS `config.yml` file. Each post type should be listed as a separate node under the `collections` field. See the [Collections reference doc](../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](../configuration-options/#collections) for more configuration options.
### Filter
@ -214,7 +214,7 @@ collections:
## Authentication
Now that you have your Simple CMS files in place and configured, all that's left is to enable authentication. We're using the [Netlify](https://www.netlify.com/) platform here because it's one of the quickest ways to get started, but you can learn about other authentication options in the [Backends](/docs/backends-overview) doc.
Now that you have your Static CMS files in place and configured, all that's left is to enable authentication. We're using the [Netlify](https://www.netlify.com/) platform here because it's one of the quickest ways to get started, but you can learn about other authentication options in the [Backends](/docs/backends-overview) doc.
### Setup on Netlify
@ -265,6 +265,6 @@ If you set your registration preference to "Invite only," invite yourself (and a
If you left your site registration open, or for return visits after confirming an email invitation, access your site's CMS at `yoursite.com/admin/`.
**Note:** No matter where you access Simple 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 Simple 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.
**Note:** No matter where you access Static 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 Static 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!