Nebulae Populate M83

    gatsby-theme-code-notes

    2.3.0 • Public • Published

    Features

    • Notes can:
      • be written using Markdown (.md) or MDX (.mdx)
      • have zero, one or many tags. See an example here
      • have associated emojis 👏
      • be nested in subfolders so you can organise them how you like
      • sketchy annotations (highlights, strike-thoughs etc). Find out more here
    • 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 git@github.com: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

    MIT © Zander Martineau

    Made by Zander • zander.wtfGitHubTwitter

    Install

    npm i gatsby-theme-code-notes

    DownloadsWeekly Downloads

    92

    Version

    2.3.0

    License

    MIT

    Unpacked Size

    82.3 kB

    Total Files

    70

    Last publish

    Collaborators

    • mrmartineau