# gatsby-theme-blog
> A Gatsby theme for miscellaneous blogging with a dark/light mode
Latest version **4.0.0** (published 2021-12-03) · MIT license · 0 weekly downloads
## Install
```sh
npm install gatsby-theme-blog
pnpm add gatsby-theme-blog
yarn add gatsby-theme-blog
bun add gatsby-theme-blog
```
## Health
**Score 15/100 (F)** — status: abandoned.
Positive: no vulnerabilities.
Warnings: low downloads; no types; no esm support.
Negative: abandoned; low maintenance score.
## Facts
| | |
|---|---|
| Version | 4.0.0 |
| Published | 2021-12-03 |
| First published | 2018-11-13 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=14.15.0 |
| Dependencies | 12 |
| Unpacked size | 84.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | dschau, kylemathews, pieh, sidharthachatterjee, wardpeet, tylerbarnes, fk, smthomas, lekoarts, rachelbahl, daniellewgatsby, veryspry, abhiaiyer, biscarch |
| Keywords | gatsby, gatsby-theme, gatsby-plugin, react, blog |
## Links
- npm: https://www.npmjs.com/package/gatsby-theme-blog
- Repository: https://github.com/gatsbyjs/themes
- Homepage: https://github.com/gatsbyjs/themes/tree/master/packages/gatsby-theme-blog#readme
- Issues: https://github.com/gatsbyjs/themes/issues
- npm.io page: https://npm.io/package/gatsby-theme-blog
## Dependencies (12)
- [theme-ui](https://npm.io/package/theme-ui.md) 0.7.0
- [mdx-utils](https://npm.io/package/mdx-utils.md) 0.2.0
- [react-helmet](https://npm.io/package/react-helmet.md) ^6.1.0
- [@reach/skip-nav](https://npm.io/package/@reach/skip-nav.md) ^0.16.0
- [@theme-ui/prism](https://npm.io/package/@theme-ui/prism.md) 0.6.2
- [gatsby-plugin-feed](https://npm.io/package/gatsby-plugin-feed.md) ^4.3.0
- [gatsby-plugin-emotion](https://npm.io/package/gatsby-plugin-emotion.md) ^7.3.0
- [gatsby-plugin-twitter](https://npm.io/package/gatsby-plugin-twitter.md) ^4.3.0
- [gatsby-plugin-theme-ui](https://npm.io/package/gatsby-plugin-theme-ui.md) 0.7.0
- [gatsby-theme-blog-core](https://npm.io/package/gatsby-theme-blog-core.md) ^4.0.0
- [gatsby-theme-ui-preset](https://npm.io/package/gatsby-theme-ui-preset.md) ^3.0.0
- [gatsby-plugin-react-helmet](https://npm.io/package/gatsby-plugin-react-helmet.md) ^5.3.0
## Alternatives
- [mobx-react](https://npm.io/package/mobx-react.md) — 2.8M weekly downloads
- [rc-tree](https://npm.io/package/rc-tree.md) — 2.6M weekly downloads
- [@react-oauth/google](https://npm.io/package/@react-oauth/google.md) — 1.3M weekly downloads
- [@wagmi/connectors](https://npm.io/package/@wagmi/connectors.md) — 877.0K weekly downloads
- [vee-validate](https://npm.io/package/vee-validate.md) — 836.4K weekly downloads
## Recent versions
- 4.0.0 (latest) — 2021-12-03
- 2.1.1-gatsby-v3.19 (gatsby-v3) — 2021-04-19
- 1.6.52-ipc-develop.23 (ipc-develop) — 2020-08-04
- 1.6.62-mdx-less-babel2.2 (mdx-less-babel2) — 2020-07-07
- 1.6.62-mdx-less-babel.1 (mdx-less-babel) — 2020-07-07
- 1.6.61-static-query-template.8 (static-query-template) — 2020-07-06
- 1.6.60-oom-exit-code.13 (oom-exit-code) — 2020-07-05
- 1.6.54-finish-plugin-activities.15 (finish-plugin-activities) — 2020-07-03
- 1.4.25-unifiedroutes.87 (unifiedroutes) — 2020-07-01
- 1.6.52-corejs3.34 (corejs3) — 2020-07-01
- 2.0.0-canary.809 (blog-2.0) — 2020-06-22
- 1.6.41-admin-pkg.4 (admin-pkg) — 2020-06-13
- 1.6.32-distributed-html.12 (distributed-html) — 2020-06-11
- 1.6.43-query-webpack-modules.12 (query-webpack-modules) — 2020-06-10
- 1.6.32-polyfills.11 (polyfills) — 2020-06-05
- … 403 more at https://npm.io/package/gatsby-theme-blog/versions
## README
The Gatsby Blog theme
A Gatsby theme for creating a blog.
## Installation
### For a new site
If you're creating a new site and want to use the blog theme, you can use the blog theme starter. This will generate a new site that pre-configures use of the blog theme.
```shell
gatsby new my-themed-blog https://github.com/gatsbyjs/gatsby-starter-blog-theme
```
### For an existing site
If you already have a site you'd like to add the blog theme to, you can manually configure it.
1. Install the blog theme
```shell
npm install gatsby-theme-blog
```
2. Add the configuration to your `gatsby-config.js` file
```js
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: `gatsby-theme-blog`,
options: {
// basePath defaults to `/`
basePath: `/blog`,
},
},
],
}
```
3. Add blog posts to your site by creating `md` or `mdx` files inside `/content/posts`.
> Note that if you've changed the default `contentPath` in the configuration, you'll want to add your markdown files in the directory specified by that path.
4. Add an image with the file name `avatar` (can be jpg or png) inside the `/assets` directory to include a small image next to the footer on every post page.
> Note that if you've changed the default `assetPath` in the configuration, you'll want to add your asset files in the directory specified by that path.
5. Run your site using `gatsby develop` and navigate to your blog posts. If you used the above configuration, your URL will be `http://localhost:8000/blog`
## Usage
### Theme options
| Key | Default value | Description |
| ------------------------ | ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `basePath` | `/` | Root url for all blog posts |
| `contentPath` | `content/posts` | Location of blog posts |
| `assetPath` | `content/assets` | Location of assets |
| `mdxOtherwiseConfigured` | `false` | Set this flag `true` if `gatsby-plugin-mdx` is already configured for your site. |
| `preset` | `gatsby-theme-ui-preset` | Theme UI compatible package name that will act as the base styles for your project. Be sure to install the package you're referencing. Set to `false` to ignore all presets and only use local styles. |
| `prismPreset` | `null` | Theme UI compatible package name that will act as the prism syntax highlighting for your project. Be sure to install the package you're referencing. For themes in `@theme-ui/prism` the name will suffice, e.g. `prism-okaidia`. |
| `excerptLength` | `140` | Length of the auto-generated excerpt of a blog post |
| `webfontURL` | `''` | URL for the webfont you'd like to include. Be sure that your local theme does not override it. |
| `imageMaxWidth` | `1380` | Set the max width of images in your blog posts. This applies to your featured image in frontmatter as well. |
| `filter` | `{}` | Set the posts filter, for example: `{ frontmatter: { draft: {ne: true} } }` |
| `limit` | `1000` | Set the amount of pages that should be generated |
#### Example configuration
```js
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: `gatsby-theme-blog`,
options: {
// basePath defaults to `/`
basePath: `/blog`,
prismPreset: `prism-okaidia`,
},
},
],
}
```
### Additional configuration
In addition to the theme options, there are a handful of items you can customize via the `siteMetadata` object in your site's `gatsby-config.js`
```js
// gatsby-config.js
module.exports = {
siteMetadata: {
// Used for the site title and SEO
title: `My Blog Title`,
// Used to provide alt text for your avatar
author: `My Name`,
// Used for SEO
description: `My site description...`,
// Used for resolving images in social cards
siteUrl: `https://example.com`,
// Used for social links in the root footer
social: [
{
name: `Twitter`,
url: `https://twitter.com/gatsbyjs`,
},
{
name: `GitHub`,
url: `https://github.com/gatsbyjs`,
},
],
},
}
```
### Blog Post Fields
The following are the defined blog post fields based on the node interface in the schema
| Field | Type |
| ---------------- | -------- |
| id | String |
| title | String |
| body | String |
| slug | String |
| date | Date |
| tags | String[] |
| excerpt | String |
| image | String |
| imageAlt | String |
| imageCaptionText | String |
| imageCaptionLink | String |
| socialImage | String |
### Image Behavior
Blog posts can include references to images inside frontmatter. Note that this works for a relative path as shown below, or an external URL.
```md
---
title: Hello World (example)
date: 2019-04-15
image: ./some-image.jpg
---
```
`image` refers to the featured image at the top of a post and is not required. It will also appear as the preview image inside a social card. Note that this requires you to set `siteUrl` in your `gatsby-config.js` file metadata to your site's domain.
When adding an `image`, `imageAlt` is available to provide alt text for the featured image within the post. If this is not included, it defaults to the post excerpt.
You may want to use a different image for social sharing than the one that appears in your blog post. You can do so by setting `socialImage` in frontmatter.
### How Styles work
This theme enables `gatsby-plugin-theme-ui` which allows you to leverage [Theme UI](https://theme-ui.com/) to style your project.
By default, `gatsby-theme-ui-preset` operates as your base theme styles. Any local shadowed styles deep merge with that preset.
Alternatively, you can pass a preset of your own choosing by installing the package and passing the package name as the `preset` in `gatsby-config.js`. Again, local shadowed styles will deep merge with this preset if they exist.
```js
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: `gatsby-theme-blog`,
options: {
preset: `my-preset-name-here`,
},
},
],
}
```
If you'd rather use only local shadowed styles with no underlying preset, pass the `preset` option as `false`.
#### Prism
You can also configure your prism theme for syntax highlighting in code snippets by passing the `prismPreset` option.
`@theme-ui/prism` is included by default, so any [available presets](https://theme-ui.com/packages/prism#syntax-themes) can be passed using only their name, e.g. `dracula`.
```js
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: `gatsby-theme-blog`,
options: {
prismPreset: `dracula`,
},
},
],
}
```
As an alternative, you can install a package with a prism theme into your project and pass the package name.
This option is null by default, and in all cases local shadowed styles take precedent.
##### Highlight Line
You can highlight code snippets using `// highlight line` or a combination of `// highlight-start` and `// highlight-end`.
To update the styling for these highlights override the `.highlight` styles inside your prism theme.
### Accessibility and skip-nav
This theme comes equipped with [skip-nav](https://reacttraining.com/reach-ui/skip-nav/). Note that if you override `header.js` you'll need to add the `SkipNavLink` component yourself. Additionally, if you override `layout.js` you'll need to include `SkipNavContent` manually.
## Migration
For migration guides please see the [dedicated migration guide](https://github.com/gatsbyjs/themes/blob/master/MIGRATING.md).
---
_Source: https://npm.io/package/gatsby-theme-blog · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._