Gatsby Chronoblog

by Ivan Ganev

Chronoblog is a Gatsbyjs theme specifically designed to create a personal website. The main idea of Chronoblog is to allow you not only to write a personal blog but also to keep a record of everything important that you have done.

Chronoblog is a Gatsby js theme specifically designed to create a personal website.

The main idea of Chronoblog is to allow you not only to write a personal blog but also to keep a record of everything important that you have done.

I never liked the blog format so that, regardless of the platform (be it Medium or WordPress), they all expect that the content that I will create is text, and this should be a long article. A blog consisting of long articles looks and works organically (on any platform). But a blog consisting of any other content (video, presentations, links to articles on other sites, or even just short notes) - it feels and works "somehow wrong".

Many people solve this problem like this - create separate pages on their website for a blog, for talks, for podcasts, for a portfolio, etc. But it is difficult to maintain and update.

But what if we make a blog theme based on a feed? Something like twitter or hackernews or reddit, but without restrictions, and in the form of a personal blog?

Chronoblog is a theme that allows you to do just that - create a more universal personal website.

Despite the fact that versions start with "0.", I want to make the Chronoblog API as stable as possible.

Gatsby Starter Chronoblog

This starter is the standard way to start a Chronoblog Gatsby Theme website.

Demo: chronoblog.now.sh
Repo: github.com/Chronoblog/gatsby-starter-chronoblog

Gatsby Starter Chronoblog Profile

This starter will help you launch a personal website with a simple text feed on the main page.

Demo: chronoblog-profile.now.sh
Repo: github.com/Chronoblog/gatsby-starter-chronoblog-profile

Gatsby Starter Chronoblog Hacker

A dark (but with ability to switch to light) starter that uses the Source Code Pro font and minimalistic UI (without emoji, as by default in Chronoblog Theme).

Demo: chronoblog-hacker.now.sh
Repo: github.com/Chronoblog/gatsby-starter-chronoblog-hacker

Examples

Examples are the same standard starter, but with some additional features. You can use the example to start your site or see how this feature was added.

Chronoblog with Disqus comments | Repo | Demo
Chronoblog with Netlify CMS | Repo | Demo

Use one of the starters as the basis for your unique site

To make your website look unique, you first need to work with the file src/gatsby-plugin-theme-ui/index.js with which you can control the style of the entire site. Basically, starters look different because of the different settings of this file. More about it here: Style settings.

Also, all starters have a different main page, src/pages/index.mdx and content. Read about all this below in the guide.

Guide - How to start working with Chronoblog Gatsby Theme
Documentation
Status
- GitHub Workflows
Feedback
Contribute
- Contribution to the README.md
Credits
- Art

This guide will show how to create a personal website using Gatsby Theme Chronoblog.

To create a website using the Chronoblog theme, you do not need to be an expert in using Gatsbyjs. However, it’s still recommended that you complete the basic tutorial: Gatsby.js Tutorials

Installation and Development

In this guide, we will set up our new site using this starter: gatsby-starter-chronoblog

If you have gatsby-cli:

gatsby new chronoblog-site https://github.com/Chronoblog/gatsby-starter-chronoblog

cd chronoblog-site

gatsby develop

Or using git clone:

git clone git@github.com:Ganevru/gatsby-starter-chronoblog.git chronoblog-site

cd chronoblog-site

npm i

npm start

Your site is now running at http://localhost:8000

You can start developing your site.

If you want to use some other starter for Chronoblog, for example, a Profile Starter, just install it according to the instructions from its readme, or just change the name during installation to:
gatsby new chronoblog-site https://github.com/Chronoblog/gatsby-starter-chronoblog-profile
or, if using git clone:
git clone git@github.com:Ganevru/gatsby-starter-chronoblog-profile.git chronoblog-site.

Folder structure

Here's how the Chronoblog Starter is organized:

chronoblog-site
  ├─ content // unique site content is located here
  │  ├─ links // content type - link cards
  │  ├─ notes // content type - note cards
  │  └─ posts // content type - blog posts
  ├─ gatsby-config.js
  ├─ package.json
  ├─ src
  │  ├─ assets
  │  ├─ gatsby-plugin-theme-ui // style of the site
  │  │  └─ index.js
  │  ├─ gatsby-theme-chronoblog // chronoblog shadow
  │  │  ├─ post-footer.mdx // what comes after every blog post
  │  │  ├─ site-footer.mdx // site footer
  │  │  └─ site-header.mdx // where is the main menu of the site
  │  └─ pages // pages of the site
  │     ├─ index.mdx // the main page of the site
  │     └─ projects.mdx // optional site page
  └─ static
     └─ robots.txt

Below will be more explanation about various aspects of the site.

Gatsby Config

gatsby-config.js located in the root of your site and looks like this:

module.exports = {
  siteMetadata: {
    siteTitle: 'Chronoblog Starter',
    siteDescription: 'Starter for Gatsby Theme Chronoblog',
    siteImage: '/banner.png', // main image of the site for metadata
    siteUrl: 'https://chronoblog.now.sh/',
    pathPrefix: '/',
    siteLanguage: 'en',
    ogLanguage: `en_US`,
    author: 'Site Author', // for example - 'Ivan Ganev'
    authorDescription: 'short author description', // short text about the author
    avatar: '/avatar.jpg',
    twitterSite: '', // website account on twitter
    twitterCreator: '', // creator account on twitter
    social: [
      {
        icon: `envelope`,
        url: `mailto:mymail@mail.com`
      },
      {
        icon: `twitter`,
        url: `https://twitter.com/ganevru`
      },
      {
        icon: `github`,
        url: `https://github.com/Chronoblog/gatsby-theme-chronoblog`
      },
      {
        icon: `node-js`,
        url: `https://www.npmjs.com/package/gatsby-theme-chronoblog`
      }
    ]
  },
  plugins: [
    {
      resolve: 'gatsby-theme-chronoblog',
      options: {
        uiText: {
          // ui text fot translate
          feedShowMoreButton: 'show more',
          feedSearchPlaceholder: 'search',
          cardReadMoreButton: 'read more →',
          allTagsButton: 'all tags'
        },
        feedItems: {
          // global settings for feed items
          limit: 50,
          yearSeparator: true,
          yearSeparatorSkipFirst: true,
          contentTypes: {
            links: {
              beforeTitle: '🔗 '
            }
          }
        },
        feedSearch: {
          symbol: '🔍'
        }
      }
    },
    {
      resolve: `gatsby-plugin-manifest`,
      options: {
        name: `Chronoblog Gatsby Theme`,
        short_name: `Chronoblog`,
        start_url: `/`,
        background_color: `#fff`,
        theme_color: `#3a5f7d`,
        display: `standalone`,
        icon: `src/assets/favicon.png`
      }
    },
    {
      resolve: `gatsby-plugin-sitemap`
    },
    {
      resolve: `gatsby-plugin-google-analytics`,
      options: {
        // replace "UA-XXXXXXXXX-X" with your own Tracking ID
        trackingId: 'UA-XXXXXXXXX-X'
      }
    }
  ]
};

This is the standard file for the gatsby starter.

Site Metadata

In siteMetadata, replace information about:

siteTitle - The main name of your site, if this is your personal site, you can simply write your name.

siteDescription - description of the website.

siteImage - image for metadata. Default: static/banner.png - you can simply replace this image with your own.

siteUrl - a domain where the site will be located. Example: https://chronoblog.now.sh.

author - the author of the site. For information at the end of each blog post, as well as for site metadata. Just write your name.

authorDescription - short description of the author. For example, "web developer", "designer", "front-end engineer" and so on.

avatar - author avatar. The file is located here: static/avatar.jpg. Replace this file with yours. It is recommended to use image with a resolution of 1:1 (the size of the default picture - 300x300).

twitterSite - twitter account of this site. Needed for twitter metadata.

twitterCreator - same as twitterSite, but for the author.

social - your social networks. List the links to your social networks in the format presented. All of them will be automatically used in the SocialLinks component (in this starter this is the main menu, footer and the author banner).

url - link to your social network profile. In general, it can be a link anywhere.
icon - name of the icon of this social network. Icons use brand icons from fontawesome.com/icons?d=gallery&s=brands - most likely, there are icons for any site on which you have a profile. Additionally you can use icons at and envelope (a good option if you want to place a link to your email) and phone.

favicon

Thanks to the plugin gatsby-plugin-manifest, you can use one image as an icon (including favicon) for all devices. Just replace src/assets/favicon.png image with your own. It is better to use the size of 512x512.

Global settings

In options for gatsby-theme-chronoblog you can find various global settings.

uiText - Here you can replace the default values of the UI of the elements of the Chronoblog. This is done to simplify the localization of the site in various languages. If your site is in English, you can leave it as it is. If the site will use any other language - translate the default values right here.

feedItems - global options for feedItems component. Inside any feedItems component on the site, you can specify other settings. Settings that are set through props are always in priority.

feedSearch - global options for feedSearch component.

Plugins

All other plugins are optional. Chronoblog does not rely on them, so if you do not need, say, gatsby-plugin-google-analytics, you can ignore it or remove it from the list of plugins.

And of course, you can use any other plugins. Gatsby Plugin Ecosystem: www.gatsbyjs.org/plugins

Style settings

Chronoblog allows you to change many style settings of the site. You can change the primary and secondary colors, fonts, border-radius of most elements, etc. All this happens thanks to the Theme-UI library.

Browse to the /src/gatsby-plugin-theme-ui/index.js file. This file already exists in the starter.

This file looks like this:

import chronoblogTheme from 'gatsby-theme-chronoblog/src/gatsby-plugin-theme-ui';

export default {
  ...chronoblogTheme,
  initialColorMode: 'light',
  colors: {
    ...chronoblogTheme.color,
    text: '#222',
    background: '#fff',
    link: '#3d7e9a',
    primary: '#3a5f7d',
    secondary: '#5a809e',
    muted: '#dae1e3',
    modes: {
      ...chronoblogTheme.colors.modes,
      dark: {
        ...chronoblogTheme.colors.modes.dark,
        text: '#eaeaea',
        background: '#0e0f17',
        muted: '#161b1d'
      }
    }
  },
  fontSizes: [14, 16, 18, 20, 22, 24, 28, 36],
  borderRadius: {
    ...chronoblogTheme.borderRadius,
    card: 6,
    button: 6,
    search: 6,
    code: 6,
    img: 6,
    authorBanner: 6
  },
  borderWidth: {
    ...chronoblogTheme.borderWidth,
    card: 2,
    search: 2
  },
  fonts: {
    ...chronoblogTheme.fonts,
    body: '-apple-system,BlinkMacSystemFont,Helvetica,Arial,sans-serif',
    heading: 'inherit',
    monospace: 'Menlo, monospace'
  }
};

In general, this file explains itself. The easiest way to understand what and how it works is simply to “play” with it. Try changing the primary and secondary colors, double the rounding of all elements, and so on.

initialColorMode - here you can select the starting color mode of the site. My be light or dark.

colors - site color management.

borderRadius - controlling rounding of various elements of a site, as a rule, it is better to use the same value. Usually, you want to have a lower value (for example 4) for a more formal and serious appearance of the site, and a larger value (12 for example) for a more informal and playful.

borderWidth - the width of the border of some elements of the site. It is recommended to use the value 2, it is still possible 1 or 3. The rest usually look very strange.

fonts - the choice of fonts for sites. Just enter the name of the font.
Value inherit in the heading means that in this case the headers will use the same font as for the body.

chronoblogTheme - you may have noticed this object throughout the file. This is done in order to add default values from the Chronoblog theme.

Content

Chronoblog has three types of content: posts, links, and notes.

All of them are in the content folder. They are located in the appropriate folders.

Chronoblog has pages, but they are not in the content folder, why? The fact is that everything in the content folder is not just website content, it is Feed content. Everything in the content folder is displayed in the feed (sorted by date, filtered by tags, etc.). But pages are not a feed content.

All types of content use markdown syntax, you can read more about this in the Gatsby documentation (markdown-syntax). Especially useful to know about frontmatter

Content Types

Posts

Posts are regular blog posts.

Place your posts inside content/posts:

chronoblog-site
  ├─ content
  │  ├─ links
  │  ├─ notes
  │  └─ posts // <- your blog posts folder
  │     └─ some-blog-post // <- one blog post
  │        ├─ image.jpg // <- cover
  │        └─ index.md // <- post file
  ├─ gatsby-config.js
  ├─ package.json
  └─ src

A typical post looks like this:

content/posts/some-blog-post/index.md

---
title: Full Blog Post Example
cover: ./image.jpg
date: 2019-11-05
description: All the usual blog post.
tags: ['post']
---

Some blog post text

Each post should have a title and date.

The cover should lead to a picture file, in this case, the file is located in the same folder as the blog post itself.

The description will appear in the post card in the feed, and will also be used for post meta tags (for SEO). If there is no description, then the text of the beginning of the post itself will be used instead.

tags are needed for organization within the Chronoblog, they are displayed in the post itself and the post card in the feed.

Links

Links in the feed aren’t very different from blog posts. But when clicked, the user will follow the link.

The basic idea of links is that they work and feel "equivalent" to blog posts - the link also has a cover, title, tags, date, description, etc.

Links are needed for materials that you consider important to post in your feed, but for some reason, you can’t post them in the form of posts. This can be your articles on other sites (which you do not have the right to host), interviews, your projects (say on the GitHub), received certificates, completed courses, etc.

To prevent users of the site from confusing posts and links, links have additional distinctive elements - emoji (🔗) in front of the title, path where the link leads under the heading, an outgoing link icon in the card. Also, links do not have a "read more ->" button like posts.

Place your links inside content/links:

chronoblog-site
  ├─ content
  │  ├─ links // <- your links folder
  │  │  └─ link-to-chronoblog // <- one link folder
  │  │     ├─ image.jpg // <- link cover
  │  │     └─ index.md // <- link file
  │  ├─ notes
  │  └─ posts
  ├─ gatsby-config.js
  ├─ package.json
  └─ src

A typical link looks like this:

content/links/link-to-chronoblog/index.md

---
title: 'Link to Chronoblog Theme repo'
cover: ./image.jpg
date: 2019-11-12
link: https://github.com/Chronoblog/gatsby-theme-chronoblog
tags: ['link', 'project']
---

Link card is a card when clicked, the user goes to the specified link.

Like a post, a link must have a title and a date, and also, of course, the link must have a link.

All other elements are the same as the post. Only in contrast to the post, the body of the link is fully displayed in the feed - because when you click, the user will follow the link, and not the "full version". So do not make the link body too large.

Notes

Notes are a type of content that is fully located in the feed. Cards of notes do not refer anywhere and do not lead anywhere.

At the same time, notes allow you to place almost anything in the feed. The starter (demo: chronoblog.now.sh) shows different options for how you can use notes - post podcasts, YouTube videos, presentations, post links or, in fact, text notes.

Place your notes inside content/notes:

chronoblog-site
  ├─ content
  │  ├─ links
  │  ├─ notes // <- notes folder
  │  │  └─ note-chronoblog // <- one note folder
  │  │     └─ index.md // <- note file
  │  └─ posts
  ├─ gatsby-config.js
  ├─ package.json
  └─ src

A typical note:

content/notes/note-chronoblog/index.md

---
date: 2019-11-02
tags: ['note']
---

Note card - the type of content that is fully displayed in the feed of the site.

A note only needs a date.

Adding Content

To add content locally, you need to create a folder in content/posts/ (if you are creating a new blog post). Give this folder any name (some-blog-post for example), and create file index.md inside this folder.

The file index.md maybe something like this:

---
title: Some Blog Post Example
cover: ./image.jpg
date: 2019-11-05
tags: ['post']
---

Some blog post text

Put some image in the same folder (in some-blog-post). If its name matches the cover from the index.md file, then this image will become the post cover.

To create a new link you need to do the same thing but in the folder content/links/ (and do not forget that the link must have link:).

And to create a new note, yes, again the same thing, but in the folder content/notes/.

The type of content is determined by the folder in which it is located!

Additional options available to content

All types of content have additional, optional options that can help you manage the content on the site.

hide - if the content has hide: true, then this content will not be displayed in the feed on the site (in any feed). But at the same time, this content itself will exist and will be available.

draft - if the content has draft: true, this content will not be on the site in any form.

frontmatter-placeholder

After you understand the content of the starter, you can delete the default content and start filling the site with your content.

However, it is better to leave the file content/links/frontmatter-placeholder in place and do not delete it. This content still doesn’t appear on the site (since it has draft: true). But its existence prevents some errors related to Gatsby and GraphQL, which may appear on an empty site.

Permanent parts of the site

It makes sense to change the default values of some parts of the site.

All these parts are just theme components. Starter replaces them with its using Component Shadowing.

Component Shadowing lets you replace the theme’s original file

You can replace any component of Chronoblog. But the parts listed here are not just possible to replace - it is recommended to do to make your site unique.

You can find this file here: src/gatsby-theme-chronoblog/site-header.mdx

Usually here is the main menu of the site. By default, it looks like this:

<MenuMain>
  <MenuBlock>
    <Link to="/">Home</Link>
    <Link to="/projects">Projects</Link>
  </MenuBlock>
  <MenuBlock>
    <SocialLinks />
    <span>&nbsp;&nbsp;</span>
    <LightDarkSwitchButton darkLabel="🌙" lightLabel="☀️" />
  </MenuBlock>
</MenuMain>

By default, the starter has two links in the menu - to the main page of the site (<Link to="/">Home</Link>) and to the additional page of the site (<Link to="/projects">Projects</Link>). The additional page of the site in the menu exists only as an example, you can change it or delete it if you do not need it. Then this file will look like this:

<MenuMain>
  <MenuBlock>
    <Link to="/">Home</Link>
  </MenuBlock>
  <MenuBlock>
    <SocialLinks />
    <span>&nbsp;&nbsp;</span>
    <LightDarkSwitchButton darkLabel="🌙" lightLabel="☀️" />
  </MenuBlock>
</MenuMain>

You may also have noticed the <SocialLinks />. This component is designed to display social network icons. Read more about this component here: SocialLinks

More about the button for switching between light and dark: LightDarkSwitchButton

You can find this file here: src/gatsby-theme-chronoblog/site-footer.mdx

This is a footer of your site, place here everything that you consider necessary to see in the footer.

By default, this file looks like this:

<div style={{textAlign: 'center'}}>
  <SocialLinks justifyContent='center' fontSize={40} />
  <p>&nbsp;</p>
  <div>© {new Date().getFullYear()}</div>
</div>

Footer of the post is what comes after every post on the blog. Usually, information about the author is placed here.

You can find this file here: src/gatsby-theme-chronoblog/post-footer.mdx

By default, this file looks like this:

<AuthorBanner></AuthorBanner>

The whole point of this file is to show how you can use it! Feel free to modify this file. Or, if you do not need it, remove everything from it and leave it blank.

By default, there is the author’s banner component that displays the author of the site.

More about AuthorBanner component: AuthorBanner Component.

You can get data about the post under which the footer is located:

Post Slug: {{props.postData.fields.slug}}  // /full-blog-post/
Post Title: {{props.postData.frontmatter.title}} // Full Blog Post Example
Post Date: {{props.postData.frontmatter.date}} // 2019-12-01T00:00:00.000Z
Post id: {{props.postData.id}} // 0ff66c75-f55f-5a87-9652-e2998c7148e0

This can be useful, for example, to connect a comment system to the site. Example of how you can use Chronoblog and Gatsby Plugin Disqus:

import { Disqus } from 'gatsby-plugin-disqus';

<AuthorBanner></AuthorBanner>
<p>&nbsp;</p>
<Disqus
	config={{
		url: props.siteMetadata.siteUrl + props.postData.fields.slug,
		title: props.postData.frontmatter.title,
		id: props.postData.id
	}}
/>

Pages

Site pages can be found here: src/pages

In Chronoblog starter you can find two pages:

index.mdx - the main page of the site

projects.mdx - example page that you can rename, change, or simply delete

A path where you can find page corresponds to the name of the file, that is, the page projects.mdx can be found at http://localhost:8000/projects.

index is an exception to this.

Pages can be used to create: contact pages, portfolio/project pages, pages dedicated to one type of content (articles on a specific topic filtered by tags), etc.

Just remember to add a link to the page in the main menu (if you want to see this page in the menu). Read more about it here: site-header

Due to how Chronoblog works, pages are not the primary way to provide information. It’s quite normal not to use a single page at all (except for the main page). The main way to organize content in Chronoblog is tags, not pages.

index.mdx - homepage of your site

By default, it looks something like this:

src/pages/index.mdx

<AuthorBanner />

Welcome to the Gatsby Starter Chronoblog! This starter will help you quickly and
easily create a website using Chronoblog Gatsby Theme. What you see is the main
page of the site. Replace everything here with your own content by editing this
file: `src/pages/index.mdx` ---

<FeedSearch />
<Tags />
<FeedItems />

You should replace the content of the main page with your own.

Pay attention to these components:

<FeedSearch />
<Tags />
<FeedItems />

You can read more about them here:

FeedItems component
Tags component
FeedSearch component

Here is more in-depth information about various aspects of Chronoblog.

Feed

Feed displays site content.

The standard way to use these components is how the main page of the site uses them:

src/pages/index.mdx

<FeedSearch />
<Tags />
<FeedItems />

How do these components work in mdx files if we did not import them there? They are already imported to mdx inside Chronoblog! So you do not need to do this. You can read about this technique here: mdxjs.com/advanced/components

FeedItems component

The most important component of the feed - this component displays content.

In this form, it is used, for example, on the main page of the site (src/pages/index.mdx):

<FeedItems />

| Prop | Required | Type | Description | | --- | --- | --- | --- | | filterByTags | optional | string[] | takes an array of tags and displays all content that have at least one of these tags | | filterByTypes | optional | string[] | takes an array of content types (links, posts, notes) and displays only this content type | | itemsFormat | optional | string | show compact or card items format | | limit | optional | number | number of content items to be displayed | | showMoreButton | optional | boolean | show or not to show the button "show more". | | yearSeparator | optional | "year" / "space" / boolean | show or not the separator by year, and if the separator is displayed, then show the year or the gap of empty space |

filterByTags example. This component will display all site content that have the project tag:

<FeedItems filterByTags={['project']} />

Tags component

This component displays all tags available on the site.

<Tags />

FeedSearch component

The search string to search feed items. It makes no sense to put this component if there is no <FeedItems /> component nearby.

<FeedSearch /> <FeedItems />

SocialLinks component

SocialLinks component displays links to your profiles on social networks in the form of icons. The information about what to display this component takes from gatsby-config.js, from siteMetadata.social.

<SocialLinks /> already included in all mdx, it can simply be used in any .mdx file:

<SocialLinks />

| Prop | Required | Type | Description | | --- | --- | --- | --- | | fontSize | optional | number / string | size of the icons | | justifyContent | optional | string[] / string | | | socialLinks | optional | array | allows you to set any links, instead of those taken from siteMetadata.social |

This component also accepts any other props, this can be used to, say, set the style you need. For example, change color:

<SocialLinks sx={{ color: "#407b6e" }} />

AuthorBanner component

AuthorBanner component displays information about the author of the site. First of all, this component is needed to display the author at the end of each blog post (see post-footer). But it can be used in any .mdx file.

Information about the author (name, description of the author, avatar and links to social networks) are taken from gatsby-config.js.

<AuthorBanner></AuthorBanner>

AuthorBanner accepts children, together with them it can be much more specific:

<AuthorBanner sx={{color: '#f1f2f6', backgroundColor: `#222`}}>
  <AuthorBannerAvatar />
  <div>
    <AuthorBannerHeading as='h1' sx={{fontSize: [7]}} />
    <AuthorBannerDescription />
    <SocialLinks fontSize="30px" />
  </div>
</AuthorBanner>

This way you can more specifically customize the look of the banner.

LightDarkSwitchButton component

This component displays a button for switching between light and dark themes.

In the starter, it is used in the main menu: site-header

<LightDarkSwitchButton />

| Prop | Required | Type | Description | | ------------ | -------- | --------------- | ---------------- | | fontSize | optional | number / string | size of the font | | darkLabel | optional | string | dark mode label | | lightLabel | optional | string | light mode label |

You can use any text for switches (including emoji):

<LightDarkSwitchButton darkLabel="🌙" lightLabel="☀️" />

Content Cover

Any content can have a cover.

You most likely want to keep the cover image in the same folder as your blog post (or link, or note). But this is optional:

chronoblog-site
  └─ content
     ├─ links
     ├─ notes
     └─ posts
        └─ some-blog-post // <- blog post with cover
           ├─ image.jpg // <- cover image
           └─ index.md // <- post file

In index.md or in index.mdx file of the post:

---
title: Full Blog Post Example
cover: ./image.jpg <- cover image
date: 2019-11-05
---

Some blog post text

Cover used in the feed, in the full blog post, as well as the main image for the metadata of the content.

Cover very forgiving to the size of the image, it is always in the center and always retains its proportions.

Font Awesome Icons

Chronoblog uses react-fontawesome for icons. Brand icons (they call them “fab”) are already built into all .mdx files - you don’t need to import them from anywhere, just use them, for example like this:

<FontAwesomeIcon icon={['fab', 'twitter']} /> <FontAwesomeIcon icon={['fab',
'github']} /> <FontAwesomeIcon icon={['fab', 'instagram']} />

These three icons that were not related to any brands were also built in:

<FontAwesomeIcon icon="at" />
<FontAwesomeIcon icon="envelope" />
<FontAwesomeIcon icon="phone" />

You can use the icons inside the text in the .md and .mdx files:

Some Text. Text with <FontAwesomeIcon icon={['fab', 'github']} /> Icon

SEO and metadata

To work with metadata, Chronoblog relies on react-helmet and gatsby-plugin-react-helmet.

Most of the work related to SEO and metadata goes automatically. Just based on what information you most likely would like to see in metadata. It is enough for the user to correctly fill in the information about the site in gatsby-config.js - gatsby-config.

Metadata generation

Basic metadata:

title is taken from the post title + site name.
description is taken from the description of the post, or, if there is no description, from the beginning of the post itself.
cover (if any) is used as the main image.

The same logic generates metadata for Open Graph and for Twitter Cards.

Metadata Verification Tools

See how Chronoblog works with metadata using these tools. For example, copy this link and paste it into the validation tool:

https://chronoblog.now.sh/full-blog-post/

Twitter card validator: cards-dev.twitter.com/validator
Facebook debug OG: developers.facebook.com/tools/debug/og/object

SEO component in `.mdx`

You can use SEO component in any .mdx file (it does not need to be imported). This component accepts child elements and you can set any metatags inside it as if you used the react-helmet plugin on its own.

This can be useful if you need to set, for example, a special title for some page on the site.

Prism Code Highlight

Chronoblog already has built-in code highlighting for posts and other content. This is done thanks to Prism and @theme-ui/prism. There is already built in support for many programming languages.

Adding support for additional programming languages

Shadowing in Chronoblog Gatsby Theme

Shadowing is a feature of any Gatsby Theme. You can read more about this in Gatsby docs: Shadowing in Gatsby Themes

This feature allows users to replace a file in the src directory that is included in the webpack bundle with their own implementation. This works for React components, pages in src/pages, JSON files, TypeScript files, as well as any other imported file (such as .css) in your site.

This all works in the case of Chronoblog Theme. However, there are components that are still better not to touch so as not to break anything when updating Chronoblog.

For example, if you want to change the site menu, you need to create file site-header.mdx here: src/gatsby-theme-chronoblog/site-header.mdx. This will automatically replace default file of Chronoblog itself (which you can see here: github.com/Chronoblog/gatsby-theme-chronoblog/blob/master/packages/gatsby-theme-chronoblog/src/site-header.mdx)

Components that can and should be shadowed

Components that were specially created for you to change them:

| shadow | name | description | | --- | --- | --- | | ✅ | src/gatsby-theme-chronoblog/post-footer.mdx | read: post-footer | | ✅ | src/gatsby-theme-chronoblog/site-header.mdx | read: site-header | | ✅ | src/gatsby-theme-chronoblog/site-footer.mdx | read: post-footer | | ✅ | src/gatsby-theme-chronoblog/content-bottom.mdx | |

Components that can be shadowed

These components can be shadowed if you think that you really need it:

| shadow | name | description | | --- | --- | --- | | 👍 | src/gatsby-theme-chronoblog/components/layout.js | the whole site is wrapped in this component | | 👍 | src/gatsby-theme-chronoblog/components/header.js | | | 👍 | src/gatsby-theme-chronoblog/components/footer.js | |

About used Technologies and Methods

Here to list the technologies and methods that are used in the project. None of this needs to be known to use Chronoblog (Read Guide and Documentation for this), but it will help to understand how everything is organized here.

Organization of this monorepository

This monorepo uses Lerna (https://github.com/lerna/lerna) and yarn workspaces (https://yarnpkg.com/en/docs/workspaces). Because of this, we do not use npm for project development (this applies only to the development of Chronoblog. It is normal to use npm to develop a site based on Chronoblog Theme).

packages folder. At the moment there is only gatsby-theme-chronoblog/tree/master/packages/gatsby-theme-chronoblog there, and all the main work on the project takes place in it. Perhaps in the future, additional packages will appear.
starters folder contains all the project starters.
examples folder contains examples of how Chronoblog can be used.
test-builds folder for test builds.

Such an organization allows you to check the work of any starter right during the work on the project. For example, by running yarn start:chronoblog command, you can make changes to gatsby-theme-chronoblog/tree/master/packages/gatsby-theme-chronoblog and immediately look at how the "chronoblog starter" works with these changes (at http://localhost:8000).

Tests and Publication

The github action scripts can be viewed here: workflows. Each time changes are added to the repo, tests and the generation of all starters (on various platforms) are launched. This allows to check if everything is working correctly.

We can say that the master branch is a development branch since changes in the branch alone do not lead to the publication of the project. Therefore, there may be bugs and problems in the master branch.

When updating the project version, packages are sent to npm, and starters, using publish-starters.yml, update their individual repositories. Because of this, chronoblog starters have such strange commits (for example, https://github.com/Chronoblog/gatsby-starter-chronoblog).

For manual/visual testing, we have a special "secret" starter for tests - https://github.com/Chronoblog/gatsby-theme-chronoblog/tree/master/starters/tests. You can run it with the command yarn start:tests or yarn serve:tests (to run a full build).

TypeScript and JSDoc for type annotation

If you looked at the package.json file in the root of the project, then you saw TypeScript and types for various libraries in the dependencies (@types/node, @types/react, etc.). But the project is written in js?

The fact is that JSDoc comments are used to declare types. Read more about this method in these articles:

GitHub Workflows

Github status shows the state of the Master branch. There may be problems and fail tests in the Master branch, this is normal - it only means that we can’t publish a new public release.

🤝 If you have any problems with the Chronoblog, or you have interesting ideas, write to the github issue: github.com/Chronoblog/gatsby-theme-chronoblog/issues

🐦 You can also contact me on Twitter: twitter.com/Ganevru, I will be glad to know your opinion about Chronoblog.

✍️ If you made a site using Chronoblog - write to me about it!

Any type of contribution to the project is also welcome! I use the GitHub issues as a todo list, so if you want to help, read existing issues. Or, if you want to add something new, write new issues with your ideas, and we will discuss it.

If you want to contribute to the project, it will be useful for you to read this: About used Technologies and Methods

Contribution to the README.md

Contributions to the README are welcome, especially considering that English is not my native language.

However, remember that you need to edit this README: https://github.com/Chronoblog/gatsby-theme-chronoblog/blob/master/packages/gatsby-theme-chronoblog/README.md - this one located in packages/gatsby-theme-chronoblog/README.md is "real".

Art

Illustrations and Images that are used in the project (usually in Starters).

Illlustrations, open source illustrations kit: illlustrations.co
Lukasz Adam free illustrations: lukaszadam.com/illustrations
Deszone: deszone.net, free vector graphics ratterns, illustrations, icons.
Unsplash: unsplash.com, the internet’s source of freely usable images. Powered by creators everywhere.
Undraw: undraw.co, open-source illustrations for every project you can imagine and create.

MIT License

Free

Preview Get

96 stars

Deploy theme in one click

Gatsby template

Compatible with Gatsby v2
It is a Gatsby theme

Compatible with Markdown

This template uses only local files