Merge pull request #25 from clean-commit/next

Release v1.0.0

.env.development

@@ -0,0 +1 @@
+GATSBY_APP_URL="http://localhost:8000"

.env.example

@@ -0,0 +1 @@
+GATSBY_APP_URL=""

.gitignore

@@ -7,6 +7,9 @@ public/
 static/admin/*.bundle.*
 .DS_Store
 yarn-error.log
+.env.*
+!.env.example
+!.env.development
 
 # Local Netlify folder
 .netlify

README.md

@@ -1,30 +1,32 @@
-# Henlo (v0.6.0)
+![Henlo Starter](https://repository-images.githubusercontent.com/270961687/4085d990-9083-451d-b39b-5316579adf09)
+
+# Gatsby Starter Henlo (v1.0.0)
 
 [![Netlify Status](https://api.netlify.com/api/v1/badges/43532afb-3488-432b-8185-a745645a90d8/deploy-status)](https://app.netlify.com/sites/henlo/deploys)
 
-[Official Website / Demo](https://henlo.netlify.app/)
+[Official Website / Demo](http://henlo.cleancommit.io)
 
-**Note:** This starter uses [Gatsby v4](https://www.gatsbyjs.com/blog/gatsby-v4/) with updated `gatsby-plugin-image`.
+Gatsby Starter Henlo is the most advanced Netlify CMS starter for Gatsby.js. We built it with Page Builder setup in mind. All pages are created out of programmable blocks, aiming to provide the best DX & admin UX possible.
 
-This repo contains an example business website that is built with [Gatsby](https://www.gatsbyjs.com/docs/), and [Netlify CMS](https://www.netlifycms.org).
+This repo contains an example website that is built with [Gatsby](https://www.gatsbyjs.com/docs/), and [Netlify CMS](https://www.netlifycms.org).
 
 It follows the [JAMstack architecture](https://jamstack.org) by using Git as a single source of truth, and [Netlify](https://www.netlify.com) for continuous deployment, and CDN distribution.
 
 ## Features
 
-- Battle-tested starting point for small & large web projects
-- Starter for pages and collections CMS configuration with Netlify CMS
-- Easy Netlify CMS configuration using [Manual Initialization](https://www.netlifycms.org/docs/beta-features/#manual-initialization)
-- Built in Tailwind with SCSS and `purge-css-plugin`
-- Built in sitemaps
-- Blazing fast loading times thanks to pre-rendered HTML and automatic chunk loading of JS files
-- Uses `gatsby-plugin-image`
+- 💪 Battle-tested starting point for small & large web projects
+- 📄 Form Builder that enables Admins to create multiple forms with ease & Netlify Forms integration.
+- 🌗 Darkmode support
+- 🗺 Sitemaps using `gatsby-plugin-sitemap`
+- 🔥 Perfect score on Lighthouse for SEO, Accessibility and Performance
+- 💇‍♀️ TailwindCSS support with PostCSS processing & PurgeCSS
+- 🔌 Support for Gatsby API functions
+- 🎇 Crazy fast images with `gatsby-plugin-image`
+- 🕵️‍♂️ Complete SEO configuration with graphql fragment and reusable components
 - Netlify deploy configuration
-- Netlify function support, see `lambda` folder
-- Support for async Netlify forms
-- Complete SEO configuration with graphql fragment and reusable components
-- Perfect score on Lighthouse for SEO, Accessibility and Performance (wip:PWA)
+- Example pages, collections, CMS configuration with Netlify CMS & hooks
 - Readme template for custom projects
+- Easy Netlify CMS configuration using [Manual Initialization](https://www.netlifycms.org/docs/beta-features/#manual-initialization)
 - ..and more
 
 ## Prerequisites
@@ -35,7 +37,7 @@ It follows the [JAMstack architecture](https://jamstack.org) by using Git as a s
 
 ## Getting Started (Recommended)
 
-Netlify CMS can run in any frontend web environment, but the quickest way to try it out is by running it on a pre-configured starter site with Netlify. The example here is the Kaldi coffee company template (adapted from [Gatsby Starter Netlify CMS](https://github.com/netlify-templates/gatsby-starter-netlify-cms)). Use the button below to build and deploy your own copy of the repository:
+Netlify CMS can run in any frontend web environment, but the quickest way to try it out is by running it on a pre-configured starter site with Netlify. Use the button below to build and deploy your own copy of the repository:
 
 <a href="https://app.netlify.com/start/deploy?repository=https://github.com/clean-commit/gatsby-starter-henlo"><img src="https://www.netlify.com/img/deploy/button.svg" alt="Deploy to Netlify"></a>
 
@@ -56,19 +58,18 @@ Pulldown a local copy of the Github repository Netlify created for you, with the
 ```
 $ git clone https://github.com/[GITHUB_USERNAME]/[REPO_NAME].git
 $ cd [REPO_NAME]
-$ yarn
-$ netlify dev
+$ yarn && yarn start
 ```
 
-This uses the new [Netlify Dev](https://www.netlify.com/products/dev/?utm_source=blog&utm_medium=netlifycms&utm_campaign=devex) CLI feature to serve any functions you have in the `lambda` folder.
-
-To test the CMS locally, you'll need run a production build of the site:
+To test the CMS locally, you'll need run a production build of the site & [run local instance of Netlify CMS](https://www.netlifycms.org/docs/beta-features/#working-with-a-local-git-repository)
 
 ```
-$ yarn build
-$ netlify dev # or ntl dev
+$ yarn start
+$ npx netlify-cms-proxy-server
 ```
 
+Your admin configuration will be available at http://localhost:8000/admin
+
 ### Deployment
 
 We've added additional commands for quick deployments with Netlify CLI. To deploy the website to netlify cms simply run.
@@ -79,93 +80,165 @@ $ yarn deploy:prod
 
 The website will build locally and then deploy to production.
 
+### Folder structure
+
+```
+├── cms                      # Netlify CMS configuration
+│   ├── blocks
+│   ├── collections
+│   ├── fields
+│   ├── previews
+│   └── cms.js
+├── content                  # Your content lives here
+│   ├── authors
+│   ├── blog
+│   ├── forms
+│   ├── pages
+│   └── dont-remove.md
+├── public
+├── src
+│   ├── api                  # Gatsby functions should be placed here
+│   ├── blocks               # Blocks that create sections
+│   ├── components           # Reusable components
+│   ├── hooks                # Hooks used in the project
+│   ├── lib                  # misc
+│   ├── pages
+│   ├── resolvers
+│   │   ├── Image.js         # Required for previews
+│   │   └── Link.js          # Resolves links to gatsby and outside links
+│   ├── settings             # Place for theme settings
+│   ├── styles
+│   └── templates            # Templates used to render page types
+│       ├── page-builder.js
+│       └── post.js
+├── static
+├── _headers
+├── gatsby-config.js         # Config files for gatsby
+├── gatsby-node.js           # Page generation setup
+└── tailwind.config.js       # Tailwind configuration
+```
+
 ### Setting up the CMS
 
 Follow the [Netlify CMS Quick Start Guide](https://www.netlifycms.org/docs/quick-start/#authentication) to set up authentication, and hosting.
 
+CMS configuration was placed within `cms` directory in the root of the project. This allows us to work efficiently on fields and collections without mixing CMS config with Gatsby code.
+
 Henlo uses Manual Initialization to take advantage of componetized approach to managing configuration for Netlify CMS. Thanks to that you don't have to control the CMS from centralized YAML file.
 
+To ensure best experience we use 2 custom widgets that are maintained by us -> [ID Widget](https://github.com/clean-commit/netlify-cms-widget-id) that provides unmutable IDs for content items and [Permalink Widget](https://github.com/clean-commit/netlify-cms-widget-permalink) that enables you to create custom permalinks with ease.
+
 ```javascript
 import CMS from 'netlify-cms-app';
-import pages from '@/cms/pages';
-import posts from '@/cms/collections/posts';
+import { Widget as UuidWidget } from 'netlify-cms-widget-id';
+import { Widget as PermalinkWidget } from 'netlify-cms-widget-permalink';
+
+import pages from './collections/pages';
+import posts from './collections/posts';
+import authors from './collections/authors';
+import settings from './collections/settings';
+import PagePreview from './previews/Page'; // Preview for all PageBuilder based pages
 
 window.CMS_MANUAL_INIT = true;
 
-CMS.init({
+const config = {
   config: {
     load_config_file: false,
+    display_url: process.env.GATSBY_APP_URL, // Enables urls based on env variable
+    local_backend: true,
     backend: {
       name: 'git-gateway',
-      branch: 'master',
+    },
+    slug: {
+      encoding: 'ascii',
+      clean_accents: true,
     },
     media_folder: '/static/img',
     public_folder: '/img',
-    collections: [pages, posts],
+    collections: [pages, posts, authors, settings],
   },
-});
+};
+
+CMS.registerPreviewStyle('../commons.css');
+CMS.registerPreviewTemplate('pages', PagePreview);
+
+CMS.registerWidget(UuidWidget);
+CMS.registerWidget(PermalinkWidget);
+
+CMS.init(config);
 ```
 
-#### Example configuration for Home Page
+#### Adding blocks
+
+Blocks are defined in `cms/blocks/index.js` file. We're leveraging use of exported functions and variables from other fields to avoid repetition within the code.
+
+This is extremely important due to the way GraphQL works with Markdown based files. Each field will have to be present on all page queries -> we can't differetiate between different sections.
+
+That's why it's important to reuse names of fields, hence usage of imports.
 
 ```javascript
-import seo from '@/cms/partials/seo';
+import { Buttons, Title, Content, VariantField, ImageField } from '../fields';
 
-const page = {
-  file: 'content/pages/home.md',
-  label: 'Home',
-  name: 'Home',
-  fields: [
-    {
-      label: 'Layout',
-      name: 'layout',
-      widget: 'hidden',
-      default: 'index',
-    },
-    {
-      label: 'Type',
-      name: 'type',
-      widget: 'hidden',
-      default: 'page',
-    },
+const Config = {
+  label: 'Blocks',
+  name: 'blocks',
+  widget: 'list',
+  types: [
     {
-      label: 'Title',
-      name: 'title',
-      widget: 'string',
-      default: '',
-      required: false,
-    },
-    {
-      label: 'Links',
-      name: 'links',
-      widget: 'list',
+      label: 'Hero',
+      name: 'hero',
+      widget: 'object',
       fields: [
-        {
-          label: 'Link',
-          name: 'link',
-          widget: 'object',
-          fields: [
-            {
-              label: 'Content',
-              name: 'content',
-              widget: 'string',
-              required: false,
-            },
-            {
-              label: 'URL',
-              name: 'url',
-              widget: 'string',
-              required: false,
-            },
-          ],
-        },
+        Title,
+        Content,
+        Buttons,
+        VariantField('default', ['default', 'centered', 'full']),
       ],
     },
-    seo,
-  ],
-};
+...
+```
+
+To add new block you have tp add new `Type` to `cms/blocks/index.js` file, and modify `Blocks` fragment located in `src/components/PageBuilder.js`
 
-export default page;
+As you can see below we're adding all fields used by all sections. This causes issues with Gatsby's [Schema Inference](https://www.gatsbyjs.com/docs/schema-inference/). Gatsby needs an example of the field to know what type of field it is.
+
+That's why we rely on `dont-remove.md` this file contains all possible fields used in the starter, so you're never encounter a problem with types inference!
+
+```
+export const query = graphql`
+  fragment Blocks on MarkdownRemarkFrontmatter {
+    blocks {
+      type
+      title
+      content
+      columns {
+        title
+        content
+      }
+      photo {
+        image {
+          childImageSharp {
+            gatsbyImageData(
+              width: 800
+              quality: 72
+              placeholder: DOMINANT_COLOR
+              formats: [AUTO, WEBP, AVIF]
+            )
+          }
+        }
+        alt
+      }
+      variant
+      buttons {
+        button {
+          content
+          url
+          variant
+        }
+      }
+    }
+  }
+`
 ```
 
 ### Adding Favicons
@@ -185,20 +258,6 @@ yarn preload-fonts
 
 Gatsby tends to add a lot of polyfills to support older browser versions. In package.json file you can adjust which sites your project should support. As default Henlo will use `defaults` setting. If you want to learn more about the browser support visit official [Gatsby How-To Guide on this subject](https://www.gatsbyjs.com/docs/how-to/custom-configuration/browser-support/)
 
-## Debugging
-
-Windows users might encounter `node-gyp` errors when trying to npm install.
-To resolve, make sure that you have both Python 2.7 and the Visual C++ build environment installed.
-
-```
-npm config set python python2.7
-npm install --global --production windows-build-tools
-```
-
-[Full details here](https://www.npmjs.com/package/node-gyp 'NPM node-gyp page')
-
-MacOS users might also encounter some errors, for more info check [node-gyp](https://github.com/nodejs/node-gyp). We recommend using the latest stable node version.
-
 ## PurgeCSS
 
 This plugin uses [gatsby-plugin-purgecss](https://www.gatsbyjs.org/packages/gatsby-plugin-purgecss/) and [Tailwind](https://tailwindcss.com/). The builds are usually ~780K but reduced 98% by purgecss. Normally our websites won't cross 30Kb of CSS.