devfolio.page

Your portfolio as code. Version control it like software.

Installation

npm install -g devfolio-page

Quick Start

# Create a new portfolio folder
devfolio-page init

# Edit the portfolio config
cd my-portfolio
nano portfolio.yaml

# Start development server with auto-rebuild
devfolio-page dev

# Or generate the static site once
devfolio-page render

Folder Structure

After running devfolio-page init, you get:

my-portfolio/
├── portfolio.yaml   # Your config
├── images/          # Add images here
└── site/            # Generated after render
    ├── index.html
    └── assets/

Commands

devfolio-page init

Create a new portfolio folder with config and images directory.

devfolio-page init

devfolio-page dev

Start development server with file watching and auto-rebuild.

devfolio-page dev                       # Start server on port 3000
devfolio-page dev --port 8080           # Use custom port
devfolio-page dev --theme modern        # Use a specific theme

Options:

• -p, --port <port> - Port for dev server (default: 3000)
• -t, --theme <theme> - Theme to use (srcl, modern, dark-academia)
• -o, --output <dir> - Output directory (default: ./site)

The dev server will:

• Watch portfolio.yaml and images/ for changes
• Automatically rebuild your site when files change
• Serve your site at http://localhost:3000

devfolio-page render

Generate a static website. Run from inside your portfolio folder.

devfolio-page render                        # Uses portfolio.yaml → site/
devfolio-page render --theme modern         # Use a different theme
devfolio-page render --output ./dist        # Custom output directory
devfolio-page render other.yaml             # Use a different YAML file

Options:

• -t, --theme <theme> - Theme to use (srcl, modern, dark-academia)
• -o, --output <dir> - Output directory (default: ./site)

devfolio-page validate <file>

Validate your portfolio YAML file.

devfolio-page validate portfolio.yaml

YAML Schema

Basic Example

meta:
  name: Your Name
  title: Your Title
  location: Your Location
  timezone: America/Los_Angeles  # optional
  tagline: A short tagline        # optional
  avatar: images/avatar.jpg       # optional

contact:
  email: [email protected]
  github: username        # optional
  linkedin: username      # optional
  twitter: username       # optional
  website: https://...    # optional

bio: |
  A few sentences about yourself.
  Can be multiple lines.

# Extended about section (generates dedicated /about page)
about:
  short: Brief intro for homepage
  long: |
    Longer bio with markdown support.

    Multiple paragraphs work great here.

sections:
  experience:
    - company: Company Name
      role: Your Role
      date:
        start: 2024-01
        end: present
      location: City, State  # optional
      highlights:
        - Achievement 1
        - Achievement 2

  projects:
    - name: Project Name
      url: https://github.com/...  # optional
      description: What the project does
      tags: [React, TypeScript]
      featured: true  # optional

  skills:
    Frontend: [React, TypeScript, Next.js]
    Backend: [Node.js, Python, Go]
    Tools: [Git, Docker, AWS]

  writing:
    - title: Article Title
      url: https://...
      date: 2024-12
      description: Brief description  # optional
      featured: true  # optional

  education:
    - institution: University Name
      degree: B.S. Computer Science
      date:
        start: 2016-09
        end: 2020-05
      location: City, State  # optional
      highlights:  # optional
        - Dean's List
        - Relevant coursework

theme: srcl  # srcl, modern, dark-academia

settings:
  show_grid: false       # show character grid overlay
  enable_hotkeys: true   # enable keyboard shortcuts
  color_scheme: dark     # dark or light
  animate: subtle        # none, subtle, or full

Rich Projects (Case Studies)

For a multi-page portfolio with dedicated project pages, use the top-level projects field:

projects:
  - id: my-project           # URL slug: /projects/my-project.html
    title: My Project
    subtitle: A brief tagline
    featured: true
    thumbnail: images/project-thumb.jpg
    hero: images/project-hero.jpg
    meta:
      year: 2024
      role: Lead Developer
      timeline: 3 months
      tech: [React, Node.js, PostgreSQL]
      links:
        github: https://github.com/...
        demo: https://demo.example.com
        live: https://example.com
    sections:
      - type: overview
        content: |
          Markdown content describing the project.
      - type: image
        src: images/screenshot.png
        caption: Main dashboard view
      - type: metrics
        data:
          - label: Users
            value: "10,000+"
          - label: Uptime
            value: "99.9%"
      - type: outcomes
        content: |
          What was achieved and lessons learned.

Experiments

For side projects and explorations:

experiments:
  - title: Creative Coding
    description: Generative art experiments
    image: images/experiment.png
    github: https://github.com/...
    demo: https://demo.example.com
    tags: [p5.js, WebGL]

Page Customization

Customize titles and descriptions for each page:

pages:
  projects:
    title: My Work
    description: A curated selection of projects and case studies.
  about:
    title: About Me
    description: Designer, developer, and coffee enthusiast.
  experiments:
    title: Lab
    description: Creative experiments and explorations.
  writing:
    title: Blog
    description: Thoughts on design and technology.

If not specified, each theme provides sensible defaults.

Themes

SRCL (Default)

Terminal-inspired aesthetic from sacred.computer.

• Monospace typography
• Character-based spacing
• Keyboard navigation (Ctrl+T, Ctrl+G)
• Dark/light mode toggle

Modern

Clean, contemporary design.

• Sans-serif fonts
• Card-based layout
• Smooth animations

Dark Academia

Classical, scholarly design.

• Serif typography
• Warm color palette
• Book-like layout

Keyboard Shortcuts

When enable_hotkeys: true:

| Key | Action | |-----|--------| | Ctrl+T | Toggle dark/light theme | | Ctrl+G | Toggle grid overlay | | 1-9 | Jump to section | | Esc | Close accordions |

Philosophy

Inspired by RenderCV. Your portfolio should be:

• Version controlled - Track changes with Git
• Content-first - Separate content from presentation
• Portable - Deploy anywhere (Vercel, Netlify, GitHub Pages)
• Fast - Static HTML, no JavaScript required
• Accessible - Semantic HTML, keyboard navigation

Development

# Install dependencies
npm install

# Run in dev mode
npm run dev

# Build
npm run build

# Link globally for testing
npm link

Examples

See the examples/ directory:

• minimal.yaml - Bare minimum required fields
• full.yaml - All sections and options
• engineer.yaml - Realistic software engineer example

Built with SRCL.