makefolio

A modern, fast static site generator built for professional portfolio websites.

Built with Python, Jinja2, and Markdown. Generates clean, responsive HTML with dark mode, scroll animations, and SEO out of the box.

---

Features

• Markdown + YAML frontmatter content authoring with zero boilerplate
• Four content types — projects, experience, education, and standalone pages
• Dark / Light theme with toggle and localStorage persistence
• Scroll-reveal animations via IntersectionObserver
• Animated skill bars and stat counters
• Responsive mobile menu with hamburger toggle
• SVG social icons — GitHub, GitLab, LinkedIn, Twitter/X, Email, and 10+ more
• Open Graph & Twitter Card meta tags on every page
• Sitemap.xml auto-generation
• Reading time estimates on content pages
• Tag collection across projects
• Extensible theme system with Jinja2 templates
• Hot-reload dev server with file watching
• Clean URLs (extensionless routing)

---

Installation

Method	Command
pip	pip install makefolio
uv	uv pip install makefolio
From source	git clone https://github.com/martian56/makefolio.git && cd makefolio && uv pip install -e ".[dev]"

Requirements: Python 3.11+

---

Quick Start

# 1. Scaffold a new portfolio
makefolio init my-portfolio

# 2. Enter the project directory
cd my-portfolio

# 3. Build the static site
makefolio build

# 4. Start the dev server with hot reload
makefolio serve

Your site is now live at http://localhost:8000.

---

Creating Content

makefolio new project    --name my-project    # Portfolio project
makefolio new experience --name my-role       # Work experience entry
makefolio new education  --name my-degree     # Education entry
makefolio new page       --name contact       # Standalone page

Each command creates a Markdown file with the correct frontmatter template, ready to edit.

---

Project Structure

my-portfolio/
├── content/
│   ├── config.yaml          # Site config, social links, skills, nav
│   ├── about.md             # Standalone pages
│   ├── projects/            # Portfolio project entries
│   ├── experience/          # Work experience (sorted by start_date)
│   └── education/           # Education entries (sorted by start_date)
├── themes/
│   └── default/
│       ├── templates/       # Jinja2 HTML templates
│       └── static/          # CSS, JS assets
├── static/                  # Custom static files (copied to build/)
└── build/                   # Generated output

---

Configuration

Edit content/config.yaml to customize your site:

site:
  title: "Jane Doe"
  description: "Full-Stack Engineer"
  author: "Jane Doe"
  url: "https://janedoe.dev"
  theme: "light"                # "light" or "dark" default
  greeting: "Hello, I'm"       # Hero section greeting
  headline: "Software Engineer" # Gradient text under name

social:
  github: "janedoe"
  linkedin: "janedoe"
  email: "jane@example.com"
  # twitter, gitlab, website, medium, devto, dribbble,
  # behance, instagram, youtube, stackoverflow, codepen,
  # keybase, telegram

skills:
  - name: "Python"
    level: 95
  - name: "React"
    level: 88

nav:
  - name: "About"
    url: "/about"
  - name: "Projects"
    url: "/projects"
  - name: "Experience"
    url: "/experience"
  - name: "Education"
    url: "/education"

---

Content Frontmatter

Project — content/projects/my-project.md

---
title: "My Project"
date: 2024-06-15
tags: ["python", "react", "docker"]
featured: true
description: "Short description for cards"
---

Your project write-up in Markdown...

Experience — content/experience/my-role.md

---
title: "Senior Engineer"
company: "Acme Corp"
position: "Senior Engineer"
location: "Remote"
start_date: 2023-01-15
end_date: ""
current: true
---

Role description in Markdown...

Education — content/education/my-degree.md

---
title: "B.Sc. Computer Science"
institution: "MIT"
degree: "Bachelor's"
field: "Computer Science"
location: "Cambridge, MA"
start_date: 2019-09-01
end_date: 2023-05-15
gpa: "3.9"
---

Additional details in Markdown...

---

Built With

---

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Format (Ruff)
uv run ruff format src/

# Lint (Ruff)
uv run ruff check src/

# Type check (ty)
uv run ty check src/

# Run tests with coverage
uv run pytest --cov=src/makefolio --cov-report=term

---

Contributing

Contributions are welcome! Please open an issue for bugs or feature ideas, then submit a pull request.

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes using Conventional Commits (feat:, fix:, docs:, etc.)
4. Push to your branch and open a PR

---

Contributors

---

Star History

---

License

This project is licensed under the MIT License — see the LICENSE file for details.