@d3vd/gatsby-theme-code-notes
v2.0.1
Published
A Gatsby theme for publishing code-related notes and snippets
Downloads
2
Maintainers
Readme
Features
- Notes can:
- Extra markdown features have also been added. Find out more here
- Note search powered by the super-fast Flexsearch
Installation
mkdir my-site
cd my-site
yarn init
# install gatsby-theme-code-notes and it's dependencies
yarn add gatsby-theme-code-notes gatsby react react-dom
# or
npm install gatsby-theme-code-notes gatsby react react-dom
Using the Gatsby starter
Step 1: Starter installation
Source code for the starter can be found at: https://github.com/MrMartineau/gatsby-starter-code-notes
With gatsby-cli
:
gatsby new code-notes https://github.com/MrMartineau/gatsby-starter-code-notes
With git clone
:
git clone [email protected]:MrMartineau/gatsby-starter-code-notes.git
cd code-notes
yarn
Step 2: Develop & Build
Once installed or cloned locally and all packages are installed you can begin developing your site.
# Run localhost
yarn dev
# Build your Gatsby site
yarn build
Usage
Theme Options
| Key | Default value | Description |
| -------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| basePath
| /
| Root url for all notes pages |
| contentPath
| /content/notes
| Location of notes content |
| logo
| ''
(empty string) | Path to your site's logo. Will be used as the src
attribute for an image |
| showDescriptionInSidebar
| true
| Show config.site.description
in the sidebar |
| showDate
| false
| Show the note's modified date |
| gitRepoContentPath
| ''
| Set the location for your notes if they're hosted online, e.g. your git repo. This will show a "Edit this page" link underneath each note |
| showThemeInfo
| true
| Show info about this Gatsby theme |
| mdxOtherwiseConfigured
| true
| Configure gatsby-plugin-mdx
. Note that most sites will not need to use this flag. If your site has already configured gatsby-plugin-mdx
separately, set this flag false
. |
| flexSearchEngineOptions
| { encode: 'icase', tokenize: 'forward', resolution: 9 }
| Configure FlexSearch's index method. The default value uses FlexSearch's default
preset. Find out your other options here. |
| openSearch
| { }
| Configure the opensearch.xml
file contents. This file is generated during the build process. If you want to add opensearch support, ensure you set a siteUrl
in the config. See below for more information. |
Example usage
This example overrides some of the theme defaults and shows the various options for the opensearch config.
// gatsby-config.js
module.exports = {
plugins: [
{
resolve: `gatsby-theme-code-notes`,
options: {
basePath: '/',
contentPath: '/content/notes',
gitRepoContentPath:
'https://github.com/mrmartineau/gatsby-theme-code-notes/tree/master/example/code-notes/',
showDescriptionInSidebar: true,
showThemeInfo: false,
logo: 'https://brand.zander.wtf/Avatar.png',
showDate: true,
// Opensearch is used to enhance the search on your site.
// If you want to add it, ensure you set a `siteUrl`
openSearch: {
siteUrl: 'https://code-notes-example.netlify.app', // required if you want opensearch
siteShortName: 'Gatsby Theme Code Notes Example', // override the default value of 'Search`
siteTags: 'front-end', // optional
siteContact: 'https://twitter.com/MrMartineau', // optional
siteDescription: 'A Gatsby theme for storing your code-related notes', // optional
},
},
},
],
}
Add notes to your site by creating md
or mdx
files inside /content/notes
.
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.
Note frontmatter
Frontmatter information (written in YAML) can be used to add metadata and extra information for your notes
Only the title
field is required, the rest are optional.
---
title: Note metadata
emoji: 😃
tags:
- metadata
- info
link: https://zander.wtf
---
Link
The link
item is used to display a link that is related to the note itself. It will appear below the title if.
Emoji
The emoji
frontmatter item will add an emoji beside the title on listing views and above the title on individual note pages
Tags
The tags
array frontmatter item allows you to add as many tags to a note as you'd like.
Dates
The modified
frontmatter item allows you set a date for your note. This means they can then be sorted (ascending & descending) when viewed in the note list pages. This was introduced in v2.0.0.
The created
frontmatter item works in a similar way, but it is not being used at the moment so it can be ommitted.
1. Add new modified
key to your YAML frontmatter
This will mean that you have to update all your notes with a timestamp.
---
title: Storybook
tags:
- testing
emoji: 📖
link: 'https://storybook.js.org'
created: 2020-02-27T23:02:00.000Z # this is not used by the theme at the moment
modified: 2021-01-16T10:31:32.000Z
# any valid ISO timestamp should work, like this:
# modified: 2021-01-16
---
If you have many notes and want to speed up adding all those timestamps, I created an npm package (frontmatter-date-setter
) to automate it based on your last git or file modification dates.
Use the frontmatter-date-setter
(or fds
) CLI like so: (where notes
is the directory of all your notes)
fds --directory=notes --debug
The package does have a few issues that I'd like to improve. For example, it will convert most emojis to unicode strings, and will format other parts of your frontmatter. So take care when you run it.
2. Set showDate: true
in gatsby-config.js
Setting this value in this plugin's config renders the interface to switch to date sorting as well as showing the date in other parts of the interface.
Advanced usage
PWA
Turn your code notes into a PWA using this extra config. This requires gatsby-plugin-manifest
and gatsby-plugin-offline
.
// gatsby-config.js
{
resolve: `gatsby-plugin-manifest`,
options: {
name: `Zander's Code Notes`,
short_name: `CodeNotes`,
description: `Notes on code. My memory bank.`,
start_url: `/`,
background_color: `hsl(210, 38%, 95%)`,
theme_color: `hsl(345, 100%, 69%)`,
display: `standalone`,
icon: `static/logo.png`,
showDate: true,
},
},
{
resolve: `gatsby-plugin-offline`,
options: {
precachePages: [`/*`, `/tag/*`],
},
},
License
Made by Zander • zander.wtf • GitHub • Twitter