Improve readme, add site-wide CSP (#3485 )

This pull request significantly expands and clarifies the documentation
for the al-folio Jekyll theme, focusing on improved file structure
explanations, enhanced quick reference guides, and the addition of a
comprehensive analytics setup guide. The changes make it easier for
users and contributors to understand the project organization, available
features, and configuration options, especially regarding CV formats,
teaching pages, and analytics integration.

**Key documentation and structure improvements:**

*Expanded file and collection structure:*
- The file structure documentation in
`.github/agents/customize.agent.md` and `.github/agents/docs.agent.md`
now details all major directories, including new and existing
collections such as `_books/`, `_teachings/`, `_scripts/`, `_plugins/`,
and expanded `assets/` subdirectories. It also covers new configuration
and utility files, making it easier for users to locate and understand
the purpose of each file or folder.
[[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L24-R66)
[[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L17-R58)

*Documentation and quick reference enhancements:*
- The quick reference table in `.github/agents/customize.agent.md` has
been updated to include new actions like adding teaching pages, setting
up analytics, improving SEO, and ensuring accessibility, with more
precise documentation links.
- The documentation map now lists all major guides (e.g.,
`QUICKSTART.md`, `INSTALL.md`, `TROUBLESHOOTING.md`, `ACCESSIBILITY.md`,
`ANALYTICS.md`, `SEO.md`), providing a clearer overview of available
resources.
[[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L58-R110)
[[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L17-R58)

**Feature and configuration documentation updates:**

*CV/resume format guidance:*
- The CV documentation now clarifies that users can maintain both
RenderCV and JSONResume formats simultaneously, with clear instructions
on switching between them and deleting unused files if desired.
[[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L139-R185)
[[2]](diffhunk://#diff-52f2a9488bfe4177d1f1d01120859dad0b3e2d087283ded68f72d47b4f183391L291-R291)

*Teaching pages and new collections:*
- Adds documentation for the new `_teachings/` collection, including
required frontmatter and support for course materials, as well as
updates to enable/disable teaching and books pages via `_config.yml`.
[[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L180-R252)
[[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L24-R66)

*Analytics integration:*
- Introduces a new `ANALYTICS.md` guide with detailed setup instructions
for Google Analytics, privacy-friendly alternatives (Plausible, Pirsch,
Openpanel, GoAccess), GDPR considerations, and a comparison table to
help users choose the right analytics provider.
- The configuration documentation now references analytics setup and
related configuration options.
[[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L180-R252)
[[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L479-R550)

These updates collectively make the documentation more comprehensive,
actionable, and user-friendly for both new and advanced users.

**References:**
[[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L24-R66)
[[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L58-R110)
[[3]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L139-R185)
[[4]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L180-R252)
[[5]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L479-R550)
[[6]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L17-R58)
[[7]](diffhunk://#diff-0967e840631a541bb95e057e1c6d4884274cf56d5a217d7fee2eb7223b6b4c0dR1-R268)
[[8]](diffhunk://#diff-52f2a9488bfe4177d1f1d01120859dad0b3e2d087283ded68f72d47b4f183391L291-R291)

---------

Signed-off-by: George Araújo <george.gcac@gmail.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

2026-01-28 21:22:27 -03:00

3.3 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.

Quick Start Guide

Step 1: Create Your Repository (1 min)

Click Use this template on the al-folio repository page
Name your repository:
- Personal/Organization site: username.github.io (replace username with your GitHub username)
- Project site: Any name (e.g., my-research-website)
Click Create repository from template

Video Tutorial: Watch a walkthrough of these steps here

Step 2: Configure Deployment (1 min)

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

Step 3: Personalize (2 min)

Open _config.yml in your repository

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

Click Commit changes (at the bottom of the page)

Step 4: View Your Site (1 min)

Go to your repository → Actions tab
Wait for the "Deploy site" workflow to complete (~4 minutes, look for a green checkmark)
Go to Settings → Pages → set Source to gh-pages branch
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

Full customization guide: CUSTOMIZE.md
Troubleshooting: TROUBLESHOOTING.md
Installation options: INSTALL.md
Frequently asked questions: FAQ.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! 🎉

3.3 KiB Raw Blame History