A ready-to-deploy static portfolio website for data science students. Write your content in simple YAML files, run one command to build, and publish to GitHub Pages — no web-development experience required.

What you get out of the box:

• A professional single-page site with an About section, project cards, and contact links.
• Light and dark themes you can switch with one config line.
• Two example projects that demonstrate how to write clearly for a hiring-manager audience.

uv sync
uv run python build.py
uv run python serve.py   # opens http://localhost:8000 in your browser

Install uv (if you don't have it):

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install the project dependencies:

uv sync

Build the example site and open it locally:

uv run python build.py
uv run python serve.py

serve.py will open http://localhost:8000 in your browser automatically. Press Ctrl+C in the terminal to stop the server.

Do not overwrite the example files. Copy them and edit the copies so you always have a working reference to look back at.

cp content/example_student.yaml content/my_profile.yaml

Open content/my_profile.yaml and fill in:

Writing multi-paragraph about text

The about field supports Markdown. Use | (literal block) in your YAML so blank lines and formatting are preserved:

# Use | to write multiple paragraphs and Markdown formatting
about: |
  First paragraph here. *This text will be italic.*

  Second paragraph here. **This text will be bold.**

# Don't use > — it collapses everything into a single line,
# so blank lines between paragraphs are lost.

Then open portfolio_config.yaml and change:

student_file: content/my_profile.yaml

cp content/projects/example_project_1.yaml content/projects/my_project_1.yaml

Fill in each field:

Add each project to portfolio_config.yaml:

projects:
  - content/projects/my_project_1.yaml
  - content/projects/my_project_2.yaml

Once you have your own projects listed, remove the example_project_*.yaml lines.

Replace the placeholder images by saving your own image files to static/img/ and updating image_path in the corresponding project YAML. Any common image format (.png, .jpg, .svg) will work.

In portfolio_config.yaml:

theme: light    # or: dark, msu-light, msu-dark

The following themes are included out of the box:

MSU colors follow the official brand guidelines at brand.msu.edu/visual/color-palette.

Edit static/css/base.css to change layout, spacing, typography, or any style that should apply to both themes.

1. Copy an existing theme file:

   cp static/css/themes/light.css static/css/themes/ocean.css

2. Edit the colors in ocean.css.

3. Select it in portfolio_config.yaml:

   theme: ocean

4. Rebuild:

   uv run python build.py

Before you push: The docs/ folder is not included in this template repo — you need to generate it first. Run uv run python build.py locally and commit the resulting docs/ folder before enabling GitHub Pages, otherwise GitHub will have nothing to serve.

1. Remove docs/ from .gitignore.

   The template's .gitignore excludes docs/ so the example site isn't committed to the template repo itself. In your own fork, you need to track docs/ so GitHub Pages can serve it. Open .gitignore and delete (or comment out) this line:

   docs/

2. Build the site and commit docs/.

   uv run python build.py
   git add docs/
   git commit -m "build site"

3. Push your repo to GitHub.

4. In your repository on GitHub, go to Settings → Pages.

5. Under Build and deployment → Source, select Deploy from a branch.

6. Set the branch to main (or your default branch) and the folder to /docs.

7. Click Save. GitHub will build and publish your site within a minute or two.

Your site will be available at:

https://<your-github-username>.github.io/<your-repo-name>/

Note: If you name the repository <your-github-username>.github.io, GitHub will publish it at https://<your-github-username>.github.io/ (no repo name suffix).

Already have a personal site at https://<username>.github.io/?

That site lives in a special repo named exactly <username>.github.io. As long as you put this portfolio in any other repo (e.g. data-science-portfolio), GitHub Pages will publish it alongside your existing site at a separate URL — the two sites will not interfere with each other:

Because this template uses only relative paths for CSS and images, no code changes are needed — the site will work correctly whether it is served from the root or from a subdirectory.

When you're making updates, the typical workflow will be:

1. Edit YAML content files and/or CSS.
2. uv run python build.py ← regenerate the site with your changes
3. uv run python serve.py ← preview in browser
4. git add . && git commit -m "update portfolio" ← commit your changes
5. git push origin main ← GitHub Pages auto-deploys

Files you should not need to edit unless you want to change the page structure:

• templates/base.html — HTML shell (header, nav, footer)
• templates/index.html — Page layout and section order
• build.py — Site generator
• serve.py — Local preview server

├── pyproject.toml              # Python dependencies (managed by uv)
├── portfolio_config.yaml       # Main site config — start here
├── build.py                    # Site generator script
├── serve.py                    # Local preview server
├── content/
│   ├── example_student.yaml    # Example student profile
│   └── projects/
│       ├── example_project_1.yaml
│       └── example_project_2.yaml
├── templates/
│   ├── base.html               # HTML shell (header, nav, footer)
│   └── index.html              # Page content template
├── static/
│   ├── css/
│   │   ├── base.css            # Layout styles (all themes)
│   │   └── themes/
│   │       ├── light.css
│   │       ├── dark.css
│   │       ├── msu-light.css
│   │       └── msu-dark.css
│   └── img/
│       ├── placeholder_project_1.png
│       └── placeholder_project_2.png
└── docs/                       # Generated output — served by GitHub Pages

This project is released under the MIT License. You are free to use, modify, and distribute it — including for your own portfolio. See the LICENSE file for full terms.

This project was drafted and built with the help of AI (Claude). The initial code and structure were generated by the model based on the provided instructions that aligned with the goals for this repository. The generated content and code has been reviewed and edited to ensure quality and correctness.