Crafting posts, snippets and complex page navigation

ACT is a starter to create blogs, documentation, or e-learning websites. Just edit markdown files, or use MDX to quickly create formated, user interactive pages without any programming skills, or complex visual designers. As ACT is a Gatsby starter, all the power of Gatsby plugin system is at your disposal (optimized images, SEO, etc), as well as Ant Design, webpack, Babel, etc. These interesting and important topics are left for other blog posts though (see, for example, more in depth article about complex page development). Here we concentrate on installation/usage, general project structure and main ACT page types.

Installation

ACT is a Gatsby starter, which means node.js must be already present.

# install a Gatsby CLI globally (if not already installed)
npm install -g gatsby-cli

# create a new blog site using an ACT starter 
gatsby new my-blog-name https://github.com/act-labs/gatsby-starter-act-blog

# change to the newly created project directory
cd my-blog-name

# install all dependencies
npm install

Pages

ACT provides tools to create cross referenced entries, convenient for documentation, e-learning, and other websites describing closely related items. To accomplish this, two main page types are provided: posts and snippets. Snippets are short write-ups (for example, short code excerpts), grouped by subjects for quick reference. They are for readers, who already know the subject well enough, but wish to review/quickly look up information. Posts are fully fledged articles, often referencing/embedding relevant snippets. Just interactively edit/preview markdown documents using your favorite text editor.

To edit posts, go to src/content/posts. Posts are ordinary MDX files. Which means they are basically markdown documents with embedded JSX and configuration information (a JS object) in the beginning (in the form of a frontmatter section).

---
title:  The frontmatter field containing a post title
keywords: used for SEO
order: 20 (a number influencing document position in lists )
---

## Some post

As posts are MDX documents, they may contain not only markdown, but also embedded JSX components. Using such components, for example, one can embed a chart, data table, quiz popup, or just split text into separate tabs. MDX documents themselves are React components, and hence, for example, snippets could be embedded in posts (or other snippets as well):

import Chart from 'content/snippets/main/chart'

........

<Chart/>

Snippets are located in src/content/snippets subdirectories (each subdirectory is a snippet collection). They are ordinary MDX files. Snippets are organized into collections. Every snippet collection comes with a *.yaml configuration file of the same name as the corresponding collection directory. Within collections, snippets are also divided into groups. Snippet pages have a two level sidebar menu (group/name) for quick navigation.

---
title:  The frontmatter field containing a snippet title
keywords: used for SEO
menu: group name/snippet name (slash separated group and snippet names)
---

Some snippet content

# a sidebar menu (snippet groups)
menu:
  - text: group name 1
    icon: group icon 1
  - text: group name 2
    icon: group icon 2

Complex singleton pages (e.g., the main site page, posts index, etc.) are located in the src/content/pages directory. Files from this directory correspond to root pages (pages/page.md maps to the /page/ URL, pages/index.md maps to /, etc.). To edit these pages, modifications to React components or helper node.js modules could be required. For more information about helper modules see gatsby-plugin-combine and source code.

Ordinary Gatsby pages (for example, pure React components or simple MDX documents) could be created in the standard Gatsby src/pages directory. See a Hello Antd page in the src/pages/examples/ directory. For more information see ACT directory tree structure.

Usage

To start ACT development, Gatsby development server must be started in the ACT project home directory. After which posts and snippets could be edited/added. Modifications could be previewed live in a browser. After site updates are done and tested, static pages could be built and examined/served (tested) from the public directory.

# start a development server
gatsby develop

# clean ".cache" and "public" directories
gatsby clean

# build all pages
gatsby build

# serves pages from the site build (from the directory "public")
gatsby serve

Deployment

After the build, a public directory containing all static resources could be deployed to any web hosting. The Gatsby website contains detailed instructions how to deploy builds to the most popular hosting providers. As they are quite similar and simple. For example, lets consider GitHub Pages, which is a free static website hosting from a leading version control service based on Git. The simplest way to deploy to GitHub Pages is to use a gh-pages package.

# add a gh-pages package
npm install gh-pages --save-dev

// package.json
    {
        "scripts": {
            ...
            "deploy": "gatsby build && gh-pages -d public -b master",
        }
    }

// package.json
    {
        "scripts": {
            ...
            "deploy": "gatsby build --prefix-paths && gh-pages -d public -b master",
        }
    }

// gatsby-config.js
module.exports = {
    pathPrefix: "/reponame",
}