pages/QUICKSTART.md

Quick Start Guide

Get your al-folio site running in 5 minutes. This guide is for users who just want a working website quickly without deep customization.

Video Tutorial: Watch a walkthrough of these steps here

• Quick Start Guide
  • Step 1: Create Your Repository (1 min)
  • Step 2: Configure Deployment (1 min)
  • Step 3: Personalize (2 min)
  • Step 4: View Your Site (1 min)
  • What's Next?
    • Add Your Content
    • Customize Appearance
    • Learn More
    • Get Help from AI

Step 1: Create Your Repository (1 min)

⚠️ Important: Use the "Use this template" button, NOT the fork button. This ensures your site is independent and you won't accidentally submit your personal changes back to the al-folio project.

1. Go to the al-folio repository
2. Click the green "Use this template" button (top right), then select "Create a new repository"
3. Name your repository:
   • Personal/Organization site (if you want your site to be at username.github.io): username.github.io (replace username with your GitHub username)
   • Project site (if you want your site to be at username.github.io/project-name): Any name (e.g., my-research-website)
4. Click "Create repository from template"

Already forked by mistake? No problem. Your fork will work fine—just be careful when making changes. Create a new branch for your updates (e.g., git checkout -b my-site-updates) and make sure you push to your own repository, not the main al-folio project.

Step 2: Configure Deployment (1 min)

1. Go to your new repository → Settings → Actions → General → Workflow permissions
2. Select Read and write permissions
3. Click Save

Step 3: Personalize (2 min)

1. Open _config.yml in your repository
2. Update these fields:

   title: My Website
   first_name: Your
   last_name: Name
   url: https://your-username.github.io # or your custom domain
   baseurl: # Leave this empty (do NOT delete it)
   

3. Click Commit changes (at the bottom of the page)

Step 4: View Your Site (1 min)

1. Go to your repository → Actions tab
2. Wait for the "Deploy site" workflow to complete (look for a green checkmark, ~4 minutes)
3. Go to Settings → Pages → Build and deployment
4. Make sure Source is set to Deploy from a branch
5. Set the branch to gh-pages (NOT main)
6. Wait for the "pages-build-deployment" workflow to complete (~45 seconds)
7. Visit https://your-username.github.io in your browser

That's it! Your site is live. You now have a working al-folio website.

---

What's Next?

Once your site is running, explore these customization options:

Add Your Content

• Profile picture: Replace assets/img/prof_pic.jpg with your photo
• About page: Edit _pages/about.md to write your bio
• Publications: Add entries to _bibliography/papers.bib
• Blog posts: Create files in _posts/ with format YYYY-MM-DD-title.md

Customize Appearance

• Theme color: Edit _config.yml, search for theme_color
• Enable/disable sections: In _config.yml, look for enabled: false/true options
• Social media links: Edit _data/socials.yml

Learn More

• Installation and local setup options: INSTALL.md
• Full customization guide: CUSTOMIZE.md
• Frequently asked questions: FAQ.md
• Troubleshooting: TROUBLESHOOTING.md

Get Help from AI

Use the GitHub Copilot Customization Agent (if you have Copilot) to:

• Get step-by-step help with customizations
• Understand how to modify specific features
• Apply changes directly to your site

See CUSTOMIZE.md § GitHub Copilot Customization Agent for details.

---

Common first steps:

• Change the theme color in _config.yml
• Add your social media links in _data/socials.yml
• Upload your profile picture to assets/img/prof_pic.jpg
• Write a short bio in _pages/about.md

Happy customizing! 🎉