Skip to content

00-getting-started.md

Latest commit

 

History

History
484 lines (345 loc) · 13.4 KB

00-getting-started.md

File metadata and controls

484 lines (345 loc) · 13.4 KB
Raw

Getting Started with microfolio — Beginner's Guide

Welcome!

microfolio is a modern static portfolio generator, designed specifically for creatives: designers, architects, photographers, artists, graphic designers, collectives... It allows you to create a professional website to showcase your projects elegantly, without needing deep technical knowledge.

This guide takes you from a blank computer to a portfolio running locally, step by step. If you have never opened a terminal in your life, you are exactly the reader it was written for.

Important note about the terminal / command line

Don't worry! This guide uses the terminal (or "command line"), but no technical knowledge is required. You'll simply need to type or copy-paste a few simple commands. It's easier than it looks! 😊

How to open the terminal

On Mac:

  • Press Cmd + Space to open Spotlight
  • Type "Terminal" and press Enter
  • Or go to Applications > Utilities > Terminal

On Windows:

  • Press Windows + R
  • Type "powershell" and press Enter
  • Or search for "PowerShell" in the Start menu

Installing Prerequisites

For Mac

Option 1: Installation via Homebrew (Recommended)

Homebrew is a package manager for macOS that greatly simplifies the installation of development software.

  1. Install Homebrew (if you don't have it already):

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

  2. Trust the AKER tap, then install microfolio:

    brew trust aker-dev/tap
brew install aker-dev/tap/microfolio

  3. Create a new portfolio:

    microfolio new my-portfolio
cd my-portfolio

  4. Start the development server:

    microfolio dev

Your site will be accessible at: http://localhost:5555

Advantages of this method:

  • Automatic installation of all dependencies (Node.js, pnpm, Git)
  • Simplified commands: microfolio new, microfolio dev, microfolio build
  • brew upgrade microfolio keeps the command current; a site updates with pnpm update-microfolio (see Updating microfolio)

Option 2: Manual Installation

If you prefer manual installation or encounter problems with Homebrew:

1. Install Node.js

  1. Go to https://nodejs.org/
  2. Download the LTS version (recommended)
  3. Open the downloaded .pkg file and follow the wizard
  4. Close and restart Terminal for the installation to take effect
  5. Verify the installation by typing: 
    node --version
    You should see a version number of 22.13 or above (e.g., v22.14.0)

2. Install Git

  1. Open Terminal
  2. Type the following command: 
    xcode-select --install
  3. Installation software will open automatically
  4. Follow the on-screen instructions to install Xcode development tools
  5. Close and restart Terminal for the installation to take effect
  6. Verify the installation once completed: 
    git --version

3. Install pnpm

  1. Open Terminal
  2. Type the following command: 
    curl -fsSL https://get.pnpm.io/install.sh | sh
  3. Close and restart Terminal for the installation to take effect (or type source ~/.zshrc in the current terminal)
  4. Verify the installation: 
    pnpm --version

For Windows

1. Install Node.js

  1. Go to https://nodejs.org/
  2. Download the LTS version (recommended)
  3. Open the downloaded .msi file and follow the wizard
  4. Close and restart PowerShell for the installation to take effect
  5. Verify the installation by typing: 
    node --version

2. Install Git

  1. Download Git from https://git-scm.com/download/win
  2. Open the .exe file and follow the wizard
  3. Leave the default options
  4. Close and restart PowerShell for the installation to take effect
  5. Verify the installation: 
    git --version

3. Install pnpm

  1. Open PowerShell as administrator
  2. Type: 
    Invoke-WebRequest https://get.pnpm.io/install.ps1 -UseBasicParsing | Invoke-Expression
  3. Close and restart PowerShell for the installation to take effect
  4. Verify the installation: 
    pnpm --version

Essential Basic Commands

The cd (Change Directory) command

Allows you to navigate between folders:

cd Documents          # Go to Documents folder
cd ..                 # Go up one level
cd /                  # Go to root (Mac/Linux)
cd C:\                # Go to root (Windows)

Git commands

git clone [url]       # Download a project
git status            # See file status
git add .             # Add all changes
git commit -m "msg"   # Save changes

pnpm commands

pnpm install          # Install dependencies
pnpm dev              # Start development server
pnpm build            # Build site for production

Choosing Your Working Directory

On Mac

  1. Open Terminal
  2. Navigate to your Documents folder: 
    cd ~/Documents
  3. Or create a dedicated folder: 
    mkdir ~/Documents/Web-Projects
cd ~/Documents/Web-Projects

On Windows

  1. Open PowerShell
  2. Navigate to your Documents: 
    cd %USERPROFILE%\Documents
  3. Or create a dedicated folder: 
    mkdir %USERPROFILE%\Documents\Web-Projects
cd %USERPROFILE%\Documents\Web-Projects

Downloading microfolio

If you installed via Homebrew

Use the microfolio command directly:

microfolio new my-portfolio
cd my-portfolio

If you did the manual installation

Once in your working directory:

git clone https://github.com/aker-dev/microfolio.git my-portfolio
cd my-portfolio
pnpm install

Explanation:

  • git clone downloads the project
  • my-portfolio is the name of the created folder (you can change it)
  • cd my-portfolio enters the folder
  • pnpm install installs all necessary dependencies

Working on Your Site

Starting the development server

If you installed via Homebrew

Every time you want to work on your site:

  1. Open a terminal
  2. Navigate to your portfolio folder: 
    cd path/to/my-portfolio
  3. Start the server: 
    microfolio dev
  4. Open your browser and go to http://localhost:5555

If you did the manual installation

Every time you want to work on your site:

  1. Open a terminal (Terminal on Mac, PowerShell on Windows)
  2. Navigate to your microfolio folder: 
    cd path/to/my-portfolio
  3. Start the server: 
    pnpm dev
  4. Open your browser and go to http://localhost:5555

The server remains active as long as the terminal window stays open. To stop it, press Ctrl+C in the terminal.

Working Efficiently

  • Real-time changes: As soon as you modify a file, the browser refreshes automatically
  • Keep terminal open: Don't close the terminal window while working
  • One server at a time: You can only have one server running per project

Adding a New Project

Step 1: Create the folder

  1. Go to the content/projects/ folder
  2. Create a new folder for your project (example: my-first-project)
  3. The folder name must be lowercase, without spaces or special characters

Step 2: Copy the basic structure

The easiest way is to copy the example-project folder:

cp -r content/projects/example-project content/projects/my-first-project

Want more to look at? pnpm demo unzips the thirty projects of the demo site into content/projects/, and pnpm demo --remove takes them out again. git ignores them, so they never reach your repository.

Step 3: Modify the index.md file

Open the content/projects/my-first-project/index.md file and modify:

---
title: 'My project title' # required
date: '2024-01-15' # required, YYYY-MM-DD — everything else is optional
location: 'Paris, France'
coordinates: [48.8566, 2.3522] # Optional, for map
description: 'A short description of my project'
type: 'architecture' # or 'design', 'art', 'photography', etc.
tags: ['modern', 'sustainable'] # keywords — don't repeat the type
authors:
  - name: 'Your Name'
    role: 'Architect'
featured: true # true to highlight
---

## Description

Here, describe your project in detail...

Only title and date are required — a project missing either is skipped, and named in a summary at the end of the build. A project without a location simply shows none (no placeholder on its page or in the list), and without coordinates it has no marker on the map. The full field reference, including the optional info panel (owner, status, surface_area, cost), is in the Project Addition Guide.

Step 4: Add your files

  • Thumbnail: Replace thumbnail.jpg with your cover image
  • Images: Add your images to the images/ folder
  • Videos: Add your videos to the videos/ folder
  • Documents: Add your PDFs/documents to the documents/ folder

File Naming and Preparation Tips

File Naming

  • No spaces: my-image.jpg ✅ instead of my image.jpg ❌
  • Simple characters: avoid accents, cedillas, special characters
  • Lowercase: prefer lowercase names
  • Descriptive: main-facade.jpg rather than IMG_001.jpg

Image Preparation

  • Thumbnail: 1200×900 pixels recommended, 4:3 format
  • Gallery images: 1920px wide maximum
  • Supported formats: JPG, PNG, WebP, SVG
  • Compression: Use tools like TinyPNG to reduce size
  • Metadata: the lightbox displays the caption, credit and camera details embedded in your files — see Image Metadata for what to fill in and what to strip (GPS!) before publishing

Video Preparation

  • Format: MP4 H.264 for maximum compatibility
  • Size: Less than 50 MB per video
  • Alternative: For heavier videos, use YouTube or Vimeo and put the link in the text

Documents

  • Formats: PDF, DOC, DOCX, PPT, PPTX
  • Names: Avoid spaces and special characters
  • Size: Reasonable for web download

Introduction to Markdown

Markdown is a simple formatting language you use in your index.md files.

Basic syntax

# Main title

## Secondary title

### Tertiary title

**Bold text**
_Italic text_

- Bullet list
- Item 2
- Item 3

1. Numbered list
2. Item 2
3. Item 3

[Link to a site](https://example.com)
![Image](images/my-image.jpg)

Practical examples

## Project concept

This project explores the **relationship between space and light** in contemporary architecture.

### Materials used

- Raw concrete
- Thermoformed glass
- Corten steel

### Project stages

1. Site research and analysis
2. Sketching and design
3. Technical development
4. Implementation

![Project overview](images/overview.jpg)

For more details, consult the [technical file](documents/specifications.pdf).

Markdown Tips

  • Line breaks: Leave a blank line between paragraphs
  • Forced break: To start a new line inside a single paragraph — an address, opening hours, a credit list — end the line with \. Without it, Markdown runs the lines together
  • Images: Place them in the images/ folder and reference them with images/image-name.jpg
  • Links: Use [text](url) for external links — they open in a new tab automatically
  • Videos: a YouTube or Vimeo address alone on its line becomes the player
  • Titles: Use ## for sections (the main # is reserved for the project title)

Useful Resources

Recommended Tools

  • Text editor: VS Code, Sublime Text, or even Notepad++
  • Image compression: TinyPNG.com, ImageOptim (Mac)
  • Markdown: Typora, Mark Text for preview
  • Git: GitHub Desktop for graphical interface

Useful Links

Common Problems and Solutions

"Command not found" or "is not recognized"

  • Verify that Node.js, Git and pnpm are properly installed
  • Restart your terminal
  • On Windows, use PowerShell as administrator

Images not displaying

  • Verify that thumbnail.jpg exists
  • Avoid spaces in file names
  • Use supported formats (JPG, PNG, WebP)

Server won't start

  • Verify you're in the right folder (cd my-portfolio)
  • Verify that pnpm install was properly executed
  • Close and reopen the terminal

Changes not visible

  • Save your files
  • Verify the server is still running
  • Refresh the page (F5 or Ctrl+R)

Going Further

Once your portfolio runs locally, the next guides take over:

Contact and Support

For any questions or problems:

In your message, please specify:

  • Your operating system (Mac/Windows)
  • The problem encountered
  • The steps you followed
  • A screenshot if possible