
Documentation takes many forms. Often we talk about documentation within our code, like inline comments describing or annotating a function or piece of code. We also talk about tests and specs as a kind of documentation, where tests provide a source of truth for a function's input and result. I see this kind of documentation as tied up in and with the codebase. It's there for the developer, but, more often than not, it's actually "there" for a language server protocol (inline comments) or a CI/CD pipeline (test suite) to ensure that the code is doing what it's supposed to do. This kind of documentation is extremely important and makes working in a codebase much easier, but it's not the only documentation we need.

Documentation for human readers does and should take a different form because human readers are neither lsps or CI/CD pipelines. Sometimes we need to create documentation about how our codebase interacts with an external system or saas. Ideally there is infra-as-code, but often we just need a reminder of what buttons to click in a CMS somewhere. Other times, a codebase has unique internal procedures and systems that need to be described in order to be used. In each case, we need documentation that provides a conceptual as well as practical overview.

The kind of documentation I'm thinking about is harder to write than documentation in and as code because it's not tied into a system of 1:1 input/output. It might seem obvious that two people reading the same document will not get the same thing out of it, but we also want to cultivate strategies, systems, and templates that make it likely that anyone with some amount of technical understanding (your peers) could read the documentation and understand it.

However, in trying to outline some parameters for creating internal documentation for other developers on my current team, I found external resources lacking. Most writing about documentation emphasizes one of two things: how *code* should be documented (either within docs as code blocks or within the codebase itself with comments and spec) OR tools that teams can use to create documentation. In both cases, the emphasis misses the actual form documentation takes either by narrowly focusing on code or too broadly gesturing towards a metaframework to help with organization. The question I wanted to answer was, "What does the writing look like for internal documentation?"

Articles about documentation often focus on writing opensource documentation. However, opensource docs are geared towards the user of a product, rather than someone that is actively working on the product. While some contribution guidelines model the kind of writing I was thinking about, not many have written publicly about creating documentation for an internal team.

Additionally, the writing I did find about documentation tended to be vague on how to best to structure docs. This made some sense: the structure documentation takes depends largely on what you're documenting, the project you're working on, and even who and how many pepople are working on it. However, what I was finding was that different developers on my team were writing radically different kinds of documentation formally, grammatically, structurally, etc. What I wanted was something to guide their thinking so that we were all contributing the same *kind* of documentation.

Inspired by the idea of an [opionated framework](https://opinionatedreact.com/)[^1], I've started writing an "opionated guide to internal documentation". This is geared at standardizing the way documenation is written within a team, the goal being the creation of documentation that likely communicates, explains, or otherwise transfers knowledge between team members.

You can find it below or linked [here](https://gist.github.com/inadeqtfuturs/46466d91ce9ea048c87172631c5ed8c3).[^2]

This is an in progress document and is meant to be opionated rather than authoritative.

```markdown
---
title: opinionated documentation
---

# Opinionated Documentation

This guide outlines some principles for writing internal documentation. The scope of this guide is narrow and is adapatable depending on the project and team size.

## Consider the reader

The reader is most often going to be another developer. Because of that, we can assume some level of familiarity with the code base, language/framework, or service we're writing documentation for. Consider some of the following when writing:

- Opt for explicit instructions rather than implicit. I.e. tell the reader exactly what to code. Tell them what to click in the service you're writing about.
- Provide copy and paste-able code blocks.
- Explicitly reference files that need to be updated or that stand as an example of what is being documented.
- Docs should be skimmable/scannable, so opt for descriptive headings and clear topic/introductory sentences.
- File names and topics should be easy to find by looking at file names and/or `grep`ing the docs folder.

## Write Consistently

The documentation should be consistent with the rest of the documentation in the repo. That is, it should follow a similar format (see below) and voice of other pieces of documentation. Just as we have a consistent code style within the repo, we should have a consistent documentation style within the repo.

In general, write with a neutral tone and/or the tone consistent with the documentation in the repo.

## Instruction vs. Explanation

Docs can take two (of many) shapes: instructive and explanatory. Instructive docs tell a dev what to do to implement a feature, like adding a new slice to redux. Explanatory docs explain why a codebase, process, file, or function is written or how it works. Docs are often a combination of the two, but it's usually best to separate instuctions from explanations.

In the following example, we provide a few things:

1. A brief overview of the feature/thing we're talking about
2. Explicit step-by-step instructions for implementing/working with the thing
3. An explanation of *why* we've opted to do it this way
4. (Optional) A list of resources related to the thing if the reader is unfamiliar

### Example

\``` markdown
# Topic

## Subtopic

Brief explanation of what subtopic is

1. Instructions
2. For implementing
3. Subtopic

Brief explanation of why we've decided to implement feature or whatever this way.

## Resources

- [Resource](link)
- [Resource](link)
- [Resource](link)
\```

## Breaking Down a Topic

Depending on what you're documenting or the size of the codebase, a flat list of markdown files might not be the best form for documentation. Consider the following:

- Are you documenting something isolated and singular, or something that's part of a larger system? A folder might house multiple pieces of documentation about a system or a topic that has many discrete parts. An example might be a "State Management" folder with separate files for things like reducers, actions, hooks, and how the codebase tends to structure state.
- When a single file gets too long (hundreds of lines), it might be time to rethink its structure and break it into multiple files. The headings in the original file are helpful for creating the new files.
- Use relative links to link between documents.

## Formatting

- Use properly formatted markdown.
- Provide a semantic and skimmable hierarchy of information by using headings.
- Use lists for instructions. Numbered lists are good for sequences, whereas unordered lists are good for general tips/suggestions.  
- Add a single white space between semantic elements in the markdown.

## Resources

- [Write the Docs - Documentation Principles](https://www.writethedocs.org/guide/writing/docs-principles/#arid)
- [Write the Docs - Introduction to Markdown](https://www.writethedocs.org/guide/writing/markdown/)

```

[^1]: I see turning to an opionated framework as trusting someone else's expertise. It also decreases friction by decreasing the amount of decisions that *you* have to make in order to get a project up and running or write a piece of code. It's why we have styleguides, linting, and other guardrails when we code.
[^2]: Note to create a little code block that just shows the live raw of the gist. For another day.


nextjs, graphql, sequelize starter

opinionated guide to internal documentation


I recently started working on a new project and wanted to use NextJS across the stack. I thought it would be pretty straight forward to set up graphql api routes, but it ended up taking much longer to spin the project up than anticipated. I ended up abstracting the project architecture into a starter repo, which can be found [here](https://github.com/inadeqtfuturs/nextjs-sequelize-graphql-starter).

A brief overview:

- This is a full stack NextJS project that uses GraphQL api routes to interface with sequelize and a postgres database.
- The repo is diveded up into three sections: `database` for sequelize, `graphql` for the GraphQL schema and resolvers, and `src` for the frontend.
- Creating a new model is basically 2 steps: generate/define the model in sequelize, and then write the schema/resolvers in GraphQL.
- Because I was working on this while traveling (i.e. without internet access), it uses a project scope installed `sequelize-cli` and GraphQL Playground
- It frequently used sequelize commands aliased to `yarn`.
- The project can be deployed to Vercel or Netlify and hooked up to a Heroku hosted postgres (or whatever you prefer) database

The starter repo also comes with an example migration, model, and seed, as well as an example GraphQL schema and resolver with full CRUD operations.

If you're looking to quickly spin up a full stack NextJS project without configuring everything from scratch, this might be for you.


next-mdx-relations


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).


site refresh


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.


generating theme tokens


I'm working on a theme/token generating library based on [theme-ui](https://theme-ui.com/) and [emotion](https://emotion.sh/docs/introduction). I've found myself using some variation of the same theme object across projects, but as I iterate on that object either improving it or tweaking it, I find it increasingly difficult to keep different versions up to parity. An example: I update how I'm using breakpoints in one so I need to go through each project and update the breakpoints there.

One solution would be to publish the theme object as an npm package, but I wanted something a little more dynamic. [speculative fabulation (or sf)](https://github.com/inadeqtfuturs/if-sf) generates theme tokens (ex. colors, typography, buttons) as well as theme objects (ex. an object comprised of theme tokens). These can be passed into `emotion`'s or `styled-components`'s theme provider. `sf` operates on the idea that objects go in, objects come out -- you can extend, merge, or override theme defaults, allowing granular control over the theme you generate:

``` js
const defaultTheme = genTheme();
const defaultThemeWithNewColor = genTheme({ colors: { newColor: '#333' } });
```

Both functions return a full theme object, but you can drill down and update the specific tokens you need.

### token generators

`genTheme()` is broken down into a series of token generators -- functions that return a token object, like colors or styles for a button. In working on these token generators, I set up a few parameters for how they should behave:

0. generator files export a token object
1. generators return a token object
2. generators don't require arguments to return the token object
3. generators merge and extend the token object by default
4. generators can wholesale override the token object

For something like colors, this is simple enough:

``` js
import { merge } from 'theme-ui';

const defaultColors = {
  text: '#111827',
  background: '#F9FAFB',
  primary: '#2563EB',
  secondary: '#DE7283',
  accent: '#7C3AED',
  muted: '#88d1FF'
};

export function genColors({ override, ...restColors } = {}) {
  if (override) {
    return override;
  }
  if (!restColors) {
    return defaultColors;
  }
  return merge(defaultColors, restColors);
}

export default defaultColors;
```

By default, `genColors()` returns `defaultColors`. If we pass an `override` argument, it will return that object instead. Any other key/value pair we pass gets merged into default colors.

### token generators -- deep and defaults

Things became slightly more complicated as I began working with typography. In the past, I've defined a default text base that includes things like font size, line height, and font family, spreading that object into each typographical element (i.e. p, ul, blockquote, etc.) (I'm ultimately leveraging the `theme.styles` object from [theme-ui](https://theme-ui.com/styling-mdx)). This works for the first two generator requirements -- have a base set of styles; spread them into each element, return that:

``` js
export const defaultTextBase = {
  fontFamily: 'body',
  fontSize: ['sm', 'md'],
  lineHeight: 1.5,
  margin: 0,
  padding: 0,
  marginBottom: 4
};

const defaultText = {
  p: {
    ...defaultTextBase
  },
  ul: {
    ...defaultTextBase,
    paddingLeft: 8,
    ul: {
      margin: 0
    }
  },
  ...
}
```

The problem starts when I want to extend or merge styles into the base: if we're just spreading `defaultTextBase` into these elements, at what point do we actually merge or extend the base? One way to solve this would be to iterate through the keys in `defaultText`, spreading the base as we went, but this would prevent us from exporting an object from the generator file. Another way to handle this would be to get a diff between the new base and default base -- after all, we're just extending or merging into it. However, this presents an immediate problem if we're going to wholesale override the base at some point. So I ended up writing a utility that removes the default values (if present) from each element.

``` js
function removeDefaults(obj, defaultObj) {
  const defaultKeys = Object.keys(defaultObj);

  // mapObject does what it sounds like: allows us to map the key/value pairs in an object
  // mapObject = (obj, func) => Object.fromEntries(Object.entries(obj).map(func));
  return mapObject(obj, ([key, value]) => {
    const remainingValues = Object.keys(value).reduce((acc, curr) => {
      if (defaultKeys.includes(curr) && defaultObj[curr] === value[curr]) {
        return { ...acc };
      }
      return { [curr]: value[curr], ...acc };
    }, {});
    return [
      key,
      {
        ...remainingValues
      }
    ];
  });
}
```

Once the default values are removed, we can determine the new base (overriding, merging into, or extending the default base) and use the above `mapObject` function to pass that base into each key. You can see the full implementation [here](https://github.com/inadeqtfuturs/if-sf/blob/main/src/theme/tokens/text/index.js)

### spread defaults // remove defaults

Something about this pattern seems useful, though I'm not entirely sure where. It goes something like this:

1. Have a default base
2. Spread that default base into each key of a token object. Export that object.
3. If you need to extend or override that base, use the above function to remove those defaults
4. Return new object using new base

I like this pattern, though I think it fits a specific use case. I do think it could be used in a more generalized way, and I'd be interested to hear alternative approaches to the above problem.


markdown, dynamic routes, next.js

I'm currently building out a new digital garden over at [digital-garden.dev](https://digital-garden.dev) and writing about the process. The foundations are [next.js](https://nextjs.org/) and [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote), and I'm using them to generate static pages on build. This is a brief overview for working with dynamic routes and static generation in next.js.

### generating static pages

There are two important functions we use to generate static routes at build time with next.js. The first is `getStaticProps()`, which fetches data at build time and generates a page based on that data. The other is `getStaticPaths()`, which returns an array of paths that next.js will statically pre-render. While you can use `getStaticProps()` alone, it's helpful to see these working in tandem with one another. We generate a list of paths using `getStaticPaths` and pass that array to `getStaticProps`, which will process or fetch the data we need and generate the pages. We can also think about this in terms of file structure:

``` js
/posts
│   post-01.mdx
│   post-02.mdx
/pages
│   _app.js
│   _document.js
│   index.js
└───/posts
    │  [slug].js
```

In the file `/posts/[slug].js` (this path will become important later), we'll export `getStaticPaths`, pointing it at the `/posts` directory, getting a list of all the file paths we want to render. We'll additionally export `getStaticProps`, which will generate paths and pages for our mdx files at `/posts/post-01` and `/posts/post-02`. The `[slug].js` file can catch any mdx file in the `/posts` directory and generate a path and page for that mdx file. All the pages we generate will have a prefix of `/posts` because that's where the `[slug].js` file lives. We could similarly have `/notes/[slug].js` and generate pages with `/notes` as the path prefix.

### getStaticPaths // getStaticProps

Using our example repo, we can export a function called `getStaticProps` that looks like this:

``` js
import { promises as fs } from 'fs';
import path from 'path';
import glob from 'fast-glob';

...

const content = './posts';

export async function getStaticPaths() {
  // 1. define where the content is
  const contentGlob = `${source}/**/*.mdx`;
  // 2. get a list of files
  const files = glob.sync(contentGlob);
  // 3. if there are no files, return an empty array
  if (!files.length) return [];

  // see below
  const paths = await Promise.all(
    files.map(async filepath => {
      const slug = filepath
        .replace(/^.*[\\\/]/, '')
        .replace(new RegExp(`${path.extname(filepath)}$`), '');
      return { params: { slug } };
    });
  );

  return {
    paths,
    fallback: false
  };
}
```

This function allows us to define where our content is and get a list of markdown files. We then map over the array of files, getting the file name without the extension (`path.extname(filepath)`) to use as our slug. However, because `getStaticProps` is expecting an array of objects that contain a `params` key, we need to return an array of objects rather than just a list of paths. `paths` ends up looking like this:

```js
paths = [
  { params: { slug: 'post-01' } },
  { params: { slug: 'post-02' } }
]
```

Now that we have the paths, we need to generate the pages. We'll export `getStaticProps`, which takes our paths as an argument:

``` js
import renderToString from 'next-mdx-remote/render-to-string';
import matter from 'gray-matter';

...

export async function getStaticProps({ params: { slug } }) {
  const contentGlob = `${source}/**/*.mdx`;
  const files = glob.sync(contentGlob);
  if (!files.length) return [];

  const posts = await Promise.all(
    files.map(async filepath => {
      const fileSlug = filepath
        .replace(/^.*[\\\/]/, '')
        .replace(new RegExp(`${path.extname(filepath)}$`), '');
      // 1. read the file
      const mdxSource = await fs.readFile(filepath);
      // 2. use `matter()` to return the content and the frontmatter (data)
      const { content, data } = matter(mdxSource);
      // 3. render the mdx to string
      const mdx = await renderToString(content, {
        // we're not passing any custom components
        // see https://github.com/hashicorp/next-mdx-remote
        components: null,
        scope: data
      });

      return {
        slug: fileSlug,
        mdx,
        frontMatter: { ...data }
      }
    })
  );

  // make sure the path you hit actually has a post
  const [blogPost] = posts.filter(post => post.slug === slug);
  if (!blogPost) {
    // eslint-disable-next-line no-console
    console.warn(`No content found for slug ${slug}`);
  }

  return {
    props: {
      mdxSource: blogPost.mdx,
      frontMatter: blogPost.frontMatter
    }
  };
}
```

The first bits of code should look very similar. We're grabbing all of our content and generating slugs again. The difference here is we're also *reading* the file, getting both the frontmatter and the content of the post. The rest of the function just makes sure that when you hit a given path a post actually exists there. It returns what you'd need to render a post -- the source or content, and the frontmatter.

This is a really basic example of what you can do with static generation in next.js. But I also suspect a lot of folks will end up working with it to make static blogs, so hopefully this is helpful boilerplate.

### dynamic routes

In working on [garden](digital-garden.dev), I wanted to take dynamic routes a step further and allow for dynamic path prefixes based on where content lived. Let's return to the content directory example:

``` js
/content
└───/posts
    |   post-01.mdx
    |   post-02.mdx
└───/notes
    |   note-01.mdx
    |   note-02.mdx
```

Instead of a flat `/posts` directory, I now have a nested content directory. I want to be able to generate paths for my posts and notes based on their file path. A few ways you could do this.

1. In addition to `posts/[slug].js`, add an additional `notes/[slug].js` to catch the notes. The major downside here is just code repetition. It also requires adding a new directory to `/pages` every time there's a new kind of content.
2. Use a catch all route, so something like `[...slug].js` at the root of pages. This can end up being a bit mess as you get deeply nested routes (though it's something I'm thinking about now).

The solution I came up with is to have a catch all file at `/[path]/[slug].js` that generates paths that are one level deep (think the posts, notes, etc model) and keeps the slug logic intact. 

The first thing to do is update the `getStaticPaths()` function to return an array of objects with the shape `{ slugPath, slug }`. We'll also update `source` to be an array of strings that point to where our mdx files live.

```js
const contentSource = ['content/garden', 'content/note'];

export async function getStaticPaths() {
  const files = contentSource.reduce((acc, src) => {
    // using process.cwd() based on next.js documentation
    // https://nextjs.org/docs/basic-features/data-fetching#reading-files-use-processcwd
    const contentGlob = `${path.join(process.cwd(), src)}/**/*.mdx`;
    const files = glob.sync(contentGlob);
    return [...acc, ...files]
  }, [])

  if (!files.length) return [];

  const paths = await Promise.all(
    files.map(async filepath => {
      // get file name and use as slug
      const slug = filepath
        .replace(/^.*[\\\/]/, '')
        .replace(new RegExp(`${path.extname(filepath)}$`), '');
      // get parent folder and use as slugPath
      const slugPath = path.dirname(filepath).replace(/^.*[\\\/]/, '');

      return { params: { path: slugPath, slug } };
    })
  )

  return {
    paths,
    fallback: false
  };
}
```

Using a reducer instead of a map, we end up with something like this:

```js
paths = [
  { params: { path: 'posts', slug: 'post-01' } },
  { params: { path: 'posts', slug: 'post-02' } },
  { params: { path: 'notes', slug: 'note-01' } },
  { params: { path: 'notes', slug: 'note-02' } }
]
```

This is not radically different than the initial example. Notice that we're just grabbing the parental directory name and passing that in as one of our params. Also notice that in the param object, we have two keys -- path and slug -- which correspond to our folder structure. `getStaticPaths` is going to expect these two keys to be in each `params` object, and we should update the `getStaticProps` to check for them:

``` js
export async function getStaticProps({ params: { path, slug } }) {
  ...
  const posts = await Promise.all(
    files.map(async filepath => {
      const slug = filepath
        .replace(/^.*[\\\/]/, '')
        .replace(new RegExp(`${path.extname(filepath)}$`), '');
      // get parent folder and use as slugPath
      const slugPath = path.dirname(filepath).replace(/^.*[\\\/]/, '');

      ...

      return {
        slug: `/${slugPath}/${slug}`,
        mdx,
        frontMatter: { ...data }
      }
    })
  );

  // make sure the path you hit actually has a post
  const [blogPost] = posts.filter(post => post.slug === `/${slugPath}/${slug}`);
  if (!blogPost) {
    // eslint-disable-next-line no-console
    console.warn(`No content found for slug /${slugPath}/${slug}`);
  }
}
```

A small update, but we're making sure we get the correct content.

### wrapping up and future thinking

There's surely room for improvement here: a better way to handle slugs, perhaps a different way to catch routes (especially if we want deeper nested routes). However, if you need to spin up something quickly, this might be a good way for thinking about it.

### further reading

- [garden](https://github.com/inadeqtfuturs/garden)
- [mdnext](https://github.com/domitriusclark/mdnext/)
- [next.js](https://nextjs.org/)
- [next-mdx-remote](https://github.com/hashicorp/next-mdx-remote)


building tag pages with nextjs


High level overview for making index pages for each tag in your mdx/nextjs blog.

0. setup/assumptions

We'll use [`getStaticPaths` and `getStaticProps`](https://nextjs.org/docs/basic-features/data-fetching#getstaticprops-static-generation) to statically generate the tag pages. If a tag exists, we'll have a route like `site.com/tags/${tag}`. To do this, we'll set up a 'tag' folder with a `[slug].js` file in the pages folder.

I'm assuming that you already have tags in your frontmatter, and that you have some way of getting an array/list of all your posts. I highly recommend taking a look at [mdnext's utility file](https://github.com/domitriusclark/mdnext-blog/blob/master/src/utils/get-mdx-content.js) and this function in [next.js's blog example](https://github.com/vercel/next.js/blob/canary/examples/blog-starter/lib/api.js). Also worth taking a look at [`next-mdx-remote`](https://github.com/hashicorp/next-mdx-remote#example-usage) both as an example and as because it's an excellent library for doing this.

1. get all posts

We need to get all our tags to generate a list of paths. We can do this in the `getStaticPaths` portion of the `[slug].js` file.

```js

export async function getStaticPaths() {
  const posts = await getAllPosts(directory);
}

```

2. accrete all tags

Next, we'll reduce those tags into a single array of strings.

```js
export async function getStaticPaths() {
  const posts = await getAllPosts(directory);
  const blogTags = posts.reduce((acc, { frontMatter: { tags } }) => {
    const newTags = tags.reduce((newAcc, tag) => {
      if (acc.includes(tag)) {
        return newAcc;
      }
      return [...newAcc, tag];
    }, []);
    return [...acc, ...newTags];
  }, []);
  const paths = blogTags.map(tag => ({
    params: {
      slug: tag
    }
  }));
}
```

Here, we're using a nested reducer -- for each array of tags in a post, we check if that tag exists in the accumulator for the `blogTags`. If it's already in there, like if another post already had that tag, we skip it, otherwise, we toss it into an array called `newTags` that we can spread into the `blogTags` acc. I like doing this rather than using a `forEach` and `push` because it's immutable.

3. use those tags to form pages

Now that we have an array of tags, we pass them as our paths parameter to the return value.

``` javascript
export async function getStaticPaths() {
  const posts = await getAllPosts(directory);
  const blogTags = posts.reduce((acc, { frontMatter: { tags } }) => {
    const newTags = tags.reduce((newAcc, tag) => {
      if (acc.includes(tag)) {
        return newAcc;
      }
      return [...newAcc, tag];
    }, []);
    return [...acc, ...newTags];
  }, []);
  const paths = blogTags.map(tag => ({
    params: {
      slug: tag
    }
  }));

  return {
    paths,
    fallback: false
  };
}
```

4. get posts associated with tag for each page

For each tag pages, we want to grab the associated blog posts. So we're grabbing all our posts and filtering to see which posts' tags include whatever the slug is.

```js
export async function getStaticProps({ params: { slug } }) {
  const posts = await getAllPosts(directory);
  const blogPosts = posts.filter(post => post.frontMatter.tags.includes(slug));

  if (!blogPosts) {
    console.warn(`No content found for tag ${slug}`);
  }

  return {
    props: {
      posts: blogPosts,
      tag: slug
    }
  };
}
```

We're returning the associated blog posts and the given tag. We can then doing something like this:

```js
export default function TagIndex({ posts, tag }) {
  return (
    <Layout>
      <h2>posts tagged {tag}</h2>
      {posts.map(post => (
        <Excerpt post={post} key={post.slug} />
      ))}
    </Layout>
  );
}
```


garden webpack plugin (or, bidirectional linking)


Thinking about building (a) digital garden(s) has helped solidify the kinds of tooling I'd like to use to write and create relations among writing. In building out a version of my digital garden, these are the features I think I'll need:

1. bi-directional links: Donna Haraway tells us, 'Nobody lives everywhere; everybody lives somewhere. Nothing is connected to everything; everything is connected to something' (*Staying with the Trouble* 31). This is echoed in the model of my thinking or how I'm thinking, but it also reminds us that cognitive and note keeping models can allow us to connect seemingly disparate nodes or ideas. It's not that everything leads to everything else, but everything leads to something else, which is potentially everything else.

2. link preview (internal): internal preview links are a helpful quality of life feature that allows you to preview where you're heading. Prevents tab bloat.

3. flat lists: in the [preview post](/garden/03-rethinking-digital-gardening), I talked about trying to think a antihierarchical model of data relation. Flat lists give us access to everything at once or in one place, while relationships can add the perception of depth. Relations among data can be cultivated by the author (initial implementation), but I'm also thinking about how readers traverse this topography.

4. tags: tagging allows the accretion of information -- suddenly you have 50 things tagged with 'x' -- whereas categories predetermine what information is important. Rather than writing *for* a particular category or topic, I'm interested in the tags and ideas that become important over time.

5. cli: generate files with frontmatter for new posts. Better than code snippets (bound to editor) and will always have parity with what the garden is expecting.


(re)thinking the digital garden

digital garden tooling


The idea of utilizing a [digital garden](https://maggieappleton.com/garden-history) as a way of learning in public (over and against the practice of monetizing the self) is extremely appealing and simpatico with some things I'm trying to develop around issues of knowledge, community, and access in web development. In beginning to think about the content and structure of my own digital garden, or in thinking about what an ideal digital garden would be, I've spent a lot of time considering the metaphor of gardening. What I appreciate about Mike Caufield's description ('Every walk through the garden creates new paths, new meanings, and when we add things to the garden we add them in a way that allows many future, unpredicted relationships' [['The Garden and the Stream: A Technopastoral'](https://hapgood.us/2015/10/17/the-garden-and-the-stream-a-technopastoral/)]) is that it places central focus on the user -- the person navigating the garden. What I want to think a bit more about is gardening as a socio-spatial metaphor and practice. Who gets to garden? Where does the garden come from, or what space does the garden occupy? What counts as gardening?

### [aside]

[To lay some cards on the table, I'm interested in working towards a workflow and relational structure that enables the proliferation of free learning resources. I see digital gardening as a great way for people to (1) develop their ideas through iterative practicing and writing in public and (2) find others' writing, which might in turn help them. I see digital gardening as a reciprocal practicing in a larger ecology of knowledge practicing(s), and I see it as potentially beneficial for lowering the barrier to entry for a lot of the work that I do as a software engineer.

In this note, I'm attempting to stay very high level about some of the questions I'm thinking through and allowing some of these concepts to develop further later on.]

### gardens have walls

One major upshot of digital gardening, over and against formal blogging, is that it promotes a transitory and provisional style of writing. Gardening allows, if not encourages, us to write more for ourselves and others -- notes, working examples, missives, among other things. One thing that was exciting to learn was the amount of thinking happening around non- or antihierarchical models of knowledge in digital gardening. One example is [Aravind Balla's blog](https://notes.aravindballa.com/), which takes an index page as a central nodal point (it's where the site begins) and moves outwards to different posts or notes. The spatial arrangement helps to refuse an informational hierarchy the privileges a kind of performance of mastery (what Maggie Appleton identifies as 'cultivated performance' [['A Brief History of the Digital Garden'](https://maggieappleton.com/garden-history)]) in favor of allowing the user to move between informational nodes.

This arrangement also highlights one of the problems with the garden metaphor: gardens are bounded and domesticated spaces. A garden has a wall and the wall is meant to keep some things in and some things out. We can see Mr. McGregor chasing Peter Rabbit from the garden as an apt metaphor for young learners being kept from cultivated knowledge. I don't want to be the gardener keeping others from tilled soil, and as generous as a gardener can be with others, it doesn't negate the way gardens (literally and metaphorically) delineate space outside larger ecologies. In some ways, it makes sense to talk about a digital garden in a larger ecology that is the internet or that is a set of knowledge practices. So maybe what I'm trying to say is that 'digital garden' is an apt metaphor for internet writing, but one I want to think around or beyond rather than within.

The concept of the '[quoteback](https://quotebacks.net/)' is helpful here because it pulls in information from beyond the garden walls, drawing from the larger digital ecology we inhabit.

### gardens are anti-ecological

When I think about digital gardens as being 'anti-ecological', I mean that digital gardening can quickly become a kind of feedback loop that devolves into the 'cultivated performa[tivity]' Maggie Appleton describes in her article. I'm interested in the question of who and what is the garden for? If it's to learn in public, I see it as serving a few disparate audiences:

1. The gardener: I want to use the garden to test out and develop ideas for myself. I want to write notes that I can return to. I want to allow those notes and ideas to accrete into something beyond their own scope.
2. The garden wanderer: I want to offer pieces of information to help others. I want what I know and what I've learned to be freely accessible to everyone.
3. The onlooker: I want to demonstrate my thinking and abilities in a publicly facing forum as a stand in for or augmentation of credentials.

In general, I'm interested in thinking in service of the gardener and wanderer rather than the onlooker. For one, the onlooker (again: literally and metaphorically) doesn't inhabit the garden -- they do not participate in its co-constitution. Second, in serving the gardener and wanderer, digital gardening can cultivate an alternative topological arrangement that does not necessarily entail walls. What I'm trying to think through is the relation between public, ecology, and gardening (as a practice). This is what I mean when I say I am thinking about gardening as a socio-spatial metaphor and practice -- can we use gardening to develop a more robust ecology for learning? How is the practice of learning in public related to the co-constitution of what we might call 'alternative ecological arrangements'?

### gardens are tilled and disciplined

Your garden doesn't contain everything -- you've selected seeds and tilled the soil carefully to plant them in the hopes that something grows. While I want to hold on to projection into the future, I wonder what would come from resisting or modulating that selection impulse. I am thinking about this in terms of both form and content:

- Blogs and posts are linear whereas our gardens can be rhizomatic -- what are some alternative approaches to authoring and presenting information? What might these alternatives elucidate for both reader and writer?
- Blogs tend to focus on one topic -- what can we learn from other forms of content curation and production (even as I try to avoid 'content production' as a practice) that are multi-layered and multi-modal? What comes from juxtaposing different kinds of stuff?

What I'm wondering about and thinking towards is not so much the standard blog augmented by personal musings. I'm instead wondering about how differing modalities of thought transposed onto other content might elucidate new forms of knowledge practicing(s) (I'll leave this open ended).

### digital garden v. digital gardening

I want to stick with the term digital garden by dragging along or pulling into focus the practice of digital gardening. I want to reshape some of the issues I've outlined above by continuing to practice digital gardening. This means experimenting with low friction authoring, alternative data arrangements that lack explicit hierarchy, and presentational layers.

### further reading

- [Tom Critchlow's Blog](https://www.notion.so/ifdesign/examples-abbedb239c984882ba76301fb2158455#b65447849b4740fb9960707e9ed1f648)
- [johno's digital garden starter](https://www.notion.so/ifdesign/examples-abbedb239c984882ba76301fb2158455#30fa6dd5d4b24f4294b3111d08925e3d)
- [Setting up your own digital garden with Jekyll 🌱](https://maximevaillancourt.com/blog/setting-up-your-own-digital-garden-with-jekyll)

styled system, variants, overrides

[Styled System](https://styled-system.com/) offers some robust tools to build out a themeable component library based on design tokens simply by using a unified theme object. In this post, I want to think about how to set up reusable component variants -- components that are functionally the same but visually different -- and how to override these default values when necessary.

### styled system and design tokens

One reason to use something like Styled System is an adherence to design tokens. A design token is a value that's used to construct components. It can be a color (primary, secondary, light), a size (small, medium, large), or an array of values for spacing (2px, 4px, 8px, etc.). Using design tokens makes building out a component library or design system easy and consistent because it reduces the number of variables you _could_ use (an infinite number) to a limited set that you _can_ use. This constraint leads to consistency in design.

Styled System, and other packages floating in this ecosystem, use a [theme spec](https://system-ui.com/theme/) for consistency across projects. It's just an object with values that can be used to build out components.

```js
theme = {
  colors: {
    text: '#f7f7f7',
    background: '#464452',
    primary: '#28B4AD',
    secondary: '#4926F6'
  },
  space: [0, 0.25, 0.5, 1, 2, 4, 8]
}
```

We can grab our hex values from the `theme.colors` object, or use the `theme.space` array to get a `rem` value for defining padding or margin.

With these values, it's easy enough to go out and build a simple component by importing the theme object. But we can also use [Styled Component's Theme Provider](https://styled-components.com/docs/advanced#theming) to give use access to these variables within our styled components

```js
import React from 'react';
import styled, { css, ThemeProvider } from 'styled-components';
import theme from './theme';

const StyledButton = styled.button`
  ${({ theme }) => css`
    background-color: ${theme.colors.primary};
    padding: ${theme.space[2]}rem ${theme.space[3]}rem;
  `}
`;

function Button() {
  return (
    <ThemeProvider theme={theme}>
      <StyledButton>Styled</StyledButton>
    </ThemeProvider>
  )
}
```

In a real world use case, you'd hoist the `ThemeProvider` up to whatever the app's entry point is, allowing all styled components access to the theme variables. This eliminates the need to import the theme object into every component and allows for on the fly theme switching based on what you pass to the `ThemeProvider`.

### building a variant

Buttons ask us to think in variants. The difference between a submit and a cancel button on a form is largely about design rather than functionality. What I ultimately want is to be able to abstract that visual difference away by just passing a prop to change the color.

```js
<Button>Submit</Button>
<Button type='outline' color='secondary'>Cancel</Button>
```

Styled System has a built in [variant function](https://styled-system.com/variants/) that makes this abstraction really easy. Here's an example:

```js
import React from 'react';
import PropTypes from 'prop-types';
import styled from 'styled-components';
import { variant } from 'styled-system';
import { alpha, darken } from '@theme-ui/color';

const StyledButton = styled.button`
  ${({ theme, color }) =>
    variant({
      prop: 'type',
      variants: {
        default {
          color: 'background',
          bg: color,
          '&:hover': {
            bg: darken(color, theme.opacity.hover)
          }
        },
        outline: {
          color,
          border: `${theme.borders[1]} ${theme.colors[color]}`,
          bg: 'transparent',
          '&:hover': {
            bg: alpha(color, 0.1)
          }
        }
      }
    })
  }
`;

function Button({ children, color, type, ...props }) {
  return (
    <StyledButton
      color={color}
      type={type}
      {...props}
    >
      {children}
    <StyledButton>
  );
}

Button.propTypes = {
  /**
   * content of button
   */
  children: PropTypes.string,
  /**
   * takes one of 'primary', 'secondary', 'accent', 'muted'. corresponds
   * to theme colors
   */
  color: PropTypes.oneOf(['primary', 'secondary', 'accent', 'muted']),
  /**
   * takes one of 'default', 'outline'
   */
  type: PropTypes.oneOf(['default', 'outline'])
}

Button.defaultProps = {
  children: null,
  color: 'primary',
  type: 'default'
};

export default Button;

```

At the top of the styled component, we're deconstructing the `props` object to get access to the `theme` that is passed down from `ThemeProvider` and the button's props, specifically `color`. We then use the `variant` function by providing a prop string of 'type', so they styling will depend on the `type` we pass to the button. These are two basic examples, and your milage may vary, but `type` will determine the text color, the background color, and how to handle the hover state. In both cases, we use the button's color prop to determine which color variable to use for the different css properties.

Because our color variables line up with the variables in our theme object, the `variant` function takes care of assigning the variables for us. With the outline variant, we can even use `color` as a shorthand for explicitly defining `color: color`. This eliminates additional theme destructuring, taking the color prop and finding the corresponding value in the theme object, which we have to do for the outline's border.

### overriding a variant

At some point, you're going to want to override these variants -- the design might call for it or you need something like a one-off CTA button. Without a token in the theme object that matches what you need, you'll need a little more granular control over how to style the thing. In this example, we can pass props into the styled button and override default values by using a styled component. The above button could be overridden like this:

```js
const RedButton = styled.Button`
  color: red;
`;

function Page() {
  return (
    <RedButton>I'm red now</RedButton>
  );
}
```

Rather than getting a button with the default `primary` color, we'll get a red button. This is a basic example, but you could use the same principle to do more complicated overrides.

### further thinking

In general, I like this pattern/system because it's, on the one hand, rigid and tied to the design tokens and, on the other, extendable beyond those values if you're in a pinch. Continuing to work some of this out for an in-house design system, my next thoughts would be about extending the above -- what other props would I want the component to take? What other states would be useful here? Additionally, I want to think about what other helper or getting functions might make defining css properties that aren't explicitly in the theme object -- what's the best way to programmatically generate borders or box shadows? The color functions I'm using could be extended to do more, but there are surely other ways to make syntax a little legible and friendlier.

An additional problem to consider is what overriding values this way gets you beyond an easy one-off: this won't generate a new hover state -- I'd have to do that myself. What becomes important, I think, is thinking about the theming system a bit more holistically or systemically in the way I'm asking in the questions above.

### further reading

- [styled system props](https://github.com/styled-system/styled-system/blob/master/docs/table.md#core)
- [chakra ui](https://chakra-ui.com/style-props)
- [primer](https://primer.style/components/system-props)
- [sprout social](https://seeds.sproutsocial.com/components/system-props)
- [design tokens](https://www.erikverweij.dev/blog/manage-design-tokens-with-typescript-and-styled-components/)


tangle frontend


this post documents setting up the frontend portion of tangle.

This section covers the technical foundations including

- bootstrapping the lerna repo
- adding eslint and prettier
- setting up the frontend

### bootstrap lerna repo

``` bash
yarn init
yarn add lerna --dev
yarn lerna init
```

Add to package.json:

``` js
...
  'name': 'root',
  'private': true,
  'workspaces': [
    'packages/*'
  ]
...
```

Update lerna.json:

``` js
  'packages': ['packages/*'],
  'version': 'independent',
  'npmClient': 'yarn',
  'useWorkspaces': true
```

### gitignore

### eslint/prettier

Copy/paste eslint and prettier

``` bash
  yarn add babel-eslint eslint eslint-config-airbnb
  eslint-config-prettier eslint-plugin-import
  eslint-plugin-jsx-a11y eslint-plugin-prettier
  eslint-plugin-react prettier -W -D
```

`-W` for root flag

`-D` for dev dependencies

Add to package.json

``` js
    'lint': 'eslint --fix . && echo 'Lint complete.'',
```

Commit `[init]`.

## frontend / next.js

``` bash
  mkdir packages/web
  npx create-next-app packages/web
```

Select `Default starter app`

Update name of web app to `@tangle/web`

Add command to root package.json

```'web': 'lerna run --scope @tangle/web dev --stream'```

commit `[web] init`

We want to share react and next across the codebase. Add these as `devDependencies` to the root and add them as `peerDependencies` in whatever packages need them.

## component library

``` bash
  mkdir packages/components
  cd packages/components && yarn init -y
```

Name package `@tangle/components`.

Add peer dependencies

```js
  yarn workspace @tangle/components add -P react react-dom next
```

Add dependencies

```js
  yarn workspace @tangle/components add @emotion/styled @theme-ui/color styled-system theme-ui prop-types
```

Make a component

`packages/components/src/components/Button/Button.js`

``` js
  import React from 'react';
  import PropTypes from 'prop-types';
  import styled from '@emotion/styled';

  const StyledButton = styled.button`
    color: red;
    background-color: blue;
  `;

  function Button({ children }) {
    return <StyledButton>{children}</StyledButton>;
  }

  Button.propTypes = {
    /**
    * content of button
    */
    children: PropTypes.string
  };

  Button.defaultProps = {
    children: null
  };

  export default Button;

```

Add storybook

``` bash
  yarn add -W -D @storybook/react @storybook/addon-actions
  @storybook/addon-docs babel-loader @babel/core
```

Add `.storybook` directory w/ `config.js` and `main.js`

`config.js`

``` js
  import { configure, addDecorator } from '@storybook/react';

  addDecorator(storyFn => (storyFn()))

  configure(require.context('../packages/components/src', true, /\.stories\.js$/), module);
```

`main.js`

``` js
  module.exports = {
    stories: ['../packages/**/*.stories.js'],
    addons: ['@storybook/addon-docs']
  };
```

Add a story for the button

`Button.stories.js`

``` js
  import React from 'react';
  import { action } from '@storybook/addon-actions';
  import { storiesOf } from '@storybook/react';
  import Button from './Button';

  storiesOf('Button', module).add('default', () => (
    <Button onClick={action('clicked')}>test</Button>
  ));
```

update root `package.json`

``` js
  'stories': 'start-storybook'
```

Run storybook.

## clean up and code share

[babel-plugin-module-resolver](https://www.npmjs.com/package/babel-plugin-module-resolver) helps us keep things looking clean.

``` bash
  yarn add -D -W babel-plugin-module-resolver eslint-plugin-import
  eslint-import-resolver-babel-module eslint-import-resolver-alias
```

add a `.babelrc` file

``` js
  {
    'plugins': [
      ['module-resolver', {
        'root': ['./'],
        'alias': {
          '@components': './packages/components/src',
          '@web': './packages/web'
        }
      }]
    ]
  }
```

add to `.eslintrc.js`

``` js
  settings: {
    'import/resolver': {
      'babel-module': {},
      alias: {
        map: [['@components', './packages/components/src']],
        extensions: ['.ts', '.js', '.jsx', '.json']
      }
    }
  }
```

add an `index.js` file to `components/src` and export the button component from there. Update the import in the `Button.stories.js` file to reflect the update

``` js
  import { Button } from '@components';
```

Run storybook to test.

Time to add the button to Next.js

Add a `babel.config.js` to the next app

``` js
  module.exports = {
    babelrcRoots: ['../packages/*'],
    presets: ['next/babel'],
    plugins: [
      [
        'module-resolver',
        {
          root: ['./'],
          alias: {
            '@components': '../components/src'
          }
        }
      ]
    ]
  };
```

We need to transpile the components as they come in:

`yarn workspaces @tangle/web next-transpile-modules`

Transpile components in the `next.config.js`

``` js
  const withTM = require('next-transpile-modules')([
    '../components/src'
  ]);

  module.exports = withTM();
```

Call the `Button` in your index to test. Run your next app.


tangle


This is the first in a series of posts documenting tangle, a fullstack monorepo that utilizes next.js and styled-system on the front end, with a graphql backend. The purpose of these posts is to, on the one hand, document the technical foundations of the repo and, on the other, act as an opening for thinking about the project more generally. Towards this end, I've split this post into two sections -- technical and theoretical.

### technical

tangle is an attempt to build a full stack monorepo boilerplate for quickly spinning up web apps. It's also an attempt to learn a bit more about full stack development -- I have a sense of how I want the codebase to work, but the solutions and integrations are not completely obvious from the outset. I do know that I want a few things:

- lerna monorepo to share code between projects
- shared tooling (eslint, prettier, jest, storybook)
- component library built on top of styled components and styled system
- web/front end built on next.js
- server/back end built on an apollo or express graphql server
- alternatively, serverless functions
- easy deployed to heroku/netlify/now

The directory structure is as follows:

``` bash
├── babel.config.js
├── lerna.json
├── package.json
├── packages
│   ├── api
│   ├── components
│   └── web
└── yarn.lock
```

Some of the motivating factors:

1. I find it easier to work in a codebase that's been bootstrap than bootstrapping the same project over and over. I want the ability to dive immediately into the code rather than fret over setup.
1. Because I'm pretty much only writing JS, shared tooling makes the most sense -- again: set and forget.
1. Splitting the frontend into a component library and web project allows the component library to grow organically (more in theoretical section) and isolates the dependencies the web project needs to deal with.
1. Additionally, splitting things up with way will eventually allow me to deploy just an api, or just a frontend app, or pull in just the component library.
1. Serverless functions are what I'd like to build into this, but there's some weirdness with where those functions should reside.
1. Someone else should be able to pick this up and deploy it eventually, so ideally it's easily deployed everywhere.

For MVP, I want to deploy the repo to Netlify, render a component from the component library, and display information by making a call to the server. This initial build (v 0.1.0) will also document the steps made to structure the codebase (i.e. an edited version of what I'll be doing here).

### theoretical

'Tangle' is a noun and a verb. To tangle is a process of becoming entangled; a tangle is the result. But tangles always seem to be tangling and untangling, retaining their tangliness in the process, until they become untangled, which is a wholesale different entity or status. In this way, a tangle is more than the sum of its parts or, at least, differs from the sum of its parts. We should also think about this in terms of entanglement, or the process through which not mutually exclusive objects or entities become somehow different in their interactions among one another (see Barad or Haraway on 'intra-activity'). A blunt and mundane example is the frontend's intra-action with a server or function or service -- they become different: an app, the exposure of data.

tangle, the project, takes these ideas as foundational in an anti-foundational way. I cannot know in advance what tangle will need or become, instead, I'm interested in allowing tangle to grow itself out as needed. Having a minimal, bootstrapped project allows for easy and speedy development that doesn't assume everything a developer would need. As something coalesces into a feature, it can become part of that boilerplate, or a more permanent part of the tangling. Yet, this is also an anti-foundational stance that refuses mastery -- of a set of practices or tool(ing)s -- in favor of humility and learning. tangle attempts to refuse assumption in an effort never to fully congeal. Instead, it'll just tangle on.

What I'm trying to outline here is a way of thinking about development and boilerplates less as full stop solutions to discrete problems than as process driven projects. In time, I want to think about what it would mean to take this stance further beyond the immediate realm of development (as coding or making a thing) into development as a set of relational practices among myriad people, technologies, and social forces.


adding dark mode to your gatsby site with emotion js

In finalizing the current version of my [portfolio](/portfolio), I wanted to offer a dark mode toggle as a proof of concept, practice working with [emotion.js](https://emotion.sh/docs/introduction), and just for usability because my blog and portfolio are so light. To implement this, I utilize a toggle component to control state, `emotion.js`'s `<Global />` styles to inject some styles at `:root`, and browser supported variables to change everything from font color to backgrounds to link colors.

### Set Up

Big picture things you'll need to do:

1. Add state to your parent component/container
2. Pass state down to a `ThemeToggle` and `ThemeWrapper`
3. Use `emotion.js` to pass themes into `:root` in the `ThemeWrapper` component

I'm assuming you have [Gatsby.js](https://www.gatsbyjs.org/docs/quick-start) and have [emotion installed](https://www.gatsbyjs.org/docs/emotion/.). I'm also using browser variables to style text and background colors. You can read an excellent write up on theming with variables at [CSS Tricks](https://css-tricks.com/theming-with-variables-globals-and-locals/).

### Adding State

I built my portfolio as a standalone component, so I'm just adding state to the upper most component:

``` javascript
class Portfolio extends React.Component {
  constructor(props) {
    super(props);
    this.state = {
      dark: false
    };
    this.toggleTheme = this.toggleTheme.bind(this);
  }
  componentWillUnmount() {
    this.setState({ dark: false });
  }
  toggleTheme() {
    this.setState({ dark: !this.state.dark });
  }

  render() {
    return (
      <Wrapper>
        <ThemeWrapper
          dark={this.state.dark} />
        <Header>
          {...}
          <ThemeToggle
          toggleTheme={this.toggleTheme}
          dark={this.state.dark} />
        </Header>
        {...}
      </Wrapper>
    );
  }
```

Here, I'm initializing `this.state.dark` to false and binding a toggle function to state. I'm using `componentWillUnmount()` in case someone moves away from the portfolio to the rest of the site (which isn't set up for dark mode yet), and then using `toggleTheme()` to set dark to `true` or `false`. I'm passing state into `ThemeWrapper` as a prop so it knows whether or not to return our darkUI. Because `ThemeWrapper` is going to change `:root` level variables, we don't need to wrap the rest of the page in it, but keeping it near the top of the component makes it syntactically clear what it's for. I'm also passing our `toggleTheme()` function and state into the `ThemeToggle` component so we can visually render what state is set to.

### Theme Wrapper and Themes

Before we build our `ThemeWrapper`, we need to have a javascript file with our themes. I wrote a module that exports two themes--lightUI and darkUI. lightUI repeats the variables I have in my `global.css` and functions as a fallback. darkUI repeats these variables with new colors:

``` javascript
  const lightUI = {
    textColor: `#333`,
    {...}
    backgroundColor: `#fcfcfc`,
  }

  const darkUI = {
    textColor: `#fcfcfc`,
    {...}
    backgroundColor: `#333`,
  }

  module.exports = {
    lightUI: lightUI,
    darkUI: darkUI
  }
```

`ThemeWrapper` takes these themes and uses `emotion.js`'s global styles to inject our theme at the `:root` level:

``` javascript
import React from 'react';
import { Global, css } from '@emotion/core'

import { darkUI, lightUI } from './styles/themes'

const ThemeWrapper = props => {
  const { dark } = props;

  return (
    <Global
      styles={css`
        :root {
          --textColor: ${dark ? darkUI.textColor : lightUI.textColor};
          --backgroundColor: ${dark ? darkUI.backgroundColor : lightUI.backgroundColor};
        }
      `}
    />
  );
};

export default ThemeWrapper;
```

Here, we're importing `Global` and `css` from `@emotion/core` as well as our themes. We've passed state into our `ThemeWrapper` as a prop that's either true or false. We return a `Global` component with a style that initializes, at `root:`, our variables. We then use a ternary operator to return the associated variable depending on whether dark is set to true or false. You can read more about `Global` [here](https://emotion.sh/docs/globals).

### Theme Toggle

So far we've set up state, written some themes, and a component that will render our theme based on state. The last thing to do is provide a toggle that users can actually press to change the theme.

``` javascript
import React from 'react';

const ThemeToggle = props => {

  const { toggleTheme, dark } = props;

  return (
    <button onClick={toggleTheme}>
      {dark
        ? `light`
        : `dark`}
    </button>
  );
}

export default ThemeToggle;
```

Remember that we've passed our `toggleTheme()` function and state into this component. So we're returning a button that, when clicked, toggles state and, based on the state, toggles the words `light` and `dark`. This is a very minimal implementation--you could add a sun and moon icon to signify the same thing.

### Wrapping Up and Further Thinking

You can check out my implementation [here](https://www.inadequatefutures.com/portfolio/) and the source code on [GitHub](https://github.com/inadeqtfuturs/if/tree/master/src/components/portfolio). There's more thinking to be done here about translating variables from dark to light UI. For example, the slider navigation could be tweaked a bit more for better contrast in dark mode, but this would require renaming or adding variables. As I note above, we could also simplify state by using hooks, but that might be for another weekend.

If you have different, better, or slicker implementation, I'd love to hear about it on [twitter](https://twitter.com/inadeqt_futurs) or via email (alexj [dot] christie [at] gmail [dot] com).


programmatic menus in Gatsby

Programmatically generating menus is a difficult concept at first because it seems simple enough just to hard code your menu into a component. However, making a reusable and data agnostic menu component is really easy and can travel with you from project to project. Here, I want to outline two approaches to generating menus from your data. The first involves defining menu items in markdown frontmatter, which can be useful when designing sites for folks less familiar with javascript or coding more generally. The second is an iteration on the current Gatsby documentation that skips using GraphQL fragments in favor of a meta config file.

### Markdown Frontmatter

I'm currently working on a Gatsby site template designed specifically for folks with minimal, if any, javascript knowledge. With these users in mind, I'm trying to define most things through really basic global variables in `gatsby-config.js` and frontmatter. I think performing tasks by querying markdown frontmatter can simplify user experience immensely, especially if users are given clear guidelines and a fairly robust set of options.

I wanted users to be able to define their menu from frontmatter for a few reasons:

- It's fairly semantic. Users don't need to write out objects or arrays to get some nice menus.
- Users can distinguish between pages, posts, and pages that should be menu items from the markdown file itself.
- Users don't have to think about slugs because `gatsby-node.js` programmatically generates them. So there's never a time where a slug changes and your menu doesn't reflect that change.  

That being said, this method surely has some downsides:

- Menu is no longer centralized -- you have to go to different files to edit and reorder the menu.
- It's arguable whether this is a major upgrade from just defining a menu in `gatsby-node.js`, especially if users are already defining *other* site data there.
- Implementing sub menus this way is going to be difficult.

With these things in mind, let's take a look at some example frontmatter:

``` markdown
---
title: 'hi.'
author: 'ed.'
date: 2018-12-29T10:52:33-6:00
type: 'page'
menuItem: 1
menuTitle: 'home'
draft: true
---
```

The important things here are just that I've defined a menuItem to position the item in the menu, and I have a label or menuTitle for the item in case I want the title and what shows up in the menu to be different.

Here's our menu component:

```javascript
import React from 'react';
import { Link } from 'gatsby';
import { graphql, StaticQuery } from 'gatsby';

export default (props) => (
  <StaticQuery
    query={graphql`
      query MenuQuery {
        allMarkdownRemark(
          filter: { frontmatter: { type: { eq: "page" } } },
          sort: {fields: [frontmatter___menuItem], order: ASC},
        ) {
          edges {
            node {
              frontmatter {
                menuTitle
              }
              fields {
                slug
              }
            }
          }
        }
      }
    `}
    render={data => {
      const items = data.allMarkdownRemark.edges
      return (
        <nav>
          {items.map(({node}) => {
            const { frontmatter: { menuTitle }, fields:{ slug }, } = node;

            return (
              <Link
                to={slug}
                activeClassName={'active'}
                key={menuTitle}>
                {menuTitle}
              </Link>
            )
          })}
        </nav>
      );
    }}
  />
)
```

StaticQuery is doing the majority of the heavy lifting here. We're filtering all of our markdown files for anything that's listed as a 'page,' and then ordering them by `frontmatter.menuItem`. Any page that doesn't define a menuItem in its frontmatter is excluded from the search. This query also exposes the `menuTitle` and `slug`, so all that's left to do is map our object into Link. What we're left with is a set of easily styled list items nester in `nav` tag.

If you're looking for a simple way to generate single level menus, this is a really great way to go. But what if you're looking for something a little more robust, specifically with nested sub-menus?

### Meta Config File

The approach I ended up taking was siloing metadata about the site into a siteConfig file. Here, I define some site wide settings, and map out my menu. While this can be done in `gatsby-config.js` (and Gatsby docs even offer this as a solution for [mapping programmatic menus](https://www.gatsbyjs.org/docs/centralizing-your-sites-navigation/)), I decided to forego writing another GraphQL fragment of just use an object with some arrays. So the main difference and benefit here is just slimmer syntax at the cost of passing the object through the top level layout component.

There are two parts of this setup: the `siteConfig.js` file, and the menu components. I keep my siteConfig in `content/meta`, though it could be stored anywhere. Here, I define my menu with a series of objects listing the item label, and the page we're navigating to. Additionally, I wanted to be able to define sub-menu items, so I giving 'teaching' a subItems array with objects that are constructed the same way as the top-level objects:

``` javascript
const menu = [
  { label: 'home', to: '/' },
  { label: 'about', to: '/about' },
  { label: 'teaching', to: '/teaching', subItems: [
    { label: 'teaching philosophy', to: '/teaching' },
    { label: 'course descriptions', to: '/classes' },
  ]},
  { label: 'cv', to: '/cv' },
  { label: 'code', to: '/code' },
]

...

module.exports = {
  menu: menu,
  ...
}
```

The final bit of code here is just exporting a bunch of arrays from `siteConfig.js`, but we're just looking at menu for now.

The second part is my `menu.js` and `menuItem.js` component. `menu.js` simply maps the array into the `menuItem.js` component. This is where we use the arrays to define and programmatically generate out menu:

``` javascript
import React from 'react';
import { Link } from 'gatsby';

import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'
import { library } from '@fortawesome/fontawesome-svg-core'
import { fas } from '@fortawesome/free-solid-svg-icons'

library.add(fas)

const MenuItem = ({ item }) => {
  const { label, to, subItems } = item;

  return (
      subItems
        ? (
          <li key={label}>
            <Link to={to}>
              {label} <FontAwesomeIcon icon={['fas', 'angle-down']} size='sm' />
            </Link>
            <ul>
              {subItems.map((subItem) => {
                const { label, to } = subItem;

                return (
                  <li key={label}><Link to={to}>{label}</Link></li>
                )
              })}
            </ul>
          </li> )
        : ( <li key={label}><Link to={to}>{label}</Link></li> )
  )
};

export default MenuItem;
```

So, what's happening here?

- We're deconstructing the item so we can use 'label', 'to', and check for subItems.
- We then use a [ternary operator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Conditional_Operator) to differentiate arrays that do and do not have 'subItems'.
- If one does, we map the 'label' and 'to' properties to a list item and Link tag, respectively. We also add an 'angle-down' icon to signify that the link has a dropdown menu.
- Then, we map the subItems in similar fashion, iterating over the subItem object.
- The second half of the ternary just gives us a standard Link nested in a list item.

I like this approach because it gives us the separation of concerns that Gatsby's documentation recommends without having to write a static GraphQL query. Additionally, the example above should give you an idea of how to start working with sub-menus, which is absent in the current Gatsby documentation. Check out [my Github](https://github.com/inadeqtfuturs/if/blob/master/src/components/styles/menu.js) for styling.

### Wrap Up

I hope these two models of dealing with menus provide useful examples for folks working on their own Gatsby projects. In future iterations of these menu designs, I'd like to work on rendering a collapsible (hamburger) menu for mobile.


blog relaunch


My personal website, *inadequate futures*, has been rewritten a total of three times. I was inspired to pick html and css back up after learning about static site generators, specifically [Jekyll](https://jekyllrb.com/), after reading about [Alex Gil's 'Ed' theme](https://elotroalex.github.io/ed/about/) for minimal editions (I am in the process of porting this over to Gatsby. More on that at the end of this post). The first version of the site was launched about a year ago on GitHub pages with the help of [Hugo](https://gohugo.io/), which quickly shifted my focus from building *my* website back towards the world of frontend development. Not long after launching '[if-ver01](https://inadeqtfuturs.github.io/),' I started reading about the JAMStack and React, which offered what seemed like a robust alternative for turning markdown files into blog posts.

For the second version of the site, I moved to [Gatsby](https://www.gatsbyjs.org/), which I chose after looking around for other blogging frameworks built on Javascript. I liked Gatsby because it remained atomistic and modular (things that initially attracted me to Hugo), but also because it was built on React, providing the opportunity to learn one of the major javascript frameworks. Having worked with Gatsby for the past year, I think it offers some great features for anyone developing for the modern web:

### JAMStack and Modern JS Technology

The [JAMStack](https://jamstack.org/) undergirds much contemporary frontend web development. By leveraging javascript, APIs, and markdown, static site generators are able to deploy lightweight and fast websites without much data overhead. Gatsby, in my experience, offers the best modern JAMStack experience out of the box with prefetched links, page caching, and a pre-installed service worker. By prefetching content (i.e. rendering pages before you've even clicked on the links), Gatsby offers a fast and smooth navigation experience. Additionally, between the client side rendering and pre-installed service worker, users nearly always have access to a minimum-viable version of the website.

This is all to say that Gatsby helps developers build simple progressive web apps out-of-the-box. A [progressive web app](https://developers.google.com/web/progressive-web-apps/) functions on your smart phone or tablet like any other app--you can add it to your homescreen, it's fully immersive, and you can use it on- or offline. For my blog, and for future projects, it was important for me to develop for mobile and the modern web. Gatsby solved many of the problems I was having trying to implement many of these technologies with other static site generators.

### Easy to Set Up // Easy to (Re)Use

Gatsby has some of the best documentation for learning a completely new stack, teaching developers a variety of technologies along the way. I began working with Gatsby with little to no formal javascript experience. However, getting up and running was anything but daunting. Not only does the [tutorial](https://www.gatsbyjs.org/tutorial/) walk you through everything you need to start building a simple blog, it also introduces users to Gatsby's layout logic, GraphQL, and Google's Lighthouse audit.

Installation is as easy as running a handful of commands in terminal, but what I really like about Gatsby is the reusability of components and project structure. Because the frontend is largely data agnostic--GraphQL will give you whatever data you ask it for and then you simply pass it into [jsx](https://reactjs.org/docs/introducing-jsx.html)--users are able to reuse, refactor, and upgrade components to fit whatever particular use case they're working on. Updating *inadequate futures* was as easy as starting a new Gatsby project, dropping my content into the project root, and utilizing some existing components to get up and running.

### GraphQL and the Mesh

Gatsby utilizes [GraphQL](https://graphql.org/) to fetch data. Prior to working with Gatsby, I had never used a query language before. Returning to work on a few WordPress projects over the past six months, I can't quite imagine frontend development *without* GraphQL. Whereas WordPress offers a largely 'what you see is what you get' editing experience, GraphQL and Gatsby's frontend are  uncoupled. This means that you can query whatever information you might need from a markdown file, and inject it wherever you want it on the front end.

As a really simple example, here's a simplified snippet for querying individual blog posts:

```js
markdownRemark(fields: { slug: { eq: $slug } }) {
  html
  excerpt(format: PLAIN)
  frontmatter {
    title
    author
    date(formatString: "MMMM DD, YYYY")
  }
}
```

Here, I'm just asking GraphQL to give me the body of the markdown file, a plaintext formated version of the body to pass into an SEO component, and I get some basic information from the frontmatter, including a formatted date string. I then pass this into various post and excerpt components, allowing me to display the data using html and css:

```js
<h2 dangerouslySetInnerHTML={{ __html: title}} />
<p><i>{date} by {author}</i></p>
<div>
  { ... }
  <p dangerouslySetInnerHTML={{ __html: html }} />
</div>
```

While I'm only querying my own markdown files, GraphQL *can* be used with other content management systems, including WordPress, Drupal, and others. This means that you can utilize Gatsby with existing projects even if they're already tied to a CMS. In the future, I'd be interested experimenting with this approach, allowing for editors and developers to work in tandem without committing wholesale to something like WordPress.

### What's Next

I rewrote *inadequate futures* to integrate some of the lessons I learned about javascript, react, and component composition over the past year or so. I'm currently at work putting this knowledge into practice by porting the [Jekyll theme Ed](https://elotroalex.github.io/ed/) over to Gatsby with the sense that editors would be interested in integrating some of the above advantages of the modern JAMStack into their minimal editions and other humanities projects. I see this as an effort to contribute to both digital humanistic inquiry and add to the growing number of Gatsby starters.

I made this section of the website to start documenting some of my experiences with Gatsby, React, and web development. If you'd like to talk about static site generators, Gatsby, or [my research](https://www.inadequatefutures.com), don't hesitate to reach out on [twitter](https://twitter.com/inadeqt_futurs) or via email (alexj [dot] christie [at] gmail [dot] com).