Gatsby Theme Blog Ocean

Blog Ocean is a Gatsby theme for personal homepages and blogs. It features the material design, built-in MDX support, dark mode, SEO-friendly localization, comment system powered by Giscus and more! You can have a look at the live demo at www.howyoung.dev.

The theme is still under development and more thrilling features will be added to it soon. Meanwhile, it is designed with extendibility in mind, allowing you to customize each part of the website as you wish. Please refer to the section Customization for more details.

How to install

The theme is available as an NPM package gatsby-theme-blog-ocean. Add it as a dependency to your project first with:

# Use NPM
npm install gatsby-theme-blog-ocean

# Use Yarn
yarn add gatsby-theme-blog-ocean

Then add the theme to the gatsby-config.js file in your project.

// gatsby-config.js
module.exports = {
  // ...
  plugins: [
    // ...
    `gatsby-theme-blog-ocean`,
  ]
}

For most cases, you may want to specify your own options, which can be configured using:

// gatsby-config.js
module.exports = {
  // ...
  plugins: [
    // ...
    {
      resolve: `gatsby-theme-blog-ocean`,
      options: {
        languages: ['en', 'zh-CH']
        // ...
      }
    }
  ]
}

For more options available, please refer to the section Available options.

Available options

Examples of usage

Please refer to the example folder for a minimal example to use the theme.

To create posts, you need to create a posts folder and expose it as a source using the gatsby-source-filesystem plugin.

// plugins in gatsby-config.js
{
  resolve: `gatsby-source-filesystem`,
  options: {
    path: `posts`,
    name: `posts`
  }
}

To support multiple locales, layout the posts as specified by the postsFolderLayout option, which is parsed with path-to-regexp. A template for the generated path of posts can also be configured using postsPathTemplate. The language code (/:lang as in the default value) is recommended for an SEO-friendly localization.

Customization

Site metadata

Some of the components are automatically customized with the site metadata. title, description, and siteUrl passed to the options will be added to the metadata by default. You may also want to add social to it and it will appear on the banner.

module.exports = {
  // ...
  siteMetadata: {
    // ...
    social: [
      {
        name: `GitHub`,
        url: `https://github.com/HowyoungZhou`,
      },
      {
        name: `Email`,
        url: `mailto:me@howyoung.dev`,
      },
      // ...
    ]
  }
}

Add a new locale

To customize the text or add the translation for a new language. You need to add a locales folder and again expose it as a source using the gatsby-source-filesystem plugin, and modify the theme options to add new languages and locales source name to it.

// plugins in gatsby-config.js
{
  resolve: `gatsby-source-filesystem`,
  options: {
    path: `locales`,
    name: `locales`
  }
},
{
  resolve: `gatsby-theme-blog-ocean`,
  options: {
    // ...
    languages: ['en', 'zh'], // Add new languages
    localesSource: 'locales' // Pass locales source to the theme
  }
}

Now copy the en folder in gatsby-theme-blog-ocean/src/locales to the locales folder in your project, and add other languages by replacing the translation in the .json files inside.

Overwrite components or pages

If you want to deeply customize the components or pages, you may want to overwrite them using the shadowing features of Gatsby.

To replace a file in the gatsby-theme-blog-ocean/src folder of the theme, you should place the file in the same relative path to the src/gatsby-theme-blog-ocean folder of your project.

To reuse part of the original components, you can import them from the gatsby-theme-blog-ocean package.

How to run tests

Testing is still in progress.

How to develop locally

Clone the repository and install the dependencies:

git clone https://github.com/HowyoungZhou/gatsby-theme-blog-ocean.git
yarn install

Start the development server:

yarn develop

Edit the code and you will see the change applies with hot-reload.

How to contribute

Your generous contribution is highly appreciated! If you wish to contribute to the project, please fork this repository and edit it, then open up a Pull Request.