Building a Professional Portfolio with Quarto and GitHub Pages

Brian Cervantes Alvarez

Friday, January 31, 2025

Why Build a Portfolio?

  • Key Benefits
    • Showcase Your Work: Present projects, skills, and accomplishments in one place.
    • Increase Visibility: Stand out in applications and networking opportunities.
    • Professional Branding: Establish an online presence to showcase your expertise.

Why Build a Portfolio?

  1. First Impressions: Portfolios offer a visual and tangible way to make a lasting impression.
    • Example: Recruiters can easily browse your work without sifting through resumes.
  2. Adaptability: A portfolio evolves with your career, highlighting your most relevant work.
    • Example: Tailor sections for academic, industry, or freelance roles.
  3. Competitive Edge: Portfolios differentiate you from other candidates who only submit resumes.
    • Example: Highlighting unique skills like interactive data visualizations.

Immediate Benefits

  • Within 24 Hours of Launch
    • ✅ Live portfolio website deployed via GitHub Pages
    • ✅ Professional URL to share (yourusername.github.io)
    • ✅ Foundational structure for future content
  • Next 30 Days
    • Increased visibility in search results
    • Recruiter inquiries via portfolio contact form
    • First project documentation completed

Long-Term Career Impact

  1. Consistency: Regular updates keep your portfolio relevant and demonstrate growth.
  2. Networking Tool: Share your portfolio in conferences, talks, and online forums.
  3. Skill Demonstration: Show expertise with tools (Quarto, GitHub, etc.) and methodologies.
  4. Consistency: Regular updates demonstrate growth and commitment
  5. Negotiation Leverage: Concrete proof of skills = salary justification

Overtime, you’ll master HTML, CSS, and JavaScript to craft custom websites 👀 😮 Not bad!

Types of Portfolios

  • Statistics: Experimental design, Bayesian modeling, survey methodology, and applied data analysis.
  • Data Science: Interactive dashboards, modeling case studies, and machine learning experiments.
  • Academic: Published papers, research highlights, teaching materials, and peer-reviewed work.
  • Industry: Client work, key deliverables, project timelines, and business impact reports.
  • Creative/Design: Data visualizations, UI/UX case studies, and storytelling through data.
  • Open Source: Contributions to repositories, package development, and collaborative coding projects.

Data Science Portfolio

Impressive Yourself & Future Recruiters With An Awesome Landing Page

Portfolio Section: Home

Define Who You Are (A Human…I think?)

Portfolio Section: About

Highlight Your Best Projects! Maybe You Built A Better Deep Seek Model (SHOW IT!)

Portfolio Section: Projects

Update Your Network Thru Mini-Projects or Articles!

Portfolio Section: Blog

Yapper? Great! Put on your Website!

Portfolio Section: Talks

Public Health Portfolio

Not Convinced? Take a Peek at This!

Portfolio Section: Home

Questions?

Mini-break

Portfolio Time!

Part 1: Github

GitHub Pages Workflow

  1. Clone: Create local copy of your repository

    git clone https://github.com/yourusername/yourrepo.git

  2. Modify: Add Quarto files (.qmd) and content

  3. Commit: Save changes with descriptive messages

    git commit -m "Added project showcase section"

  4. Push: Sync to GitHub

    git push origin main

Always pull before pushing to avoid conflicts!

Essential Git Concepts

  • Key Operations
    • Commit: Snapshots changes with a timestamp and message
    • Push: Uploads commits to GitHub
    • Pull: Downloads others’ changes (critical for collaboration)
  • Danger Zone
    • ❌ Never use git push --force
    • ❌ Never commit sensitive data (PATs, credentials)

GitHub Pages Pro Tips

  1. PAT Security
    • Store tokens with gitcreds_set() in R
    • Never include in code or commit messages
  2. Atomic Commits
    • One logical change per commit
    • Example: “Fixed mobile layout” vs “Updated stuff”
  3. .gitignore
    • Always exclude: .env, .Rdata, .DS_Store
    • Quarto-specific: _site/, _cache/

Troubleshooting Checklist

  1. Authentication issues?
    • Refresh PAT with usethis::create_github_token()
  2. Merge conflicts?
    • Use git pull --rebase to integrate changes cleanly
  3. Site not updating?
    • Check GitHub Actions logs
    • Verify gh-pages branch exists

Part 2: Quarto + GitHub Pages Setup

Step 1: Create Your Quarto Website

Using RStudio:

  • Start a New Project:
    • Navigate to File → New Project → Version Control → Git → Input your Repo Link → Create Project .

Add your Website files with the Terminal:

  •   quarto create-project . --type website

Essential Files:

  • _quarto.yml – Configuration settings
  • index.qmd – Homepage content
  • about.qmd - About page content
  • styles.css – Custom styling for your site
  • Add .noJekyll!

Step 2: Understand Project Structure & Key Files

Typical Repository Structure:

📁 yourRepoName/
├── 📁 _site/          # Auto-generated site files (exclude from repo)
├── 📄 _quarto.yml     # Main configuration file
├── 📄 index.qmd       # Homepage content
├── 📄 about.qmd       # About page
└── 📄 styles.css      # Custom CSS styles

Important .gitignore Entries:

_site/
_cache/
.Rproj.user
.DS_Store

Ensure sensitive and auto-generated files are excluded.

Step 3: Configure _quarto.yml

Core Configuration:

project:
  type: website
  output-dir: docs  # Required for GitHub Pages

website:
  title: "My Professional Portfolio"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - href: about.qmd
        text: About
    right:
      - icon: github
        href: https://github.com/yourusername
format:
  html:
    theme: cosmo # Bootstrap Theming (automatic, simple)
    css: styles.css # Customize it to your hearts content
    toc: true

Key Points:

  • output-dir set to docs aligns with GitHub Pages requirements.
  • Customize the navbar to include relevant sections.
  • Choose a Bootswatch theme for aesthetic consistency.

Step 4: Configure GitHub Pages

Configure GitHub Pages:

  1. Navigate to Settings:
    • Go to Settings → Pages.
  2. Set Source:
    • Choose the main branch and /docs folder as the source.
  3. Save Configuration:
    • GitHub will provide a link to your live site once deployed.

Step 5: Deploy & Customize Your Site

Initial Deployment Steps:

  1. Render Locally:

    quarto render
    • Ensure the docs/ directory is generated with your site files.

  2. Commit Changes:

    git add .
git commit -m "Initial site setup"

  3. Push to GitHub:

    git push origin main

Customize Your Site:

  • Update Navigation:
    • Modify the navbar section in _quarto.yml to include new pages.
  • Apply Custom Styles:
    • Edit styles.css to personalize the appearance.
  • Add Content:
    • Create new .qmd files for additional sections like Blog or Contact.

References