lifetracker/apps/docs/docs/how-i-built-this/01-first-steps.md

sidebar_position	description
1	Turn an empty folder into something magical.

First Steps

:::tip

If you fuck around with documentation, you don't have to do any hard stuff.

:::

Setting up the repo

Create a project

Start by running init-nix raw lifetracker. This uses my init-nix script to initialize a folder in ~/Documents/Code/lifetracker containing a .envrc file and a bare-bones flake.nix.

For posterity (aka, to test Docusaurus code highlighting, since this is very much IN the repo), here's the flake.nix with key lines highlighted:

{
  description = "Lifetracker Monorepo";

  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
  inputs.flake-utils.url = "github:numtide/flake-utils";

  outputs = { self, nixpkgs, flake-utils }:
    flake-utils.lib.eachDefaultSystem (system:
      let
        inherit (pkgs.lib) optional optionals;
        pkgs = import nixpkgs { inherit system; };


      in
      with pkgs;
      {
        devShell = pkgs.mkShell {
          buildInputs = [
            bashInteractive
            glibcLocales
            git
            emacs-nox
            // highlight-start
            nodejs
            pnpm
            // highlight-end
          ] ++ optional stdenv.isLinux inotify-tools
          ++ optional stdenv.isDarwin terminal-notifier
          ++ optionals stdenv.isDarwin (with darwin.apple_sdk.frameworks; [
            CoreFoundation
            CoreServices
          ]);
        };
      });
}

Monorepo with pnpm and turbo

In the new directory, run npx create turbo@latest. If you're in the future trying this, yes, you'll realize it wants to make a subdirectory and complains about existing files, so you'll have to end up deleting everything, using the npx script, and then re-initializing the nix flake directory. Annoying, but manageable.

At this point, you have a pretty decent starting point. Looking at the files, you'll see references to @lifetracker that will need to be changed. Also, nothing will work and you'll get annoying messages until you run pnpm install. You'd think the error messages would hint at this, but you'd be dead wrong.

:::warning

I just made this point, but look, a warning box telling you to run pnpm install!

:::

Baby's First Steps

This is the part where I ripped out the Next.js guts from the docs folder and replaced it with Docusaurus. I gotta admit, it's an incredibly satisfying static site generator.

Am I now wasting my time writing documentation and pretending it's productive? Sure. But, you know, good documentation is a gift, they say.

Adding Docusaurus

So, how do you actually add Docusaurus to a fresh newly-generated Turbo app? Of course, this isn't the most straightforward either. I renamed docs to docs.old, renamed its package.json to package.json.old (so that the pnpm-workspace.yaml doesn't try to load shit from the old docs folder), then ran

npx create-docusaurus@latest docs classic

from the apps directory. This created a new apps/docs subdirectory with a Docusaurus, uh... install, I guess.

After another pnpm install, and then editing the name, version, dependencies, and scripts (I just renamed "start" to "dev" so that pnpm run dev starts Docusaurus) --- we're good to go!