Principles and practices, project management.

// weekly schedule

// overview

Week 1 sets the foundation for the entire Fab Academy journey. It focuses on two things: establishing my documentation workflow (Git, GitLab, building my personal website) and sketching initial ideas for my final project. According to Neil’s and local instructor’s orientation, the key principle is “document as you do”—recording every step, problem, and solution becomes a habit I should carry through all 18 weeks.

// learning objectives

Communicate an initial project proposal. Identify and utilise version control protocol(s). Explore and use website development tool(s).

// assignments

• download, read, and sign the student agreement and commit the file to your repo.
• work through a git tutorial.
• describe briefly what it will do and who will use it.
• make a website and describe how you did it.
• create a section about yourself on that website.
• add a page with your sketch and description of your final project idea(s).
• document steps for setting up your Git repository and adding files to it.
• push to your class GitLab repository.

// research

the tools (my stack).

Considering that documenting plays such a critical roll in the Fab Academy program, my first question was: How could I work locally, prepare my documentation and then publish it? I am familiar with Obsidian, a free and flexible app that cares for the user’s privacy. It is a markdown editor, which I believe should ease my whole process. It works with plain .md files stored locally in a folder called a “vault.” Obsidian adds features like internal linking and templates, but at the end of the day, it’s just reading and writing text files.

But this is just the local editor. I need something else so I found Astro. Astro is a static site generator. They claim that:

Astro builds websites by converting content into 100% static HTML, CSS, and JavaScript files at build time, resulting in lightning-fast performance with minimal client-side JavaScript.]

In my case, Astro takes my markdown files, runs them through templates and layouts, and spits out a folder of plain HTML/CSS/JS. That output is what actually gets published.

Git Version control. It tracks every change I make and syncs everything with a remote repository on GitLab. When I push, it triggers the deployment.

GitLab CI/CD The automation layer. Every time I push to the repository, a pipeline kicks in: it installs dependencies, builds the site with Astro, and publishes the result to GitLab Pages.

VSCodium My code editor. Open-source fork of VS Code. I use it for anything that isn’t pure content writing—Astro components, configuration files, troubleshooting.

1. I write content in Obsidian.
2. edit code and config in VSCodium when needed.
3. run npm run dev* to preview the site locally at localhost:4321.
4. once I’m happy with the result, I commit and push with Git.
5. the pipeline builds and deploys automatically.

npm run dev

starts a local development server. Astro watches my files and rebuilds the site automatically when I save changes. I see the result instantly in my browser without pushing anything to GitLab.

// process

web

After playing around with the GitLab editor, uploading some files and pictures, I started researching for a minimalist, modern and clutter-free template. Being an occasional Figma’s user I went straight looking for some of the community’s free templates. This one seemed right for the job:

Some tweaking and prompting with their in-built AI (Figma Make), made me came out with the current design.

ai usage disclosure

For the past year and a half, I have been using large language models extensively—mainly Claude, but also ChatGPT, Perplexity, local models like Meta Llama and others—as part of my daily workflow. I use them to learn new concepts, troubleshoot code, draft documentation, and generally move faster through technical work.]

For Fab Academy, I am documenting the prompts and conversations that contributed to my progress. This is not about hiding AI assistance; it is about being transparent with how I actually work.

Below are the key prompts I used to set up and refine this documentation site.

Prompts.

Figma’s template tweaking:

• Initial concept & aesthetic:

  Create a documentation website for Fab Academy 2026 inspired by a minimalist art gallery aesthetic. The design must be strictly rectangular with zero rounded corners (rounded-none). Implement a dual navigation system: a persistent vertical sidebar on the left and a horizontal navigation bar at the top. Ensure my name is presented subtly and discreetly, maintaining a clean and professional look. Use a neutral color palette (whites, blacks, and grays).

• Structure & grid layout:

  Develop a homepage featuring a clean, responsive grid of 18 cards, representing the 18 weeks of the Fab Academy program. Each card should display the week number and the specific assignment title. Use high-quality placeholder images for each week that reflect a ‘maker’ or ‘laboratory’ environment. All typography should be professional and minimal.

• Navigation & componentization:

  Build a SideNavigation component for main sections (Home, About, Final Project, Agreements) and a TopNavigation component that displays the current section or week title. Ensure the sidebar stays fixed on desktop and collapses gracefully on mobile. The transition between the grid and individual week pages should feel seamless.

• Dynamic week pages:

  Implement a dynamic system to handle 18 individual week pages. Each page should include a header with the week’s title, a section for documentation text, an image gallery for process photos, and a dedicated area for file downloads (STLs, code, etc.). Use the official Fab Academy 2026 schedule for the week titles, starting with ‘Principles and Practices’ and ‘Project Management’.

• Visual refinement:

  Refine the UI to ensure absolute ‘rectangularity’. Every button, card, and container must have border-radius: 0. Use thin, subtle borders (1px) to separate layout sections instead of heavy shadows, mimicking a digital architectural blueprint or a modern gallery catalogue.

Prompts using Claude:

• Obsidian vault structure:

  Configure the structure of the new Obsidian Vault step by step, with the most probable sections and subsections.

Solution: Created vault at C:\fab-academy\src\content\ with:

src/content/
├── _assets/           # Images (excluded from collections)
│   ├── weeks/week01-18/
│   ├── final-project/
│   └── about/
├── weeks/             # 18 weekly assignment files
├── final-project/     # Final project documentation
├── pages/             # Static pages (about, student-agreement)
└── _templates/        # Templater templates

Once the structure was created, I took care of the Obsidian settings.

Configuration:

• Content collections configuration:

  Configure Astro content collections.

Solution: Created src/content/config.ts:

typescript

import { defineCollection, z } from 'astro:content';

const weeks = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    week: z.number(),
    date: z.coerce.date(),
    topic: z.string(),
    status: z.enum(['not-started', 'in-progress', 'completed']).default('not-started'),
    tags: z.array(z.string()).default([]),
    heroImage: z.string().optional(),
  }),
});

• Figma’s design integration:

  Integrate Figma React components into Astro project.

Solution:

• Installed Tailwind CSS v3: npm install -D tailwindcss@3 @astrojs/tailwind

• Created MainLayout.astro with sidebar navigation

• Applied Figma design styles using Tailwind classes

• Layout includes: side navigation, mobile header, footer.

• GitLab CI/CD configuration:

  Deploy to GitLab Pages.

Solution: Final .gitlab-ci.yml:

yaml

image: node:20

pages:
  cache:
    paths:
      - node_modules/
  script:
    - npm ci
    - npm run build
    - rm -rf public
    - mv dist public
  artifacts:
    paths:
      - public
  only:
    - main

Debugging:

Obviously, not everything worked fine the first time, some debugging was needed.

1 MDX comment syntax.

Problem: MDX files with HTML comments (<!-- -->) caused errors.

Solution: Convert all comments to JSX syntax:

powershell

Get-ChildItem -Path "C:\fab-academy\src\content" -Filter "*.mdx" -Recurse | ForEach-Object {
    $content = Get-Content $_.FullName -Raw
    $content = $content -replace '<!--', '{/*' -replace '-->', '*/}'
    Set-Content -Path $_.FullName -Value $content -NoNewline
}

2 Image workflow.

Problem: Images in _assets/ folder not rendering in Astro.

Solution: Use the public/ folder for images:

1. Store images in C:\fab-academy\public\images\about\
2. Reference in markdown: ![Alt text](/2026/labs/leon/students/inigo-gutierrez/images/about/image.jpg)
3. Rename files to avoid spaces: mi-pequeno-unicornio-arcoiris.jpg

3 File Extensions for Obsidian.

Problem: Obsidian can’t edit .mdx files natively.

Solution:

• Rename .mdx to .md for pages edited in Obsidian
• Clear Astro cache after renaming: Remove-Item -Recurse -Force "C:\fab-academy\.astro"
• Enable “Detect all file extensions” in Obsidian settings

// git

git is the most popular version control system (VCS). git let’s us:

• track changes across multiple files.
• compare versions of a project.
• “time travel” back to old versions.
• revert to a previous version.
• collaborate and share changes.
• combine changes.

Git installation and tutorial.

The official git’s site offers a lot of helpful information. One interesting resource is this cheat sheet with the most common commands:

Following Eduardo Chamorro’s tutorial led me to a spotless installation.

There was though one topic that kept thinking. Checking every element of the SSH key generation in the Internet

ssh-keygen -t rsa -C "your-email@example.com"

led me to a comparison of two digital signature algorithms:

I ended up choosing the ed25519 SSH key generation. So far everything works fine.

Git Workflow

Basic commands:

First I make sure what files have changed:

cd C:\fab-academy git status

Check commit size before pushing:

powershell

git diff --stat

Then, proceed with the commit and push:

```powershell
git add .
git commit -m "Description of changes"
git push

generate a prompt for a new chat. In this new chat a will need a basic explanation of my final project: an standing desk regulable with a small display, but also with a backup manual leaver.

I attached a couple of pictures so you get an idea. My