
This post spins off of the [previous post's](/garden/02-syntax-highlighting) interest in extending themes. Because I ended up reworking both how garden handles themes (both their generation and passing them to different theme providers), I spun this off into its own post.

### color tokens and generating themes

To start, the minimum number of color tokens needed for garden is two: text and background color. Rather than go monochromatic, we also want a primary color. These should live in an easily configurable place and all components necessary for garden to work should only use these colors.

We'll add a `theme` object to `config.js`. It will expect at least a `default` object with keys corresponding to the theme object, so we'll give it a `color` object with the necessary colors. We define our themes this way so that, in the future, we can continue extending the theme with other design tokens besides colors. We can also provide config any number of other objects to generate themes. Here's an example with a default and a dark theme:

``` js
  ...
  theme: {
    default: {
      colors: {
        text: '#2d2a24',
        background: '#fdfdfd',
        primary: '#b7e2d8'
      }
    },
    dark: {
      colors: {
        text: '#ececec',
        background: '#2c2c2c',
        primary: '#888'
      }
    }
  }
```

> => question
>
> This would be really easy to accomplish with [color modes](https://theme-ui.com/color-modes), but we have to also pass the theme to the styled components provider. We'll handle this very similarly to how theme-ui handles it, though.

Next, we need to make sure the theme object supports color overrides. Garden does this using a function called `genTheme` that takes `colors` as an argument and returns a theme object.

``` js
  function genTheme({ colors } = { colors: defaultColors }) {
    ...theme
  };
```

Note here that I also have a set of default color values. You could run the function without any arguments and still get a perfectly good theme object.

### toggle between modes

Heavily influenced by theme-ui's color modes documentation, garden takes the themes specified in the config and cycles through them. At the `App.js` level, we generate an object that contains a list of themes defined in the config, and an array of theme objects generated by those themes. Here, I'm calling them 'modes' just to differentiate them (in name alone) from themes.

``` js
  const { themes } = siteConfig;
  const modeList = {
    modes: Object.keys(themes),
    modeThemes: Object.keys(themes).map(theme => {
      return genTheme({ ...themes[theme] });
    })
  };
```

In the functional component, we use a hook to setup the default state, and a toggle function to cycle among nodes.

``` js
  const [currentMode, setMode] = useState('default');
  const { modes, modeThemes } = modeList;
  const toggleMode = () => {
    const index = modes.indexOf(currentMode);
    const next = modes[(index + 1) % modes.length];
    setMode(next);
  };
```

Wrapping the whole of the app in a [context provider](https://reactjs.org/docs/hooks-reference.html#usecontext) allows us to pass the down the mode state and the toggle function.

``` js
  <ThemeContext.Provider
    value={{
      currentMode,
      toggleMode
    }}
  >
    {...app}
  </ThemeContext.Provider>
```

As an aside, I ended up liking this as a feature rather than the usual sun/moon icon for a few reasons:

1. more than one theme
2. clear what theme is on (rather than relying on iconography)
3. no need for svg imports

### resources

- [theme-ui color modes](https://theme-ui.com/color-modes)

### up next

- [x] syntax highlighting
- [x] [content directories](/garden/04-content-directories)
- [ ] templating

programmatically generating themes utilizing basic variables/tokens and adding state logic to cycle through themes

03 - extending themes


This post offers really brief documentation for adding syntax highlighting with [rehypePrism](https://github.com/mapbox/rehype-prism) to `next-mdx-remote`. It then outlines some considerations for handling that highlighting over and against the global theme.

### syntax highlighting

Syntax highlighting with next-mdx-remote can be done a few different ways. If you want to use [prism-react-renderer](https://github.com/FormidableLabs/prism-react-renderer), you can find great examples in the template repos for [mdnext](https://github.com/domitriusclark/mdnext/blob/master/packages/mdnext-components/src/components/Code.js). I opted to use `rehypePrism` to render code blocks on the node side of things. All I did was pass it as an argument in `renderToString`.

```js
  import rehypePrism from '@mapbox/rehype-prism';

  ...

  const mdx = await renderToString(content, {
    components: null,
    mdxOptions: {
      rehypePlugins: [rehypePrism]
    },
    scope: data
  });
```

### themeing and syntax highlighting

Initially, I just added the prism NightOwl theme and thought I'd move on, but the difference between the prism theme and the color scheme of the site had me wondering if there was a better way to handle syntax highlighting as an extension of the theme object. Some considerations:

1. Syntax highlighting should be an extension of the theme
2. This also means that it should be an extension of the dark theme
3. Because garden is meant to be extendable, the syntax highlighting should be as simple as possible so it can be easily overridden
4. Syntax highlighting and themeing more generally should utilize the minimum viable theme tokens or variables

Thinking about syntax highlighting ultimately opened some space to think a little bit more about colors, theme tokens, and their relation garden as a whole. You can find a post about that [here](/garden/03-extending-themes);

The approach I ended up taking, which is a design pattern I consistently fall back on, is defaults with fallbacks. To differentiate tokens in a block of code, I needed 6 colors. To accommodate undefined themes in a user config, I'm export a default color object from the theme and using that as a fallback. So now the syntax highlighting will be an extension of the current theme and fills in missing tokens with defaults. The one other thing I wanted to add was a way to define the highlighting theme based on some other theme in the config. An example: I want my syntax highlighting to be derived from the dark theme, no matter what theme is currently being used. This gives us three use cases/scenarios:

1. I didn't define any themes, so default.
2. I've defined themes. Just use those colors.
3. I've defined themes. I want to use a specific theme for syntax highlighting.

This ends up having a few moving parts:

``` js
  export const defaultColors = {
    text: '#2d2a24',
    background: '#fdfdfd',
    primary: '#b7e2d8',
    secondary: '#de7283',
    accent: '#bcadfb',
    muted: '#88d1ff'
  };
```

We need to export a set of default colors to generate the theme is a user doesn't define one. It gets imported into `App.js` and used during theme generation.

``` js
  const { themes = { default: { colors: defaultColors } } } = siteConfig;
```

In the theme function, we check if the user defined a specific theme to use for syntax highlighting, and fall back to the default color pallet if not.

``` js
  const prismTheme = pt ? themes[pt].colors : colors;
```

At that point, we have the variables available in the theme object and they get passed in.

### wrapping up

This ended up being a helpful exercise in moving from making something that works to thinking about how I wanted it to work and implementing from that direction. In thinking through different ways one would want to define their theme object, I think I also opened up space to think about extendability here and in future projects.

Working through this also highlighted the need for a different kind of post -- something shorter, and maybe just with code snippets. Next up is thinking about content directories and templating.

### resources

- [components.ai theme-ui](https://components.ai/theme-ui)
- [theme-ui color modes](https://theme-ui.com/color-modes)
- [prism theme generator](http://k88hudson.github.io/syntax-highlighting-theme-generator/www/)

### up next

- [x] syntax highlighting
- [x] [content directories](/garden/04-content-directories)
- [ ] templating


adding syntax highlighting to next-mdx-remote and rethinking themeing

02 - syntax highlighting and themeing


This post documents adding search to next.js powered static sites using [fuse.js](https://fusejs.io/). When deciding how to implement search functionality, I ended up choosing between a custom implementation (basically just filtering arrays) and using a dedicated library. While I tend not to reach for off the shelf solutions, I chose fuse because it has UMD and commonJS support and will likely be helpful to eventually build out the cli.

1. initialize fuse to search through the posts
2. hook up the search function to text input
3. return filtered list of posts

### initialize fuse

I'm adding search to the [garden page](/garden) because it already has access to all the post data needed to actually search. I have an array of posts with the following shape:

```js
  post = {
    content,
    frontmatter: {
      tags: [],
      title
    }
  }
```

Because it's searching a nested list, we need to tell fuse which fields to search for:

```js
  const options = {
    keys: ['content', 'frontmatter.title', 'frontmatter.tags']
  };
  const fuse = new Fuse(posts, options);
```

### hook up search input

We'll use a hook to keep track of the search value. The one extra piece here is [debouncing](https://css-tricks.com/debouncing-throttling-explained-examples/) the input. I like this a bit better than throttling since I'm guessing users will be entering single words rather than phrases.

```js
  import debounce from 'lodash.debounce';

  const [searchVal, setSearchVal] = useState('');

  const debounceQuery = debounce(val => setSearchVal(val), 333);
  const updateSearchVal = e => {
    const { value } = e.target;
    debounceQuery(value);
  };

  ...

  <input value={searchVal} onChange={updateSearchVal} />
```

### return filtered list of posts

Last thing to do is filter the posts based on the search criteria. The `else` statement resets the `postState` back to its initial state when the search field is empty.

```js
  const [postState, setPostState] = useState(posts);
  useEffect(() => {
    if (searchVal) {
      const filteredPosts = fuse.search(searchVal).map(p => p.item);
      setPostState(filteredPosts);
    } else {
      setPostState(posts);
    }
  }, [searchVal]);
```

### wrapping up

A tribute to fuse, to be sure, this was extremely easy. This logic will need to be extended at some point to do tag filtering, too, but that can wait until there's more content.

One thing that came up while working on this was the lack of syntax highlighting -- something I wholesale forgot -- so I'll be adding that next.

### up next

- [x] [syntax highlighting](/garden/02-syntax-highlighting)
- [x] [content directories](/garden/04-content-directories)
- [ ] templating


adding search to next.js powered static sites with fuse.js

posts tagged 'documentation'

03 - extending themes

02 - syntax highlighting and themeing

01 - searching with fuse.js