How to use this theme

June 08, 2020

Use this theme

how to

acme

gatsby

Let's say that you want to start this theme from a blank canvas. For me the easiest way is to follow the below steps:

Create a package.json file in a particular folder;
You will need to run npm install or yarn;
After that you can start the configuration of your theme;
Run npm run develop or yarn develop... and get an error(for now);
Your site need content;

Package.json

In the root of your selected folder you will be creating your package.json file as follows:

{
  "name": "amce",
  "author": "Tiago Sanchez",
  "main": "index.mdx",
  "license": "MIT",
  "dependencies": {
    "gatsby": "^2.22.15",
    "gatsby-theme-acmeblog": "^1.0.0",
    "react": "^16.4.0",
    "react-dom": "^16.4.0"
  },
  "scripts": {
    "develop": "gatsby develop",
    "clean": "gatsby clean",
    "build": "gatsby build",
    "serve": "gatsby serve"
  }
}

Npm install or yarn

This will install all the packages that you will need into your folder and you will need to run this command in your terminal.

Configuration

There are a couple of things that you will need to consider:

The theme options;
Basic site data configuration;
Using Mdx

It is also important to note that at the moment the slugs are the name of the MDX file.

Theme options

key	default value	description
`blogPath`	`/blog`	defines the url (slug) for the blog posts overview page
`postsContentPath`	`content/posts`	location of all the posts files
`postsContentThumbnail`	`content/images`	location of all the thumbnails images used in the posts
`pagesContentPath`	`content/pages`	location of other pages that you would like to build using `mdx`
`otherImagesContentPath`	`images`	location for any other images that you would like to post in your
`tagsPath`	`/tags`	defines the url (slug) for all existing tags, shown in a overview tags page and used for listing all posts with a certain tag (prepending it to the tag itself, e.g. `/blog/tags/yourtag`)
`categoryPath`	`/category`	defines the url (slug) used for listing all posts with a certain category (prepending it to the category itself, e.g. `/blog/category/yourcategory`)
`postTableOfContents`	`false`	If you would like to have a table of contents in your posts page change it to `true`

How to use theme options

In gatsby-config.js you will be able to define the options

module.exports = {
  plugins: [
    {
      resolve: "gatsby-theme-acmeblog-data",
      options: {
        blogPath: "/anything", // the default will be /blog
        tagsPath: "/mytags", // the default will be /tags
        categoryPath: "/mycategory", // the default will be /category
        postsContentPath: "myblog/posts", // the default will be content/posts
        pagesContentPath: "myblog/pages", // the default will be content/pages
        otherImagesContentPath: "mysuperimages", // the default will be images
        postTableOfContents: true, //the default is false
      },
    },
  ],
};

Additional configuration

In addition to the theme options the siteMetadata object is extremely useful. In our gatsby-config.js you will have the following:

siteMetadata: {
    siteTitle: `ACME`,
    siteTitleAlt: `Simple Blog - @tfs/gatsby-theme-acmeblog`,
    siteHeadline: `Simple Blog - Gatsby Theme from tiagofsanchez`,
    // siteUrl: ``,
    siteDescription: `A blogging theme with small aesthetics. Includes tags and categories support`,
    siteLanguage: `en`,
    siteImage: `./images/logo.png`,
    author: `tiagofsanchez`,
    navigation: [
      {
        title: `blog`,
        slug: `/blog`,
      },
      {
        title: `about`,
        slug: `/about`,
      },
    ],
    externalLinks: [
      {
        name: `LinkedIn`,
        url: `https://www.linkedin.com/in/tiagofsanchez/`,
      },
      {
        name: `Twitter`,
        url: `https://twitter.com/tiagofsanchez`,
      },
    ],
  },

Overall example

Example being used

module.exports = {
    siteMetadata: {
      siteTitle: `ACME`,
      siteTitleAlt: `Simple Blog - gatsby-theme-acmeblog`,
      siteHeadline: `Simple Blog - gatsby theme from tiagofsanchez`,
      // siteUrl: ``,
      siteDescription: `A blogging theme with small aesthetics. Includes tags and categories support`,
      siteLanguage: `en`,
      siteImage: `./images/logo.png`,
      author: `tiagofsanchez`,
      navigation: [
        {
          title: `blog`,
          slug: `/blog`,
        },
        {
          title: `about`,
          slug: `/about`,
        },
      ],
      externalLinks: [
        {
          name: `LinkedIn`,
          url: `https://www.linkedin.com/in/tiagofsanchez/`,
        },
        {
          name: `Github`,
          url: `https://github.com/tiagofsanchez`,
        },
      ],
    },
      plugins: [
        {
          resolve: "gatsby-theme-acmeblog",
          options: {
            postTableOfContents: true,
          },
        },
      ],
    };

How to use Mdx for your posts

Url (slug) of your posts

This will be automatically generated for you and it will be the name of the mdx file created

The frontmatter will need to have the following structure

---
title: "How to use this theme"
date: "2020-06-08"
category: Use this theme
tags:
  - how to
  - acme
  - gatsby
---

title - will be the title of the blog post
date - will be the date that will be shown in the blog post;
category - defines the category of this post
tags - the tags that you want this particular post to have
thumbnail - in case you want to give the post a thumbnail

Tim for running your side

Now you can run npm run develop or yarn develop to get an error :(. Sorry about that. The problem here is that we need content for all the magic to happen.

Add your content

Assuming that you are using all the defaults from the theme, you will need to add posts, pages and images (dummy for now) into content/posts, content/pages and content/images

Eh voila! Now you can start to create great content!

If you think you are ready and want deploy your site you can follow gatsby documenation

Hope this was usefull.

Package.json
Npm install or yarn
Configuration
Tim for running your side
Add your content