Need Package Maintenance

    @pauliescanlon/gatsby-theme-terminal

    2.0.0 • Public • Published
    gatsby-theme-termninal main image

    gatsby-theme-terminal

    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

    👀 Preview

    🚀 Getting started

    To help you get started you can either clone the starter gatsby-starter-terminal or read the below.

    Install

    npm install @pauliescanlon/gatsby-theme-terminal
    

    Install Peer Dependencies

    npm install @mdx-js/mdx @mdx-js/react gatsby gatsby-plugin-mdx gatsby-source-filesystem react react-dom
    

    Setup

    gatsby-config.js

    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']
    }
    

    directory structure

    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 
    
    

    frontmatter setup

    Pages

    Pages must include navigationLabel in the frontmatter

    // src/pages/about.mdx
    ---
    navigationLabel: About
    ---
    
    # About
    
    This is about page
    
    

    Theme options

    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
    ---
    

    Embedded Images

    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} />
    

    markdown

    The theme supports the complete markdown spec and you can see how to use markdown in the demo

    theme-ui/components

    The theme supports all the components provided by theme-ui/components and you can see in the demo how they are used.

    gatsby-theme-terminal/components

    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

    Component Shadowing

    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

    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

    ko-fi

    Install

    npm i @pauliescanlon/gatsby-theme-terminal

    DownloadsWeekly Downloads

    1

    Version

    2.0.0

    License

    MIT

    Unpacked Size

    141 kB

    Total Files

    69

    Last publish

    Collaborators

    • pauliescanlon