macOS setup

1. Install iTerm2. iTerm2 is a terminal emulator that is more user-friendly and feature-rich than the built-in Terminal app.

2. Install Homebrew. Homebrew is a macOS package manager that will let you easily install many useful command line tools.

3. Install the Xcode Command Line Tools:

   xcode-select --install

4. Install Jujutsu.

   brew install jj

Windows setup

1. Install Windows Subsystem for Linux 2 (WSL 2).

2. Install Jujutsu. Download the prebuilt binary and place it in /usr/local/bin.

   # https://github.com/jj-vcs/jj/releases/tag/v0.31.0
   mkdir -p /tmp/jj-install
   wget -O /tmp/jj-install/jj-linux.tar.gz https://github.com/jj-vcs/jj/releases/download/v0.31.0/jj-v0.31.0-x86_64-unknown-linux-musl.tar.gz
   tar -xvf /tmp/jj-install/jj-linux.tar.gz -C /tmp/jj-install
   sudo mv /tmp/jj-install/jj /usr/local/bin

General setup

1. Install VS Code. After you've installed VS Code, add VS Code to your PATH environment variable so you can launch VS Code from the command line.

2. Sign up for a Github account if you don't have one already.

3. Create an SSH private/public key pair. This will create two files:

   • a public key ~/.ssh/id_ed25519.pub, and
   • a private key ~/.ssh/id_ed25519.
     

   You don't need to encrypt your private key with a passphrase when prompted; just make sure you never share its contents. Your public key is the only value that you share to services like Github.

   ssh-keygen -t ed25519 -C "$USER@$HOST"

4. Add your public SSH key to your Github account: https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account. This will let you push (upload) and pull (download) code from Github without your username and password.

5. Install the Fast Node Manager (fnm) by running the following:

   curl -fsSL https://fnm.vercel.app/install | bash
   fnm install 20.18.3
   fnm default 20.18.3

6. Configure Jujutsu.

   jj config set --user user.name "<Your name>"
   jj config set --user user.email "<Email you use on Github>"

Jujutsu basics

Jujutsu (jj) is a new(ish) version control system (VCS) that is much more user-friendly and intuitive than Git. Importantly, Jujutsu uses Git as a storage layer which means we can still use Github as our remote repository.

Go through this tutorial to get a basic understanding of how to use Jujutsu.

Setting up your website

1. Fork the website template (https://github.com/mattfeng/website-template). Rename the repository to <GITHUB USERNAME>.github.io (this is needed for Github Pages, a free website hosting service, to work).

2. Clone your fork of the repository. This downloads a complete copy of the repository to your computer, where you can make and save edits, and eventually push (upload) those edits to Github, where they'll be compiled and published.

   jj git clone git@github.com:<YOUR_GITHUB_USERNAME>/<YOUR_GITHUB_USERNAME>.github.io.git

3. The first time you clone the repository, you will need to install the Node.js dependencies in order to run the live preview.

   cd <YOUR_GITHUB_USERNAME>.github.io
   code . # this launches a VS Code editor window
   npm install

4. Start the live preview server of the blog:

   npm run dev

5. Make edits to the blog posts under app/(blog)/posts. The name of the .mdx file (e.g. onboarding.mdx) will because the blog post's "slug" (the URL link). Folders are ignored and are only present for organization.

   Every post should contain a frontmatter which provides metadata about the post:

   ---
   title: 'The title of your post'
   publishedAt: '2025-07-14' # Date as a string in YYYY-MM-DD format
   summary: 'A summary of your post.'
   published: true # false if the post is still in draft mode; true if the post is public
   ---

   The rest of the post is written in MDX, an extension of Markdown. For now, you can simply use Markdown to write your posts.

   Be sure to check how your post looks, typically by viewing it at http://localhost:3000/<SLUG> (e.g. http://localhost:3000/onboarding). Your server may be running on a different port than 3000; check your terminal output to see which port you're using.

   You can include images in your post by including them in the folder with your post.

   For example:

   To make sure that the blog post loads quickly, compress your images so that they are under 1 MB in size.

6. When you're satisfied with your edits, commit and push your changes.

   jj commit -m "Description of the edits you made"
   jj bookmark move -f main -t @-
   jj git push

7. At some point, you may need to learn how to merge changes.