Getting Started

Portosaur is a solution for building personal portfolios and digital notebooks with minimal configuration.

Prerequisites

Requirements:

• Bun (Recommended & primarily supported) or Node.js v24.15.0+.
• Git installed and available in your PATH.

Installation

You can install Portosaur globally with:

bun i -g portosaur@latest

After this, add the bin directory to PATH and restart shell.

Initialization

You can initialize a new project using the init command.

Interactive (Recommended)

This is the standard way to set up your site. It will guide you through configuring your providers and scaffold the project structure.

# If installed globally
porto init

# Or without installation
bunx portosaur init

Non-Interactive

Useful for automation and scripting.
Providing any configuration flag will enter to non-interactive mode, defaults will be used for missing flags.

# Example: with specific providers
porto init -p github -h github-pages -u soymadip -n "Shyam Roy"

# Or withought installation
bunx portosaur@latest init -p github -h github-pages -u soymadip -n "Shyam Roy"

Flag	Description	Default
-p, --vcs-provider	Git Provider ID (none, github, gitlab, codeberg, sourcehut)	github
-h, --hosting	Hosting Platform ID (none, github-pages, gitlab-pages, codeberg-pages, woodpecker, surge, netlify)	Selected VCS Default
-u, --username	Username for the Git provider	Git/OS User
-n, --name	Full Name for the site title	Full Name
-k, --no-install	Skip automatic dependency installation	false
-P, --project-name	Desired Project Name. Note that custom name is not recommended	vcs provider ideal name

It's not recommended to use custom name

Many(most) git hosting platforms require a specific repository name (e.g., username.github.io) to deploy to your root domain. A custom project name deploys to a subdirectory URL (e.g., username.github.io/custom-name).

Project Structure

The init command generates a project directory with the following structure:

my-site/
├── [workflow file/dir]        # CI workflow for automated deployment
├── blog/                      # Blog articles and deep dives
├── notes/                     # Markdown/MDX digital notebook
├── static/                    # Assets like images, icons, and PDFs
├── config.yml                 # Primary configuration file
├── package.json               # Project dependencies and scripts
└── README.md                  # Project overview

Key Directories

• notes/: Your digital second brain. Organize your notes using standard Markdown.
• blog/: Long-form articles and updates.
• static/: Global assets available at the site root.
• config.yml: Central source of truth for site settings and content.

Spin up the Site

Start the local development server with HMR to see changes in real-time:

cd <your-project-dir>
porto dev

The site will be available at http://localhost:3000.

Production Build

To generate a static version of your site ready for deployment:

porto build