Skip to content

Latest commit

 

History

History
192 lines (128 loc) · 8.03 KB

README.md

File metadata and controls

192 lines (128 loc) · 8.03 KB
Raw

Agility CMS & Gatsby Starter

This is sample Gatsby starter site that uses Agility CMS and aims to be a foundation for building fully static sites using Gatsby and Agility CMS.

Live Website Demo

New to Agility CMS? Sign up for a FREE account

About This Starter

  • Uses Gatsby V3 - The latest version of Gatsby’s core framework which introduces massive improvement to the developer and user experience.
  • Uses AgilityImage - A custom image component utilizing the new Gatsby Image Plugin that take's images stored within Agility CMS and handles all of the hard parts of displaying responsive images that follow best practices for performance on your website or application.
  • Uses gatsby-source-agilitycms - Our official Gatsby plugin that will only refresh content that has changed since your last build, so you can rest easy your builds will be fast, regardless of how many pages you have.
  • Supports full Page Management.
  • Supports Preview Mode.
  • Provides a functional structure that loads a Page Templates dynamically, and also dynamically loads and renders appropriate Agility CMS Page Modules (as React components).

Tailwind CSS

This starter uses Tailwind CSS, a simple and lightweight utility-first CSS framework packed with classes that can be composed to build any design, directly in your markup.

It also comes equipped with Autoprefixer, a plugin which use the data based on current browser popularity and property support to apply CSS prefixes for you.

Getting Started

To start using the Agility CMS & Gatsby Starter, sign up for a FREE account and create a new Instance using the Blog Template.

  1. Clone this repository
  2. Run npm install or yarn install
  3. Rename the .env.development.example file to .env.development
  4. Retrieve your GUID & API Keys (Preview/Fetch) from Agility CMS by going to Settings > API Keys.

How to Retrieve your GUID and API Keys from Agility

Running the Site Locally

Development Mode

When running your site in development mode, you will see the latest content in from the CMS.

yarn

  1. yarn install
  2. yarn start or gatsby develop

npm

  1. npm install
  2. npm run start or gatsby develop

To clear your content cache locally, run gatsby clean

Production Mode

When running your site in production mode, you will see the published from the CMS.

yarn

  1. yarn build or gatsby build
  2. yarn serve or gatsby serve

npm

  1. npm run build or gatsby build
  2. npm run start or gatsby serve

Deploying Your Site

The easiest way to deploy a Gatsby website to production is to use Gatsby Cloud from the Gatsby team. Gatsby Cloud is a platform that gives your Gatsby website superpowers! With intelligent caching and incremental builds, Gatsby Cloud takes the speed and performance of your Gatsby website to another level.

Deploy your site to Gatsby Cloud

Notes

How to Register Page Modules

  1. To create a new Page Module, create a new React component within the src/components/agility-pageModules directory.
  2. All of the Page Modules that are being used within the site need to be imported into the index file within the src/components/agility-pageModules directory and added to the allModules array:
import RichTextArea from "./RichTextArea";
import FeaturedPost from "./FeaturedPost";
import PostsListing from "./PostsListing";
import PostDetails from "./PostDetails";
import Heading from "./Heading";
import TextBlockWithImage from "./TextBlockWithImage";

const allModules = [
  { name: "TextBlockWithImage", module: TextBlockWithImage },
  { name: "Heading", module: Heading },
  { name: "FeaturedPost", module: FeaturedPost },
  { name: "PostsListing", module: PostsListing },
  { name: "PostDetails", module: PostDetails },
  { name: "RichTextArea", module: RichTextArea },
];

How to Register Page Templates

  1. To create a new Page Template, create a new React component within the src/components/agility-pageTemplates directory.
  2. All of the Page Template that are being used within the site need to be imported into the index file within the src/components/agility-pageTemplates directory and added to the allTemplates array:
import MainTemplate from "./MainTemplate";

const allTemplates = [
  { name: "MainTemplate", template: MainTemplate }
];

How to Properly Link to an Internal Page

To link to internal pages, use the Link component from gatsby.

import { Link } from 'gatsby';

// where post.path is the url path 
<Link to={post.path}>
  {post.title}
</Link>

Resolving Linked Content

In the agilitycms-gatsby-starter, we resolve Linked Content by using Gatsby Resolvers.

Resolvers are added to your gatsby-node.js in your site, and they allow you to add a new field to your content node which will handle resolving your Linked Content reference.

This means you are telling GraphQL, when you query a specific property on a node, it will actually run a function to go and get your Linked Content and return it.

An example of this can be found here in this starter site:

// gatsy-node.js

const agility = require('./src/agility/utils')

  const resolvers = {
    // on the 'agilityPost' node type
    agilityPost: {
      // get the sitemap node that represents this item ( i.e. /blog/my-blog-post )
      sitemapNode: agility.getDynamicPageItemSitemapNode(),

      // get the category
      linkedContent_agilityCategory: agility.getLinkedContentItem({
        type: "agilityCategory",
        linkedContentFieldName: "category",
      }),
    },
  }
  createResolvers(resolvers)
}

How to Resolve Linked Content

Previewing Content

Previewing content prior to publishing is crucial for Editors. You can set up and configure Previews to work with Gatsby Cloud so editors can preview content as their making edits within Agility CMS.

Set up Preview with Gatsby Cloud

Resources

Agility CMS

Gatsby

Gatsby Cloud

Tailwind CSS

Community

Feedback and Questions

If you have feedback or questions about this starter, please use the Github Issues on this repo, join our Community Slack Channel or create a post on the Agility Developer Community.