@@ -74,10 +74,9 @@ There are other commercial options that may update faster because of their archi
## Getting started 💻
This is how you create a **new site powered by cState.** What you are generating is a Hugo site with specific, already existing modifications (to Hugo, cState is a theme).
### — The easy way —
#### 💚 Netlify and Netlify CMS
### 💚 Netlify and Netlify CMS
cState was built to work best with Netlify and comes with the neccesary files to enable Netlify CMS.
...
...
@@ -102,38 +101,49 @@ These are the settings you should be using:
+ Publish directory: **public**
+ Add one build environment variable
+ Key: **HUGO_VERSION**
+ Value: **0.48** (or later)
+ Value: **0.80** (or later)
+ Also **for the Build image selection, pick Ubuntu Xenial 16.04 or later**
### 🧡 Other great hosting and CMS options
#### 🧡 GitLab Pages (Experimental)
The most popular options, apart from Netlify's offers, are:
GitLab Pages, unlike GitHub Pages, supports Hugo, so you can let GitLab build and serve cState without needing to do it on your own machine ([similarly to how you can blog with GitLab Pages from your phone](https://about.gitlab.com/blog/2016/08/19/posting-to-your-gitlab-pages-blog-from-ios/)).
***Hosting:**
* GitHub Pages
* GitLab Pages
* CloudFlare Pages
* Vercel
***Admin panels / CMS:**
* Forestry.io
* Or just use your Git provider (github.com, gitlab.com, etc)
[GitLab has a good guide for getting started with GitLab Pages in their documentation.](https://docs.gitlab.com/ee/user/project/pages/#getting-started)
You can also look at [other headless CMS options **(we use Git-based CMS types)** on jamstack.org](https://jamstack.org/headless-cms/).
**In short: a `.gitlab-ci.yml` file** is responsible for making cState work. As of v4.2.1, the [cState automatically ships with this file](https://github.com/cstate/cstate/releases/tag/v4.2.1).
### GitLab Pages
As of this time, this is a relatively untested option, but Hugo does seem to generate the right things (this can be checked by downloading the **CI/CD artificats**).
Here is a [good guide for getting started with the service.](https://docs.gitlab.com/ee/user/project/pages/#getting-started)
According to GitLab, it may take up to 30 minutes before the site is available after the first deployment.
**In short: a `.gitlab-ci.yml` file** is responsible for making cState work. As of v4.2.1, the [cState automatically ships with this file](https://github.com/cstate/cstate/releases/tag/v4.2.1), but support is still experimental.
You can [make Netlify CMS work on GitLab](https://www.netlifycms.org/docs/gitlab-backend/), but that requires overriding an existing file in the theme. Create a file in `static/admin/config.yml` and follow the instructions linked earlier. (cState by default ships with Git Gateway.)
As of this time, this is a relatively untested option, but Hugo does seem to generate the right things (this can be checked by downloading the **CI/CD artificats**).
According to GitLab, it may take up to 30 minutes before the site is available after the first deployment.
#### 🖤 Other platforms
You can [make Netlify CMS work on GitLab](https://www.netlifycms.org/docs/gitlab-backend/), but that requires overriding an existing file in the theme. Create a file in `static/admin/config.yml` and follow the instructions linked earlier. (cState by default ships with Git Gateway for Netlify.)
Check out [Forestry.io](//forestry.io) and [Vercel](//vercel.com).
### GitHub Pages, CloudFlare Pages, Vercel, Forestry, and others
Keep reading to see how to deploy manually.
There is no official, separate documentation for these, but if you look below to see how to deploy manually, the instructions will be the same everywhere.
### Doing it on your PC
Keep reading to see how to deploy manually. Developers wishing to contribute, scroll to the very bottom.
### — Manual builds —
### Manual builds
For this tutorial, it is assumed that you have Hugo and Git installed (check with `hugo version` & `git --version`).
> A minimum version of `0.48` is required for Hugo, starting with v3.
> A minimum version of `0.80` is required for Hugo, starting with v5.
#### I want to use my site in production
...
...
@@ -161,30 +171,6 @@ And the folder `public` can now be hosted.
The downside with manual building is that, if you do not want to use a solution like GitLab Pages or Netlify, this process will need to happen on your computer. This can be tedious.
hugo serve --baseUrl=http://localhost/ --theme=cstate --themesDir=../.. --verbose
```
The main directory is the theme itself (the cState guts, basically) and the `exampleSite` folder houses all content. Use this local setup to experiment before making a PR.
### — Docker —
cState comes with a Dockerfile and Netlify ([according to their article from 2016](https://www.netlify.com/blog/2016/10/18/how-our-build-bots-build-sites/)) uses a similar Docker system to build cState. This is an option for people who prefer Docker and NGINX instead of serverless, but serverless still has the priority in our development.
...
...
@@ -280,15 +266,37 @@ Check out [the wiki](https://github.com/cstate/cstate/wiki).
## Contribute 💥
**Making a change in the code**
### Making a change in the code
PRs should be submitted to the `dev` branch, if it exists. Before submitting a pull request, create an issue to [discuss the implications of your proposal](https://github.com/cstate/cstate/issues).
hugo serve --baseUrl=http://localhost/ --theme=cstate --themesDir=../.. --verbose
```
The main directory is the theme itself (the cState guts, basically) and the `exampleSite` folder houses all content. Use this local setup to experiment before making a PR.
