
Much of my thinking over the last year or so has been about [digital gardening](https://maggieappleton.com/garden-history). I've written about [rethinking the digital gardening metaphor](/garden/03-rethinking-digital-gardening) and started building out [digital-garden.dev](https://digital-garden.dev) as a place to practice some of that thinking. In really broad strokes, I'm interested in the following:

1. Low friction authoring: write in markdown, but the system you use takes care of the rest
2. alternative/anti-hierarchical data arrangements: no pagination, but easily parsed lists of information
3. relational data: content is not the 'thing'. relations between things is the 'thing'

Some of this is idiosyncratic and theoretical, but a lot of it is practical. I want to develop tools that allow people to quickly and easily create digital gardens. [digital-garden.dev](https://digital-garden.dev) was supposed to be that tool, but I wanted to try developing a package rather than  boilerplate for gardening. [`next-mdx-relations`](https://github.com/inadeqtfuturs/next-mdx-relations) is a lower level tool for gardening that provides a more agnostic api for generating pages from `md/x` and drawing relations between those files.

### overview

If you want to spin up an `md/x` powered `nextjs` site, you nearly always are going to write some boilerplate. Either you're using [`next-mdx`](https://github.com/vercel/next.js/tree/canary/packages/next-mdx) and letting webpack sort things out, or, more likely, you're using some kind of `mdx` parser like [`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote/) or [`mdx-bundler`](https://github.com/kentcdodds/mdx-bundler). In whatever case, you need to write functions for `getStaticProps` and `getStaticPaths` to generate paths and props for each page.

`next-mdx-remote` provides a really simple API that takes care of writing that boilerplate for you. Additionally, it allows for granular processing of `md/x` files and generating both extra metadata as well as relational data among static files in a collection.

### getting started

Install peer dependencies and package.[^1]

[^1]: I chose to keep these as peer dependencies in case you need functionality that `next-mdx-relations` doesn't offer. In that case, you have the raw material to glob, get the frontmatter, and serialize your markdown the way you like.

``` bash
yarn add fast-glob matter next-mdx-remote next-mdx-relations
```

Create a config file that imports `createUtils` from `next-mdx-relations` and both returns and exports functions for getting paths, pages, and pageProps.

``` js
// next-mdx-relations.config.js

import { createUtils } from 'next-mdx-relations';

export const {
  getPaths, // for `getStaticPaths`
  getPages, // for index page / `garden.js`
  getPageProps, // for `getStaticProps`
  getPathsByProp // for `[tag].js`
} = createUtils({
  content: '/content',
});
```

You get the following async helper functions

- `getPaths()`: use with `getStaticPaths` to get a list of file system based paths to your content
- `getPages()`: use in on your homepage to get a list of all your pages with accompanying frontmatter
- `getPageProps()`: use with `getStaticProps` to get your content and serialized frontmatter to pass to `next-mdx-remote`
- `getPathsByProp()`: use to make a tag page -- it returns a list of values of a given property from all of your content

If this pattern looks familiar, it's because it's heavily indebted to [stitches](https://stitches.dev/). I liked the idea of having the config file also be the place all of the package functionality is exported from. Additionally, this pattern allows you to have multiple instances of the package with their own scoped configurations. So if you have, like I did at one point, a blog and a garden, and those content types need to be handled differently, you can spin up two different configuration files (or put the `createUtils` function elsewhere) to handle either the blog or the garden.

Finally, create a `[...slug].js` file.

```js
// [...slug].js

import React from 'react';
import PropTypes from 'prop-types';
import { MDXRemote } from 'next-mdx-remote';
import { getPaths, getPageProps } from '../next-mdx-relations.config.js';

function Slug({ mdx, ...pageNode }) {
  const { frontmatter: { title, excerpt } } = pageNode;
  return (
    <article>
      <h1>{title}</h1>
      <p>{excerpt}</p>
      <MDXRemote {...mdx} />
    </article>
  );
}

export async function getStaticProps({ params: { slug } }) {
  const props = await getPageProps(slug);
  return {
    props
  };
}

export async function getStaticPaths() {
  const paths = await getPaths();
  return {
    paths,
    fallback: false
  };
}

export default Slug;
```

I've opted to use this catchall routing because it's the most generic way to handle routing. If you need something more granular, you can always make scoped catchall routes (ex. `/garden/[...slug].js`).

### meta and relational data

Relational data - the way things fit together, interact with each other, and (over)determine the meaning and value of other bits of data - seems to be the most important part of digital gardening. `next-mdx-relations` makes generating meta and relational data a first class feature by exposing two points of intervention when content is being processed.

``` js
const { getPageProps } = createUtils({
  content: '/content',
  // page level
  metaGenerators: {
    mentions: node => markdownLinkExtractor(node.content).filter(l => l[0] === '/')
  },
  // collection level
  relationGenerators: {
    mentionedIn: nodes => nodes.map((node) => ({
      ...node,
      meta: {
        ...node.meta,
        mentionedIn: nodes.filter(
          n => n.meta?.mentions.includes(`/${node.params.slug.join('/')}`))
      }
    }))
  }
})
```

In the above example, we use `metaGenerators` and `relationGenerators` to add extra meta and relational data to each page. `metaGenerators` work at the page or node level -- key value pairs have access to each `md/x` file in isolation. I'm using a package to return an array of links that point to local content. The return value is added to a node's `meta` object. `relationalGenerators` work at the collection level -- key value pairs have access to nodes after the `metaGenerators` have run. Unlike `metaGenerators` you can stash whatever the return value is anywhere on the nodes. Here, we see if any other node 'mentions' the current node, and add those nodes to the current's `meta` object. The result is a basic version of bi-directional links.

The above example is pretty straight forward, but achieves something slightly more difficult when working with static files alone. Additionally, `metaGenerators` can be used to generate data or mutate content outside of the markdown serialization.

### to follow

This is early days for the api. I'm still working out ways to keep things on the rails and not mutate data that shouldn't be, but I'm excited about what this has enabled me to build and what it might help others build, too.

Check it out on [github](https://github.com/inadeqtfuturs/next-mdx-relations).


nextjs, graphql, sequelize starter

site refresh

next-mdx-relations


A lot has changed since I last worked actively on my blog/site. The previous iteration, which I released early in 2019, was built on technology I really liked at the time: [gatsby](https://www.gatsbyjs.com/) and [emotion](https://emotion.sh/docs/introduction). As time went on, really simple things became more and more difficult to do -- gatsby's data layer would break; plugins would need to be upgraded but would break the build process; the idiosyncratic theme I built in emotion became cumbersome and prevented me from actually making updates. In the interim, I had worked a lot with [nextjs](https://nextjs.org/) and really enjoyed the simplified data fetching I could do with `getStaticProps`. Having worked with `nextjs` to build [digital-garden.dev](https://digital-garden.dev), I decided to migrate *inadequate futures* over as well.

### overview

The major impetus for this update was to better showcase the work and writing I had been doing. The previous version of *if* was purposefully minimalist but that minimalism said less about what I was interested in working on and more about my design aesthetics. The homepage, just my name, job title, and a brief missive about what I do ('build elegant, responsive, and speedy software...') felt like an under- if not misrepresentation of my work and what I actually do. Additionally, many of the choices I made in the UX and design of the site ran against the grain of what I've learned to build and like. The work section, for example, was built out using a carousel, a design pattern I loathe both in terms of user experience and building, and showcased work that I haven't touched in years. In terms of writing, I had bifurcated my 'blog' from the 'garden', a demarcation that doesn't quite make sense to me from this vantage. Finally, the 'about' page was kept purposefully vague - something I thought I would update later but never did.

With this in mind, I wanted to make a few basic improvements:

1. a home page that more accurately describes/demonstrates my current interests and work
2. a single 'garden' section that can house all my writing. A list of posts is enough
3. a 'work' page that lists recent work and that is not a carousel
4. an about page that more accurately reflects my past/previous work and the role I see myself in going forward

With these things in mind, and with a basic design I made in figma in hand,[^1] I set off to do the heavy engineer lifting.

### gatsby → nextjs

I moved over to `nextjs` for a few reasons. First, it's what I've reached for both professionally and to build side projects for the last two years. The API feels very minimal and lightweight, it's fairly agnostic about how you load assets, and the build process is extremely fast. Second, I really like next's routing for generating static sites. I have a `[...slug].js` catch-all route for blog pages that exports a `getStaticPaths` and `getStaticProps` function. `getStaticPaths` returns an array of paths based on a folder with markdown files in it, and `getStaticProps` processes the markdown to render to the page. I can use the same `getStaticProps` functionality to get specific markdown files to generate specific pages, like the index or about page.

In broad stokes, I think `nextjs` provides one of the quickest ways to get a site built with React up and running.

### emotion → stitches

I've worked with both emotion and styled-components in the past, and I've built a theme generator and component library called [if-sf](https://github.com/inadeqtfuturs/if-sf), which is built on styled-components and [theme-ui](https://theme-ui.com/). While I really enjoy working with these technologies, I wanted to take the opportunity to try out some of the new styling systems that have emerged over the last two years. Having worked with [tailwind](https://tailwindcss.com/) on my [spotify dashboard](https://github.com/inadeqtfuturs/spotify-dashboard), I decided to try out [stitches](https://stitches.dev/) because it seemed lightweight, performant, and minimalist.

In addition to the `stitches.config.js` at the root of the project, which handles the theme object, I also wrote a `globalStyles.js` to define styles at the element level. Using `stitches`'s `global` function, it's easy enough to import these styles into my `_app.js`. While this works, I did miss how `theme-ui` took care of my mdx styles for me, and I hope this global element styling is something `stitches` can integrate into their existing api.

### next-mdx-relations

Having worked with `md/x` powered `nextjs` sites in the past, I had grown tired of writing boilerplate for getting file globs, parsing the markdown, and generating file paths to work with the catch-all `[...slug].js`. One of the goals in building [digital-garden.dev](https://digital-garden.dev) was to re-think the statically generated site in slightly more relational terms. Without a database, what and where is the best way and place to draw relations between these static files?

I wrote `next-mdx-relations` to try to answer this question. build on top of `next-mdx-remote`, another solution for parsing markdown for `nextjs` sites, `next-mdx-relations` provides two key things:

1. A set of utilities for generating paths and parsing markdown. No more boilerplate -- just give it the folder your content lives in and it handles the rest
2. An API that allows users to intervene at crucial points in the processing. Users can add extra metadata without writing to the markdown file, and has access to ALL files to generate relations between them

It's early days for `next-mdx-relations` -- I'm actively dogfooding it on this site -- but I'm already thinking that it's where I'll be working through some [questions I've asked](/garden/03-rethinking-digital-gardening) about digital gardening. I'd like for it to eventually power [digital-garden.dev](https://digital-garden.dev). In the mean time, you can check out the [github repo](https://github.com/inadeqtfuturs/next-mdx-relations).

### garden

I'm hoping this refresh returns me to the garden. I have some ideas for extending `next-mdx-relations` that would be useful for other digital gardens and I'm looking forward to working those things out.

[^1]: There is a longer and more interesting version of this post that talks through some of the design decisions, but I'm not a designer. Maybe for another time.
