Documentation

Getting Started with Repofolio

Everything you need to scaffold, configure, and deploy your GitHub-powered portfolio in minutes.

Quick Start

Run the following command to scaffold your portfolio project:

bash

npx create-repofolio

The CLI will prompt you for:

Project name — The folder name (e.g. my-portfolio)
GitHub username — Used to fetch all your profile data
Theme preference — Dark, Light, or System
Install dependencies — Optional auto-install

bash

cd my-portfolio
npm install   # if you skipped auto-install
npm run dev

Note

The generated project is a standard Next.js 14 App Router app with Tailwind CSS. Customise any part freely.

Configuration

Open the generated .env.local and fill in:

.env.local

# Your public GitHub username
NEXT_PUBLIC_GITHUB_USERNAME=your_username

# GitHub Personal Access Token
GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxx

Required PAT Scopes

repo

Access private repositories

read:user

Read profile bio, avatar, location

read:org

Read organisation membership

public_repo

Public repos only (minimal alternative)

Warning

Never commit .env.local to git. The generated .gitignore excludes it. Use Vercel environment variables for production.

Customizing Projects

Create a repofolio/ folder at the root of any repository:

Repository

your-repo/
├── src/
├── package.json
└── repofolio/
    ├── thumbnail.png   ← custom project image
    └── description.md  ← extended description

thumbnail.png

Overrides the auto-generated Microlink screenshot for this project's card image.

Pro Tip

If your site is behind Cloudflare anti-bot protection, Microlink will capture the challenge page instead of your app. Adding thumbnail.png bypasses this entirely — your image is always served directly from GitHub.

description.md

Adds rich markdown content to the project detail page. Supports full GFM: headings, lists, tables, code blocks, images, and links.

repofolio/description.md

## About

A full-stack e-commerce app built with **Next.js** and **Stripe**.

### Tech Stack
| Layer    | Technology        |
|----------|-------------------|
| Frontend | Next.js, Tailwind |
| Backend  | Prisma, Postgres  |
| Payments | Stripe            |

GitHub Topics API

Add specific GitHub topics to repositories to control how they appear in your portfolio — no code changes required.

portfolio

Include Forked Repos

Forked repos are hidden by default. Adding this topic explicitly includes them in your portfolio listing.

featured

Override Pinned Repos

Pins this repo at the very top of your portfolio, overriding the standard GitHub pinned repos order.

Topic	Effect	Priority
`featured`	Pinned at top, overrides GitHub pins	Highest
`(GitHub pinned)`	Shown in default pinned order	High
`portfolio`	Includes forked repos in listing	Medium
`(none)`	Standard public repos	Default

Pro Tip

Combine both topics on a forked repo to include it in your portfolio AND pin it at the top.

Deploy to Vercel →Open an Issue →