florent/pages
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity
25b758805c
pages/QUICKSTART.md
George 25b758805c
Added copilot instructions, AGENTS.md, improved README files (#3486) 
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>
2026-01-28 22:55:05 -03:00

3.7 KiB
Raw Blame History

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

Step 1: Create Your Repository (1 min)

  1. Click Use this template 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: 
    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

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! 🎉