Gatsby Theme Terminal aims to be a zero component theme. It provides data components to aid in the abstraction of presentational and data layers which together provide the most flexibility
The theme handles the data but how it's displayed is up to you!
You can create any page layout or component combination you like using your own components or components provided by theme-ui/components
To help you get started you can either clone the starter gatsby-starter-terminal or read the below.
npm install @pauliescanlon/gatsby-theme-terminal
npm install @mdx-js/mdx @mdx-js/react gatsby gatsby-plugin-mdx gatsby-source-filesystem react react-dom
Add the siteMetaData
and @pauliescanlon/gatsby-theme-terminal
to your gatsby-config.js
// gatsby-config.js
module.exports = {
siteMetadata: {
name: "Your blog title",
description: "I like tech",
keywords: ["tech", "blog", "boop"],
siteUrl: 'https://gatsby-theme-terminal.netlify.com',
siteImage: 'name-of-open-graph-image.jpg', // pop an image in the static folder to use it as the og:image,
profileImage: 'name-of-profile-image.jpg'
lang: `eng`,
config: {
sidebarWidth: 240 // optional,
},
},
plugins: ['@pauliescanlon/gatsby-theme-terminal']
}
To add pages create .mdx
files in the src/pages
directory. You need at least one file called index.mdx
located at
src/pages
or you'll see a GraphQL error.
|-- src
|-- pages
|-- index.mdx
|-- about.mdx
|-- contact.mdx
Pages must include navigationLabel
in the frontmatter
// src/pages/about.mdx
---
navigationLabel: About
---
# About
This is about page
Additional .mdx
can be sourced from anywhere outside the pages
directory but you need to tell the theme where to
source these files from.
Use the source
option in gatsby-config.js
// gatsby-config.js
...
plugins: [
{
resolve: `@pauliescanlon/gatsby-theme-terminal`,
options: {
source: [
{
name: "posts",
dir: "posts",
},
{
name: "projects",
dir: "projects",
},
] // can be an object or array of objects
},
},
],
}
Then create the relevant files and directories
|-- src
|-- pages
...
|-- posts
|--2020
|--02
|-- some-post.mdx
|-- featuredImage: markus-spiske-466ENaLuhLY-unsplash.jpg
|-- markus-spiske-FXFz-sW0uwo-unsplash.jpg
|-- projects
|-- some-project.mdx
Any file that is not sourced from pages
can contain any of the following frontmatter
but a title
is required,
this is how the theme distinguishes between pages and other .mdx
files
// src/posts/2020/02/some-post.mdx
---
title: Some Post
tags: ["JavaScript", "React", "GatsbyJs", "HTML", "CSS", "theme-ui"]
date: 2020-01-01
dateModified: 20-20-2020
author: Paul Scanlon
status: draft // => means it won't be rendered
isPrivate: // => it will be rendered but you can use this prop as a filter
url: "https://example.com" // => could be an external url
misc: "Ahoy" // => use how you wish
pinned: false // => Could be used as a filter for pinned posts
featuredImage: markus-spiske-466ENaLuhLY-unsplash.jpg
featuredImageUrl: https://via.placeholder.com/936x528
embeddedImages:
- markus-spiske-FXFz-sW0uwo-unsplash.jpg
embeddedImageUrls:
- https://via.placeholder.com/468x264
---
By using the The <GatsbyImage />
component from gatsby-plugin-image
you can pass the image data queried by GraphQL
and pass it on via the image
prop
The gatsbyImageData
, data is available via props.embedded.image(n)
<GatsbyImage image={props.embedded.image1} />
You can also use the Theme UI <Image />
component by passing it a src
<Image src={props.embedded.image1.gatsbyImageData.images.fallback.src} />
image1
in this example would be markus-spiske-FXFz-sW0uwo-unsplash.jpg
EmbeddedImages can also be sourced from a remote url, in this case use the <Image />
component and pass it the same
props
<Image src={props.embedded.image2.gatsbyImageData.images.fallback.src} />
The theme supports the complete markdown spec and you can see how to use markdown in the demo
The theme supports all the components provided by theme-ui/components and you can see in the demo how they are used.
The theme also comes with it's own components but... These are purely to provide access to the source nodes. What you choose to render is completely up to you!
For example to display a list of all files sourced from the source
theme option you could do something like this.
This component can be used in ANY .mdx
file 😎
<SourceList>
{(source) => (
<ul>
{source.map((edge, index) => {
const {
frontmatter: { title },
} = edge.node
return <li key={index}>{title}</li>
})}
</ul>
)}
</SourceList>
You can see more about how to use the theme components in the demo
There is very little to shadow because almost everything is exposed by the components but you might want to add your own logo.
To do this create the following directories @pauliescanlon/gatsby-theme-terminal/components/Logo
in the src
directory of your project and then create a Logo.js
file. You can do anything you like in here.
|-- src
|-- @pauliescanlon
|-- gatsby-theme-terminal
|-- components
|-- Logo
|-- Logo.js
If you would like to customize any part of the theme you can do so by shadowing the theme file.
To do this create the following directory src/gatsby-plugin-theme-ui
and then create an index.js
// src/gatsby-plugin-theme-ui/index.js
import baseTheme from '@pauliescanlon/gatsby-theme-terminal/src/gatsby-plugin-theme-ui'
export default {
...baseTheme,
colors: {
...baseTheme.colors,
primary: '#FF4081',
secondary: '#03A9F4',
success: '#FFEB3B',
background: '#232323',
surface: '#393939',
},
}
favicon(s) need to be saved in static/images
and named favicon-16x16.png
and favicon-32x32.png
along with an
.icon
file called favicon.ico
If you're using gatsby-theme-terminal in your project i'd love to hear from you @pauliescanlon