25b758805c
This pull request introduces several documentation improvements and adds comprehensive Copilot and agent instruction files to the al-folio repository. The most significant changes are the addition of repository-wide and path-specific Copilot instructions, updates to agent documentation to reference these instructions, and improvements to the documentation structure and clarity regarding file purposes and workflows. **Copilot and Agent Instruction Enhancements:** - Added a new `.github/copilot-instructions.md` file providing detailed, repository-wide setup, build, CI/CD, troubleshooting, and file format guidance for Copilot coding agents. - Introduced `.github/instructions/bibtex-bibliography.instructions.md` with specific instructions for editing and validating BibTeX files, including custom keywords, formatting rules, and integration with Jekyll-Scholar. - Updated agent documentation files (`customize.agent.md`, `docs.agent.md`) to reference the new Copilot instruction files and explain their purpose and usage for both repository-wide and path-specific scenarios. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L107-R122) [[3]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51) [[4]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137) **Documentation Structure and Clarity Improvements:** - Clarified and reorganized the documentation file list in agent files, removing references to deprecated or merged files (e.g., `MAINTENANCE.md`, `ACCESSIBILITY.md`) and updating descriptions to reflect current usage. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L21-R21) [[3]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137) - Enhanced documentation on the purpose and application of each documentation file, and added detailed explanations of Copilot instruction files and their role in project development. **Workflow and Validation Updates:** - Updated references and descriptions for GitHub Actions workflows in agent documentation to include the Copilot environment setup and clarify pre-commit and CI/CD requirements. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51) - Corrected references for accessibility guidance, now directing users to `TROUBLESHOOTING.md` instead of the removed `ACCESSIBILITY.md`. These changes collectively improve the onboarding experience for both human contributors and AI agents, ensuring consistent adherence to project conventions and reducing errors. **References:** [[1]](diffhunk://#diff-227c2c26cb2ee0ce0f46a320fc48fbcbdf21801a57f59161b1d0861e8aad55f5R1-R253) [[2]](diffhunk://#diff-6fd2827fb8d9c2dd6dc973572201853487ecbbd1120b00425d4f1c21dfdcf35fR1-R174) [[3]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[4]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L107-R122) [[5]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L550-R562) [[6]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L21-R21) [[7]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51) [[8]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137) --------- Signed-off-by: George Araújo <george.gcac@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
108 lines
3.7 KiB
Markdown
108 lines
3.7 KiB
Markdown
# 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](assets/video/tutorial_al_folio.mp4)
|
|
|
|
<!--ts-->
|
|
|
|
- [Quick Start Guide](#quick-start-guide)
|
|
- [Step 1: Create Your Repository (1 min)](#step-1-create-your-repository-1-min)
|
|
- [Step 2: Configure Deployment (1 min)](#step-2-configure-deployment-1-min)
|
|
- [Step 3: Personalize (2 min)](#step-3-personalize-2-min)
|
|
- [Step 4: View Your Site (1 min)](#step-4-view-your-site-1-min)
|
|
- [What's Next?](#whats-next)
|
|
- [Add Your Content](#add-your-content)
|
|
- [Customize Appearance](#customize-appearance)
|
|
- [Learn More](#learn-more)
|
|
- [Get Help from AI](#get-help-from-ai)
|
|
|
|
<!--te-->
|
|
|
|
## Step 1: Create Your Repository (1 min)
|
|
|
|
1. Click **[Use this template](https://github.com/new?template_name=al-folio&template_owner=alshedivat)** on the al-folio repository page
|
|
2. Name your repository:
|
|
- **Personal/Organization site:** `username.github.io` (replace `username` with your GitHub username)
|
|
- **Project site:** Any name (e.g., `my-research-website`)
|
|
3. Click **Create repository from template**
|
|
|
|
## 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:
|
|
```yaml
|
|
title: My Website
|
|
first_name: Your
|
|
last_name: Name
|
|
email: your.email@example.com
|
|
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](INSTALL.md)
|
|
- Full customization guide: [CUSTOMIZE.md](CUSTOMIZE.md)
|
|
- Frequently asked questions: [FAQ.md](FAQ.md)
|
|
- Troubleshooting: [TROUBLESHOOTING.md](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](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! 🎉
|