Add Sourcing from Flotiq documentation entry

docs/docs/headless-cms.md

@@ -48,6 +48,7 @@ Here are more resources for guides, plugins, and starters for CMS systems you ca
 | [Gentics Mesh](https://getmesh.io)            | [guide](/docs/sourcing-from-gentics-mesh)                                        |                                                      |                                                                    |
 | [Seams-CMS](https://seams-cms.com/)           | [guide](/docs/sourcing-from-seams-cms)                                           |                                                      |                                                                    |
 | [Builder.io](https://www.builder.io/)         | [guide](/docs/sourcing-from-builder-io/)                                         | [docs](/packages/@builder.io/gatsby/)                | [starter](https://github.com/BuilderIO/gatsby-starter-builder)     |
+| [Flotiq](https://flotiq.com/)                 | [guide](/docs/sourcing-from-flotiq/)                                             | [docs](/packages/gatsby-source-flotiq)               | [starter](https://github.com/flotiq/gatsby-starter-blog)           |
 
 ## How to add new guides to this section
 

docs/docs/sourcing-from-flotiq.md

@@ -0,0 +1,182 @@
+---
+title: Sourcing from Flotiq
+---
+
+This guide will help you understand how to setup Gatsby to pull data from [Flotiq](https://flotiq.com).
+
+Flotiq is a headless CMS with a primary focus on developer experience and integration capabilities. Flotiq's cloud-based dashboard allows you to easily design your content types and work with your data, but Flotiq also provides support for powerful integrations. One of Flotiq's key principles is to provide an effortless way to consume your content in the applications you build. It's solved by supporting technologies like OpenAPI 3.0 or Zapier as well as by providing customized API docs and SDK libraries based on your content types.
+
+Using a static website generator, like Gatsby, to consume content stored in Flotiq is one of the most frequent use cases. The integration is based on the [gatsby-source-flotiq](https://github.com/flotiq/gatsby-source-flotiq) source plugin, which bridges the dynamic REST API of your Flotiq account with Gatsby's GraphQL.
+
+> This document will base on the simple [gatsby-starter-blog](https://github.com/flotiq/gatsby-starter-blog) blog starter, but remember to check out the more advanced starters we've prepared to work with Flotiq:
+>
+> - [Recipe website Gatsby starter](https://github.com/flotiq/gatsby-starter-recipes)
+> - [Event calendar Gatsby starter](https://github.com/flotiq/gatsby-starter-event-calendar)
+> - [Project portfolio Gatsby starter](https://github.com/flotiq/gatsby-starter-projects)
+> - [Simple blog Gatsby starter](https://github.com/flotiq/gatsby-starter-blog)
+> - [Gatsby and Snipcart boilerplate, sourcing products from Flotiq](https://github.com/flotiq/gatsby-starter-products)
+> - [Gatsby and Snipcart, e-commerce with products and categories from Flotiq](https://github.com/flotiq/gatsby-starter-products-with-categories)
+
+## Setup
+
+### Quickstart
+
+1. **Start project from template using Gatsby CLI**
+
+   ```bash
+   gatsby new my-blog-starter https://github.com/flotiq/gatsby-starter-blog
+   ```
+
+2. **Setup "Blog Post" Content Type in Flotiq**
+
+   Create your [Flotiq.com](https://flotiq.com) account. Next, create the `Blog Post` Content Type straight from the `Type definitions` page.
+
+   _Note: You can also create `Blog Post` using [Flotiq REST API](https://flotiq.com/docs/API/)._
+
+3. **Configure application**
+
+   The next step is to configure your application to know from where it has to fetch the data.
+
+   You need to create a file called `.env` inside the root project directory, with the following structure:
+
+   ```shell:title=.env
+   GATSBY_FLOTIQ_BASE_URL=https://api.flotiq.com
+   GATSBY_FLOTIQ_API_KEY=YOUR FLOTIQ API KEY
+   ```
+
+4. **Start developing**
+
+   Navigate into your new site’s directory and start it up.
+
+   ```shell
+   cd my-blog-starter/
+   npm install
+   gatsby develop
+   ```
+
+   If you wish to import example blog posts to your account, before running `gatsby develop` run:
+
+   ```shell
+   node ./.flotiq/importExample.js
+   ```
+
+   It will add 1 image and 2 blog posts to your Flotiq account.
+
+   _Note: You need to put your Read and write API key in `.env` for import to work. You don't need Blog Post content type in your account. If you already have posts with ids `blogpost-1` and `blogpost-2` they will be overwritten._
+
+### Source plugin
+
+The Blog starter you've just set up uses the [gatsby-source-flotiq](https://github.com/flotiq/gatsby-source-flotiq) source plugin to pull content from Flotiq.
+
+Here are the steps to use this source plugin in other Gatsby projects:
+
+> If you're using the provided starter - all the following steps have been already taken care of, you can dive into the relevant project files to verify how it's been done.
+
+1. Install the plugin:
+   ```shell
+   npm install --save gatsby-source-flotiq
+   ```
+2. Provide API credentials in `.env`:
+3. Register the source plugin in `gatsby-config.js`:
+   Make sure your `gatsby-config.js` has the following configuration:
+   ```javascript:title=gatsby-config.js
+   module.exports = {
+     // ...
+     plugins: [
+       {
+         resolve: "gatsby-source-flotiq",
+         options: {
+           baseUrl: process.env.GATSBY_FLOTIQ_BASE_URL,
+           authToken: process.env.FLOTIQ_API_KEY,
+         },
+       },
+     ],
+     // ...
+   }
+   ```
+
+By default the source plugin will pull all the data you've stored in Flotiq. In some cases, e.g. when building sites that have thousands of pages - you'll likely want to limit the number of pulled data during development. You can do that either by narrowing down the scope to specific content types or by limiting the number of pulled objects (see the `includeTypes` and `objectLimit` options). The source plugin will do its best to resolve any dependencies for you.
+
+> You can find more details about how to configure the Flotiq source plugin in the [plugin's README](https://github.com/flotiq/gatsby-source-flotiq).
+
+## Accessing Flotiq data in Gatsby
+
+Once you finish configuring your environment you can start developing. The source plugin will pull all the content from your Flotiq account and create respective Gatsby GraphQL nodes. It will also preserve the relations you've setup in Flotiq, so the GraphQL nodes will be automatically linked, just as you would expect.
+
+For example, if you define a relation between `BlogPost` and `Category` content types in Flotiq - they will retain their relationship in Gatsby's GraphQL, so you can retrieve that in a query:
+
+```graphql
+query {
+  allBlogPost {
+    nodes {
+      id
+      slug
+      category {
+        name
+      }
+    }
+  }
+}
+```
+
+The next step is implementing these queries in your `gatsby-node.js`
+
+```javascript:title=gatsby-node.js
+const blogPost = path.resolve(`./src/templates/blog-post.js`)
+const result = await graphql(`
+  query GetBlogPosts {
+    allBlogpost(sort: { fields: flotiqInternal___createdAt, order: DESC }) {
+      edges {
+        node {
+          headerImage {
+            extension
+            id
+          }
+          content
+          id
+          slug
+          title
+        }
+      }
+    }
+  }
+`)
+
+if (result.errors) {
+  throw result.errors
+}
+
+// Create blog posts pages.
+const posts = result.data.allBlogpost.edges
+```
+
+Now the only thing you have to do is let Gatsby create appropriate pages for your Content Objects:
+
+```javascript:title=gatsby-node.js
+posts.forEach((post, index) => {
+  const previous = index === posts.length - 1 ? null : posts[index + 1].node
+  const next = index === 0 ? null : posts[index - 1].node
+
+  createPage({
+    path: post.node.slug,
+    component: blogPost,
+    context: {
+      slug: post.node.slug,
+      previous,
+      next,
+    },
+  })
+})
+```
+
+## Deployment
+
+Once you're finished with your website there are several ways to deploy it. You can use any hosting provider you choose - Netlify, Heroku, AWS S3, Cloudflare, etc.
+
+If you're using Gatsby Cloud - we've provided an integration that allows the to streamline your workflow by providing live updates in preview and push-button deployments.
+
+You can read the relevant [Flotiq Gatsby Cloud integration](https://flotiq.com/docs/panel/Plugins/Gatsby-cloud-integration/) documentation page to learn more.
+
+## Summary
+
+We've gone through the key points of setting up a simple Gatsby starter, configuring it to work with Flotiq and kicking off your development process. Remember to check out other [Flotiq Gatsby starters](https://github.com/flotiq/?q=gatsby-starter) that we've prepared to kick start your next project and come join the [Flotiq Discord channel](https://discord.gg/FwXcHnX) if you need any help!