Skip to content

1. Principles and Practices: Setting Up Your Fab Academy Documentation

Welcome to Fab Academy! This guide will walk you through setting up everything you need to document your journey. By the end, you’ll have a professional website hosted online where you can share your weekly assignments, project updates, and final project documentation.

What You’ll Learn

Learning Objectives

  • Installing and configuring Git (version control)
  • Creating SSH keys to securely connect to your repository
  • Cloning your personal Fab Academy repository to your Mac
  • Installing and using Zed, a modern text editor
  • Setting up MkDocs to build and preview your website locally
  • Making changes and publishing them to the web

Time Commitment

This week requires approximately 6-8 hours to complete all setup tasks and documentation.

Prerequisites

  • Mac computer (macOS 10.15 or later)
  • Internet connection
  • Basic computer literacy

Introduction: Why This Matters

Documentation is a core part of Fab Academy. Your website serves as: - A portfolio of everything you create throughout the program - Proof of your work for assessment and grading - A learning tool for future students who follow in your footsteps - A collaboration space where instructors and peers can review your progress

Think of your documentation as a public journal that captures your creative and technical journey. The skills you learn here—using the terminal, Git, Markdown, and static site generators—are fundamental tools used by developers, designers, and makers worldwide.

Part 1: Setting Up Git

Git is a “version control system” that tracks changes to your files over time. It allows you to: - Save snapshots of your work (called “commits”) - Go back to previous versions if something breaks - Collaborate with others without overwriting each other’s work - Maintain a complete history of your project’s evolution

Step 1.1: Check if Git is Already Installed

  1. Open the Terminal app (found in Applications → Utilities, or press Cmd+Space and type “Terminal”)
  2. Type the following command and press Return:
git --version
  1. If you see a version number (like git version 2.39.0), Git is already installed and you can skip to the next section.
  2. If you see “command not found”, you need to install Git.

Step 1.2: Install Git Using Xcode Command Line Tools

The easiest way to install Git on a Mac is through Xcode’s command line tools:

  1. Open Terminal
  2. Run this command:
xcode-select --install
  1. A popup window will appear asking you to “Install” the command line developer tools. Click Install.
  2. Wait for the download and installation to complete (this may take a few minutes).
  3. Verify the installation by running:
git --version

You should now see a version number.

Part 2: Creating an SSH Key

SSH (Secure Shell) keys are a way to securely communicate between your computer and online services like GitHub or GitLab. Instead of typing a password every time, you’ll use a cryptographic key pair.

Step 2.1: Check for Existing SSH Keys

Before creating a new key, let’s check if you already have one:

  1. Open Terminal
  2. Run:
cat ~/.ssh/id_rsa.pub
  1. If you see a long string of characters starting with ssh-rsa, you already have an SSH key. Copy it (we’ll need it later) and skip to Step 2.4.
  2. If you see “No such file or directory”, you need to generate a new key.

Step 2.2: Generate a New SSH Key

  1. In Terminal, run the following command (replace your.email@example.com with your actual email address):
ssh-keygen -t rsa -C "your.email@example.com"
  1. You’ll be asked where to save the key. Press Return to accept the default location (~/.ssh/id_rsa).
  2. You’ll be asked for a passphrase (optional but recommended for security). You can:
  3. Press Return for no passphrase, or

  4. Type a passphrase and press Return (you’ll need to remember it)

  5. Confirm your passphrase if you set one.

Step 2.3: View Your New SSH Key

  1. Run:
cat ~/.ssh/id_rsa.pub
  1. You should see a long string starting with ssh-rsa. Copy the entire string (select all text from ssh-rsa to the end of your email address).

Step 2.4: Add Your SSH Key to Your Account

If using GitHub: 1. Go to https://github.com and sign in 2. Click your profile picture → Settings 3. In the left sidebar, click SSH and GPG keys 4. Click New SSH key 5. Paste your key into the “Key” field 6. Give it a descriptive title (e.g., “My MacBook Pro”) 7. Click Add SSH key

If using GitLab: 1. Go to https://gitlab.fabcloud.org and sign in 2. Click your profile picture → Preferences 3. In the left sidebar, click SSH Keys 4. Paste your key into the “Key” field 5. Give it a descriptive title 6. Click Add key

Part 3: Cloning Your Repository

Your “repository” (or “repo”) is your personal online storage space for all your Fab Academy files. “Cloning” creates a local copy on your Mac that you can edit.

Step 3.1: Find Your Repository URL

  1. Go to your Fab Academy GitLab page (ask your instructor for the link)
  2. Click on your personal repository
  3. Click the blue Clone button
  4. Select Clone with SSH
  5. Copy the URL (it looks like git@gitlab.com:your.username/fabacademy.git)

Step 3.2: Create a Folder for Your Fab Academy Files

  1. Open Terminal
  2. Create a folder on your Desktop:
mkdir ~/Documents/leo-cabibihan
  1. Navigate into that folder:
cd ~/Documents/leo-cabibihan

Step 3.3: Clone Your Repository

  1. In Terminal, run the following command (replace the URL with your actual repository URL):
git clone git@gitlab.com:your.username/fabacademy.git
  1. If this is your first time connecting, you may see a warning about authenticity. Type yes and press Return to continue.

  2. If you set a passphrase for your SSH key, you’ll be prompted to enter it.

  3. Once complete, you should see a new folder with your repository name. Navigate into it:

cd leo-cabibihan

Part 4: Installing Zed Editor

Zed is a fast, modern text editor designed for collaboration. It has excellent support for Markdown and is perfect for writing your Fab Academy documentation.

Step 4.1: Download Zed

  1. Go to https://zed.dev
  2. Click Download for macOS
  3. A .dmg file will download to your Downloads folder

Step 4.2: Install Zed

  1. Open your Downloads folder
  2. Double-click the Zed.dmg file
  3. A window will open showing the Zed icon and your Applications folder
  4. Drag the Zed icon into the Applications folder
  5. Eject the Zed disk image
  6. Open Finder → Applications and double-click Zed to open it
  7. You may see a warning that Zed is from an unidentified developer. To proceed:
  8. Right-click (or Control-click) on Zed
  9. Select Open
  10. Click Open in the dialog box

Step 4.3: Configure Zed (Optional)

  1. Open Zed
  2. Go to Zed → Settings (or press Cmd+,)
  3. You can customize:
  4. Font size (default is usually good)
  5. Theme (try “Dark” or “Light”)
  6. Word wrap (enable for easier Markdown editing)
  7. Tab size (2 or 4 spaces are common)

Zed has a built-in AI Agent (inline assistant) that can help with code completion, explanations, debugging, and even generating Markdown documentation. We recommend using OpenRouter as the provider because it gives access to multiple top models through one API key, with automatic fallbacks and cost optimization.

Quick Setup:

  1. Get an OpenRouter API key:
  2. Go to https://openrouter.ai
  3. Sign up/login (free tier available)
  4. Go to Keys → Create Key

  5. Copy your API key (starts with sk-or-...)

  6. Configure in Zed:

  7. Open Zed → Zed → Settings (or Cmd+,)
  8. Search for “AI” or navigate to AI section
  9. Click + Add Provider
  10. Select OpenRouter
  11. Paste your API key
  12. Set default model (see comparison below)

  13. Enable features like Inline Assistant (Cmd+I) and Agent Mode

  14. Test it:

  15. Open a Markdown file (like this one)
  16. Press Cmd+I to summon the inline assistant
  17. Ask: “Explain how to add a table in Markdown” – it will generate

Part 5: Setting Up MkDocs with uv

MkDocs is a tool that turns your Markdown files into a professional website. We’ll use uv, a modern Python package manager, to install and run MkDocs.

Step 5.1: Install uv

  1. Open Terminal
  2. Navigate to your repository folder:
cd ~/Documents/leo-cabibihan
  1. Run the uv installation script:
curl -LsSf https://astral.sh/uv/install.sh | sh
  1. The script will download and install uv. You’ll see output confirming the installation.
  2. Close Terminal and open a new Terminal window (this ensures uv is available).
  3. Verify the installation:
uv --version

You should see a version number.

Step 5.2: Install Required Python Packages

Your repository should already have a requirements.txt file that lists the packages needed. Install them:

  1. In Terminal, make sure you’re in your repository folder:
cd ~/Documents/leo-cabibihan
  1. Run:
uv pip install -r requirements.txt

This will install: - MkDocs – the static site generator - MkDocs Material – a beautiful theme for your site - MkDocs Git Revision Date Localized Plugin – shows when each file was last edited

Step 5.3: Preview Your Website Locally

Now let’s see what your website looks like before publishing it online:

  1. In Terminal, run:
uv run mkdocs serve --livereload
  1. You’ll see output indicating the server is running. It should say something like:
INFO    -  MkDocs version: 1.5.3
INFO    -  Building documentation...
INFO    -  Documentation built in 2.4 seconds
INFO    -  [livereload] Server on http://127.0.0.1:8000
  1. Open your web browser and go to http://127.0.0.1:8000
  2. You should see your Fab Academy website!

Keep this terminal window open. The server will automatically rebuild your site whenever you save changes to any file. To stop the server, press Ctrl+C.

Part 6: Making Your First Changes

Now you’re ready to start documenting! Let’s make a small change to see how the workflow works.

Step 6.1: Open Your Repository in Zed

  1. Open Zed
  2. Go to File → Open…
  3. Navigate to your repository folder (~/Documents/leo-cabibihan)
  4. Click Open

You should see all your files in the sidebar on the left.

Step 6.2: Edit This File

  1. In the file browser, find and click on docs/assignments/week01.md
  2. You can now edit the content. Try changing some text (for example, update the “Final project idea” section with your actual project idea)
  3. As you type, notice that Zed shows formatting previews
  4. When you’re done, press Cmd+S to save

Step 6.3: See Your Changes Live

  1. Look at your web browser (showing http://127.0.0.1:8000)
  2. The page should have automatically refreshed with your changes
  3. If you don’t see the update, try refreshing the page manually (press Cmd+R)

Congratulations! You’ve just made your first change!

Part 7: Publishing Your Changes

Once you’re happy with your changes locally, it’s time to publish them to the web so everyone can see them.

Step 7.1: Understand the Workflow

The basic workflow for saving changes is:

Pull → Add → Commit → Push
  • Pull: Download any changes from the online repository (in case someone else made changes)
  • Add: Tell Git which files you want to save
  • Commit: Create a snapshot with a descriptive message
  • Push: Upload your changes to the online repository

Step 7.2: Pull Latest Changes

  1. Open Terminal
  2. Navigate to your repository:
cd ~/Documents/leo-cabibihan
  1. Run:
git pull

This ensures you have the latest version from the server.

Step 7.3: Check What Changed

Run:

git status

You’ll see: - Red files – changed files that are not yet tracked - Green files – files that have been added and are ready to commit

Step 7.4: Add Your Changes

To add all changed files:

git add .

Or to add a specific file:

git add docs/assignments/week01.md

Step 7.5: Commit Your Changes

Create a snapshot with a meaningful message:

git commit -m "Update week 1 documentation with project overview"

Tips for good commit messages: - Be specific: “Add project timeline” is better than “update” - Keep it concise (under 50 characters) - Use present tense: “Add” not “Added”

Step 7.6: Push to the Server

Upload your changes:

git push

If you set a passphrase for your SSH key, enter it when prompted.

Step 7.7: Verify Your Changes Are Live

  1. Wait about 2-5 minutes (the site needs to rebuild)
  2. Go to your Fab Academy website URL (ask your instructor for the link)
  3. You should see your changes published!

Essential Terminal Commands Reference

Here’s a quick reference for commands you’ll use frequently:

Command What It Does
cd foldername Change to a different folder
cd .. Go up one folder level
ls List files in current folder
pwd Show current folder path
mkdir name Create a new folder
cat filename Display file contents
clear Clear the terminal screen
Ctrl+C Cancel a running command

Git Commands Reference

Command What It Does
git status See what files have changed
git add . Stage all changes
git add filename Stage a specific file
git commit -m "message" Save changes with a message
git pull Download latest changes
git push Upload your changes
git log View commit history

Troubleshooting Common Issues

“Permission denied” when pushing

Make sure your SSH key is added to your GitHub/GitLab account. See Part 2 above.

Terminal says “No such file or directory”

Check that you’re in the correct folder. Use pwd to see where you are, and cd to navigate to your repository.

Website not updating online

  • Make sure you ran git push
  • Wait 2-5 minutes for the site to rebuild
  • Clear your browser cache (press Cmd+Shift+R)
  • Check for errors in your Markdown syntax

MkDocs serve won’t start

Make sure all packages are installed: uv pip install -r requirements.txt

Next Steps

Now that your environment is set up:

  1. Continue documenting this week: Fill in the rest of week01.md with your actual project ideas, research, and reflections
  2. Practice the workflow: Make small changes, preview locally, and publish
  3. Explore your site: Navigate through the folder structure and understand how the documentation is organized
  4. Add your first screenshot: See the “Adding Images” section below for instructions

Adding Images to Your Documentation

To add screenshots or images to your documentation:

  1. Create an images folder (if it doesn’t exist): bash mkdir -p docs/images

  2. Copy your image into that folder: bash cp ~/Desktop/my-screenshot.png docs/images/

  3. Add the image to your Markdown file: markdown ![Description of the screenshot](../images/my-screenshot.png)

  4. Save the file and check the live preview!

Summary

In this guide, you’ve learned to:

  • ✅ Install and configure Git on your Mac
  • ✅ Create SSH keys for secure authentication
  • ✅ Clone your personal Fab Academy repository
  • ✅ Install and use the Zed text editor
  • ✅ Set up MkDocs with uv to build your website
  • ✅ Preview changes locally with live reloading
  • ✅ Publish changes to share your work online

You now have a complete professional documentation workflow that will serve you throughout Fab Academy and beyond. Welcome to the world of version-controlled, collaborative documentation!

If you have questions or run into issues, don’t hesitate to ask your instructor or classmates for help. Happy documenting!

AI-Usage

This documentation was generated with the help of ai

prompt showing the Fab Academy documentation setup workflow