florent/pages
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

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

Browse Source 
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>
This commit is contained in:
George 2026-01-28 21:22:27 -03:00 committed by GitHub
parent 1e657e9a4b
commit cc6284d18f
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
22 changed files with 2892 additions and 188 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
.all-contributorsrc
View File

@ -15,14 +15,14 @@
"login": "alshedivat",
"name": "Maruan",
"avatar_url": "https://avatars.githubusercontent.com/u/2126561?v=4",
"profile": "http://maruan.alshedivat.com",
"profile": "https://maruan.alshedivat.com",
"contributions": ["design", "code"]
},
{
"login": "rohandebsarkar",
"name": "Rohan Deb Sarkar",
"avatar_url": "https://avatars.githubusercontent.com/u/50144004?v=4",
"profile": "http://rohandebsarkar.github.io",
"profile": "https://rohandebsarkar.github.io",
"contributions": ["code"]
},
{

111
.github/agents/customize.agent.md vendored
View File

@ -21,17 +21,49 @@ You are an expert customization assistant for the al-folio Jekyll academic websi
- **Deployment:** GitHub Pages (automated via GitHub Actions)
- **File Structure:**
- `_config.yml` – Main site configuration (URL, metadata, theme colors, enabled features)
- `_data/` – YAML data files (CV info in RenderCV format, social links, repository links, coauthors)
- `_pages/` – Site pages (About, Blog, Projects, Publications, CV, etc.)
- `_data/` – YAML data files:
- `cv.yml` – CV/resume in RenderCV format
- `socials.yml` – Social media links and configuration
- `repositories.yml` – GitHub repositories to display
- `coauthors.yml` – Coauthor information and links
- `venues.yml` – Publication venue abbreviations
- `citations.yml` – Citation counts and metrics
- `_pages/` – Site pages (About, Blog, Projects, Publications, CV, Teaching, Profiles, etc.)
- `_posts/` – Blog posts in Markdown (format: `YYYY-MM-DD-title.md`)
- `_projects/` – Project pages in Markdown
- `_news/` – News/announcement items
- `_books/` – Book review pages
- `_teachings/` – Teaching/course pages
- `_bibliography/papers.bib` – Publications in BibTeX format
- `_sass/` – SCSS/SASS stylesheets (colors, themes, layout)
- `assets/` – Static assets (images, PDFs, custom CSS/JS)
- `assets/json/resume.json` – JSONResume format (synced with `_data/cv.yml`)
- `_scripts/` – Helper scripts for development and utilities
- `_plugins/` – Custom Jekyll plugins for extended functionality
- `_includes/` – Liquid template components:
- `_includes/cv/` – Unified CV component renderers (awards, education, experience, skills, languages, certificates, references, projects, interests, etc.)
- `_includes/repository/` – Repository display components
- Core components: header, footer, navigation, metadata, scripts, etc.
- `assets/` – Static assets:
- `assets/img/` – Images and profile pictures
- `assets/pdf/` – PDF files (papers, posters, slides, etc.)
- `assets/json/` – JSON files (resume.json in JSONResume format, table_data.json)
- `assets/rendercv/` – RenderCV configuration and generated PDFs
- `.github/workflows/` – GitHub Actions for deployment and CI/CD (includes CV PDF generation)
- `assets/css/`, `assets/js/` – Custom stylesheets and scripts
- `assets/bibliography/` – BibTeX-related assets
- `assets/fonts/`, `assets/webfonts/` – Font files
- `assets/libs/` – Third-party JavaScript libraries
- `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content
- `.devcontainer/` – Development container configuration for VS Code
- `.github/` – GitHub-specific configuration:
- `.github/workflows/` – GitHub Actions for deployment, CI/CD, CV PDF generation, link checking, code quality
- `.github/agents/` – AI agent configuration files
- `.github/ISSUE_TEMPLATE/` – GitHub issue templates
- `.pre-commit-config.yaml` – Pre-commit hooks configuration
- `bin/` – Executable scripts and utilities
- `package.json`, `purgecss.config.js` – Node.js dependencies and build tools
- `Gemfile`, `Gemfile.lock`, `.ruby-version` – Ruby dependencies and version
- Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `MAINTENANCE.md`, `QUICKSTART.md`, `ACCESSIBILITY.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md`
- `robots.txt` – SEO and crawler configuration
- `Dockerfile`, `docker-compose.yml`, `docker-compose-slim.yml` – Docker configuration
## Community Context & Issue/Discussion References
@ -55,17 +87,27 @@ Users may reference community discussions, issues, or past questions from the **
You have access to the complete documentation for al-folio:
1. **README.md** – Overview, features, community examples, installation basics
2. **CUSTOMIZE.md** – Comprehensive customization guide covering:
2. **QUICKSTART.md** – Quick start guide for getting up and running
3. **INSTALL.md** – Installation, deployment, and Docker setup instructions
4. **CUSTOMIZE.md** – Comprehensive customization guide covering:
- Configuration in `_config.yml`
- CV information (JSON/YAML formats)
- Creating pages, blog posts, projects, news items
- CV information (RenderCV and JSONResume formats)
- Creating pages, blog posts, projects, news items, and teaching pages
- Publications and BibTeX management
- Theme colors and styling
- Social media setup
- Search and analytics configuration
- Removing unwanted content
- Font and spacing customization
3. **INSTALL.md** – Installation and deployment instructions
4. **FAQ.md** – Common issues and solutions
- Newsletter setup
- Google Calendar integration
5. **FAQ.md** – Frequently asked questions and common solutions
6. **TROUBLESHOOTING.md** – Troubleshooting guide for common issues
7. **CONTRIBUTING.md** – Guidelines for contributing to the project
8. **MAINTENANCE.md** – Maintenance notes for maintainers
9. **ACCESSIBILITY.md** – Accessibility standards and features
10. **ANALYTICS.md** – Analytics and tracking configuration
11. **SEO.md** – Search engine optimization guide
## Commands You Can Use
@ -136,12 +178,11 @@ npx prettier . --write
**Files:** `_data/cv.yml` (RenderCV format), `assets/json/resume.json` (JSONResume format), `assets/rendercv/` (configuration)
- **Choose your format:** Users select either RenderCV (`_data/cv.yml`) or JSONResume (`assets/json/resume.json`) — they pick ONE format
- **Delete the unused format:** Remove the file for the format you're not using (so only one source exists) if you want to avoid confusion
- **RenderCV features:** Automatic PDF generation via GitHub Actions, customizable styling via `assets/rendercv/` config files (`design.yaml`, `locale.yaml`, `settings.yaml`)
- **JSONResume features:** Standard format compatible with other tools and services
- **Switching formats:** Users can change which format displays on the CV page by editing the `cv_format` setting in `_pages/cv.md` frontmatter
- **Note about both files:** Both files exist in the repository for template flexibility, but users usually only maintain the one they choose
- **Choose your format:** Users can maintain either RenderCV (`_data/cv.yml`) or JSONResume (`assets/json/resume.json`), or both simultaneously
- **RenderCV (recommended):** Human-readable YAML format with automatic PDF generation via GitHub Actions, customizable styling via `assets/rendercv/` config files (`design.yaml`, `locale.yaml`, `settings.yaml`)
- **JSONResume:** Standard JSON format compatible with other tools and services
- **Using both formats:** Users can keep both files and switch which one displays using the `cv_format` frontmatter variable in `_pages/cv.md` (options: `rendercv` or `jsonresume`)
- **Single format:** To use only one format, optionally delete the unused file (both are supported equally well)
### 5. Publications
@ -177,7 +218,15 @@ npx prettier . --write
- Add inline announcements or news with links
- Automatically displayed on home page
### 9. Theme Colors
### 9. Teaching Pages
**Files:** `_teachings/*.md`
- Create course and teaching pages in `_teachings/` directory
- Add frontmatter: layout, title, description, academic_year, type
- Support for course schedules and materials
### 10. Theme Colors
**Files:** `_sass/_themes.scss`, `_sass/_variables.scss`
@ -185,20 +234,22 @@ npx prettier . --write
- Available theme colors defined in `_sass/_variables.scss`
- Enable/disable dark mode in `_config.yml` (`enable_darkmode`)
### 10. GitHub Repositories Display
### 11. GitHub Repositories Display
**Files:** `_data/repositories.yml`, `_pages/repositories.md`
- Add GitHub usernames and repository names
- Displayed with stats and trophies on repositories page
### 11. Enable/Disable Features
### 12. Enable/Disable Features
**File:** `_config.yml`
- Toggle features: Google Analytics, comments (Giscus), related posts, tooltips, medium zoom
- Enable/disable pages: blog, projects, publications, repositories
- Configure navbar, footer, search functionality
- Toggle features: Google Analytics, comments (Giscus), related posts, tooltips, medium zoom, search
- Enable/disable pages: blog, projects, publications, repositories, teaching, books
- Configure navbar, footer, and navigation
- Configure analytics services (Google Analytics, Cronitor, Pirsch, OpenPanel)
- Configure newsletter and contact options
## Code Style Standards
@ -476,23 +527,27 @@ Help users avoid these frequent errors:
## Quick Reference Map
| User wants to... | Files to modify | Key documentation |
| ----------------------- | ------------------------------------------------------------------- | --------------------------------- |
| ----------------------- | ------------------------------------------------------------------- | ---------------------------------- |
| Change personal info | `_config.yml`, `_pages/about.md` | CUSTOMIZE.md § Configuration |
| Add profile picture | `assets/img/prof_pic.jpg` | CUSTOMIZE.md § About page |
| Update CV | `_data/cv.yml` (RenderCV) or `assets/json/resume.json` (JSONResume) | CUSTOMIZE.md § CV information |
| Add publications | `_bibliography/papers.bib` | CUSTOMIZE.md § Publications |
| Update CV | `_data/cv.yml` (RenderCV) or `assets/json/resume.json` (JSONResume) | CUSTOMIZE.md § Modifying CV |
| Add publications | `_bibliography/papers.bib` | CUSTOMIZE.md § Adding publications |
| Add blog post | `_posts/YYYY-MM-DD-title.md` | CUSTOMIZE.md § Blog posts |
| Create project | `_projects/name.md` | CUSTOMIZE.md § Projects |
| Add news item | `_news/announcement.md` | CUSTOMIZE.md § News |
| Change theme color | `_sass/_themes.scss` | CUSTOMIZE.md § Theme colors |
| Add news item | `_news/announcement.md` | CUSTOMIZE.md § Adding news |
| Add teaching page | `_teachings/course.md` | CUSTOMIZE.md § Teaching collection |
| Change theme color | `_sass/_themes.scss` | CUSTOMIZE.md § Theme color |
| Add social links | `_data/socials.yml` | CUSTOMIZE.md § Social media |
| Set up analytics | `_config.yml` | CUSTOMIZE.md & ANALYTICS.md |
| Enable/disable features | `_config.yml` | CUSTOMIZE.md § Configuration |
| Remove pages | Delete from `_pages/`, update nav | CUSTOMIZE.md § Removing content |
| Fix deployment issues | `_config.yml` (url/baseurl) | FAQ.md, INSTALL.md |
| Test changes locally | Docker setup | INSTALL.md § Docker |
| Debug broken site | Check GitHub Actions, local preview output | FAQ.md, Testing Before Deployment |
| Debug broken site | Check GitHub Actions, local preview output | TROUBLESHOOTING.md, FAQ.md |
| Add custom page | Create `_pages/name.md`, update nav | CUSTOMIZE.md § Creating pages |
| Customize fonts/spacing | `_sass/_variables.scss` | CUSTOMIZE.md § Customization |
| Improve SEO | `_config.yml`, `robots.txt` | SEO.md |
| Ensure accessibility | Check markup, alt text, contrast | ACCESSIBILITY.md |
## Using Community Context in Your Responses

42
.github/agents/docs.agent.md vendored
View File

@ -14,24 +14,48 @@ You are a documentation specialist for the al-folio Jekyll theme project.
## Project knowledge
- **Tech Stack:** Jekyll 4.x (Ruby-based static site generator), Liquid templating, YAML configuration, SCSS/CSS, JavaScript
- **Key Dependencies:** jekyll-scholar, jekyll-archives-v2, jekyll-paginate-v2, MathJax, Bootstrap
- **Tech Stack:** Jekyll 4.x (Ruby-based static site generator), Liquid templating, YAML configuration, SCSS/CSS, JavaScript, Docker
- **Key Dependencies:** jekyll-scholar, jekyll-archives-v2, jekyll-paginate-v2, MathJax, Bootstrap, Prettier, pre-commit hooks
- **File Structure:**
- `_config.yml` – Main Jekyll configuration file
- `*.md` (root) – Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`
- `*.md` (root) – Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `MAINTENANCE.md`, `QUICKSTART.md`, `ACCESSIBILITY.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md`
- `_pages/` – Website pages (Markdown with frontmatter)
- `_posts/` – Blog posts
- `_projects/`, `_news/`, `_books/` – Jekyll collections
- `_layouts/`, `_includes/` – Liquid templates
- `_includes/cv/` – Unified CV component renderers (awards, education, experience, skills, languages, etc.)
- `_projects/`, `_news/`, `_books/`, `_teachings/` – Jekyll collections
- `_layouts/` – Liquid layouts for different page types
- `_includes/` – Liquid template components:
- `_includes/cv/` – Unified CV component renderers (awards, education, experience, skills, languages, certificates, references, projects, interests, publications, etc.)
- `_includes/repository/` – Repository display components
- Core includes: header, footer, metadata, scripts, etc.
- `_sass/` – SCSS stylesheets
- `_data/` – YAML data files:
- `cv.yml` – CV/resume in RenderCV format
- `repositories.yml`, `socials.yml`, `coauthors.yml`, `venues.yml` – Other data
- `socials.yml` – Social media links
- `repositories.yml` – GitHub repositories
- `coauthors.yml` – Coauthor information
- `venues.yml` – Publication venue abbreviations
- `citations.yml` – Citation metrics
- `_plugins/` – Custom Jekyll plugins for extended functionality
- `_bibliography/` – BibTeX files for publications
- `assets/json/resume.json` – JSONResume format (alternative to RenderCV; syncing between formats is a template maintainer task, not a user responsibility)
- `assets/` – Static assets:
- `assets/json/` – JSON files (resume.json in JSONResume format, table_data.json)
- `assets/rendercv/` – RenderCV configuration files and generated PDFs
- `.github/workflows/` – GitHub Actions for deployment, CI, and CV PDF generation
- `assets/img/`, `assets/pdf/` – Images and PDFs
- `assets/css/`, `assets/js/` – Custom stylesheets and scripts
- `assets/fonts/`, `assets/webfonts/` – Font files
- `assets/bibliography/`, `assets/libs/` – Support files
- `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content
- `.github/` – GitHub configuration:
- `.github/workflows/` – GitHub Actions (deployment, CI/CD, CV PDF generation, link checking, code quality)
- `.github/agents/` – AI agent configuration files
- `.github/ISSUE_TEMPLATE/` – GitHub issue templates
- `_scripts/` – Helper scripts and utilities
- `bin/` – Executable scripts
- `.devcontainer/` – Development container configuration
- `.pre-commit-config.yaml` – Pre-commit hooks for code quality
- `Dockerfile`, `docker-compose.yml`, `docker-compose-slim.yml` – Docker configuration
- `Gemfile`, `Gemfile.lock`, `.ruby-version` – Ruby dependencies
- `package.json` – Node.js dependencies
## Documentation standards

401
ACCESSIBILITY.md Normal file
View File

@ -0,0 +1,401 @@
# Accessibility Guide
This guide helps you ensure your al-folio website is accessible to all visitors, including people with disabilities.
<!--ts-->
- [Accessibility Guide](#accessibility-guide)
- [Overview](#overview)
- [Why Accessibility Matters](#why-accessibility-matters)
- [Built-in Accessibility](#built-in-accessibility)
- [Accessibility Checking](#accessibility-checking)
- [Run Automated Tests Locally](#run-automated-tests-locally)
- [Manual Testing](#manual-testing)
- [Common Accessibility Issues & Fixes](#common-accessibility-issues--fixes)
- [Images Missing Alt Text](#images-missing-alt-text)
- [Links Not Descriptive](#links-not-descriptive)
- [Color Contrast Too Low](#color-contrast-too-low)
- [Keyboard Navigation Not Working](#keyboard-navigation-not-working)
- [Missing Form Labels](#missing-form-labels)
- [Heading Hierarchy Broken](#heading-hierarchy-broken)
- [Accessibility Best Practices](#accessibility-best-practices)
- [Writing Content](#writing-content)
- [Images and Media](#images-and-media)
- [Links](#links)
- [Code and Math](#code-and-math)
- [PDFs and Documents](#pdfs-and-documents)
- [Testing Tools](#testing-tools)
- [Resources](#resources)
<!--te-->
## Overview
Accessibility means ensuring your website works for everyone, regardless of ability. This includes:
- **Visual impairments** – Screen reader users, low vision
- **Hearing impairments** – Captions for video, transcripts for audio
- **Motor impairments** – Keyboard navigation, large buttons
- **Cognitive impairments** – Clear language, simple navigation
- **Other** – Slow connections, old devices, non-native speakers
---
## Why Accessibility Matters
1. **Ethical:** Making your research accessible to everyone
2. **Legal:** Some jurisdictions require web accessibility (ADA in US, AODA in Canada, WCAG in EU)
3. **SEO:** Accessible sites rank better in search engines
4. **Usability:** Accessible sites are easier for everyone to use
5. **Academic integrity:** More people can read and build on your research
---
## Built-in Accessibility
al-folio includes several accessibility features out of the box:
- ✅ **Semantic HTML** – Proper heading structure, landmarks
- ✅ **Responsive design** – Works on phones, tablets, desktops
- ✅ **Color contrast** – Meets WCAG AA standards
- ✅ **Keyboard navigation** – Navigate without a mouse
- ✅ **Screen reader support** – Works with NVDA, JAWS, VoiceOver
- ✅ **Dark mode** – Reduces eye strain for some users
- ✅ **Focus indicators** – Clear focus states for keyboard users
---
## Accessibility Checking
### Run Automated Tests Locally
al-folio includes **axe (automated testing)** to check for accessibility issues.
**Using GitHub Actions (easiest):**
1. Push changes to your repository
2. Go to **Actions** tab
3. Look for the **"Axe - a11y tests"** workflow
4. Click on the completed run to see results
5. Expand any failures to see details and fixes
**Running locally:**
```bash
# Check a specific file
axe _pages/about.md
# Or use the GitHub Actions workflow
# Results are posted as a comment on pull requests
```
**Interpreting results:**
- 🔴 **Critical** – Must fix (breaks functionality)
- 🟠 **Serious** – Should fix (impacts many users)
- 🟡 **Moderate** – Nice to fix (affects some users)
- 🔵 **Minor** – Polish (edge cases)
---
### Manual Testing
Automated tools catch ~30% of issues. Manual testing catches the rest.
**Test keyboard navigation:**
1. Hide your mouse/trackpad
2. Use **Tab** to navigate through all interactive elements
3. Use **Enter** or **Space** to activate buttons/links
4. Use arrow keys for dropdown menus
5. Ensure you can access all features
**Test with a screen reader:**
**Windows:**
- Use built-in **Narrator**: `Windows + Ctrl + N`
**Mac:**
- Use built-in **VoiceOver**: `Cmd + F5`
**Linux:**
- Use **NVDA** (free download): https://www.nvaccess.org/
**Checklist:**
- [ ] All page content is readable
- [ ] Links are descriptive (screen reader reads link text)
- [ ] Images have alt text
- [ ] Headings make sense when read aloud
- [ ] Form fields have labels
**Test color contrast:**
- Use [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
- Ensure text is readable (especially on custom theme colors)
- Minimum contrast ratio: 4.5:1 for normal text, 3:1 for large text
---
## Common Accessibility Issues & Fixes
### Images Missing Alt Text
**Problem:** Images have no description for screen reader users.
**Fix in Markdown:**
```markdown
# Bad ❌
![](assets/img/my-photo.jpg)
# Good ✅
![A group of researchers presenting at a conference](assets/img/my-photo.jpg)
```
**Fix in BibTeX:**
```bibtex
# Add descriptions for paper thumbnails
@article{mykey,
# ... other fields ...
alt={Diagram showing the three-layer neural network architecture}
}
```
**Good alt text:**
- Describes the content and purpose
- About 125 characters max
- Doesn't say "image of" (screen readers already say that)
- For charts: describe the data, not just "chart"
**Examples:**
```markdown
❌ "Photo"
✅ "Alice Chen presenting her research on climate modeling"
❌ "Graph of results"
✅ "Bar chart showing publication counts by year from 2015 to 2024"
❌ "Logo"
✅ "University of Example logo"
```
---
### Links Not Descriptive
**Problem:** Links like "click here" don't make sense to screen reader users.
**Fix:**
```markdown
# Bad ❌
See my paper [here](assets/pdf/paper.pdf).
# Good ✅
Read my [analysis of climate policy](assets/pdf/paper.pdf).
```
**Why this matters:** Screen reader users often skip through links quickly. Links must be meaningful out of context.
---
### Color Contrast Too Low
**Problem:** Text is hard to read against background color.
**Fix:**
1. Use the [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
2. Enter your text color and background color
3. Ensure ratio is at least **4.5:1** (normal text) or **3:1** (large text)
4. Adjust colors in `_config.yml` or `_sass/_themes.scss`
**al-folio default colors meet WCAG AA standards**, so this is usually only an issue if you customize colors heavily.
---
### Keyboard Navigation Not Working
**Problem:** Some buttons or links can't be accessed with keyboard.
**Fix:**
- Ensure all interactive elements use semantic HTML: `<button>`, `<a>`, `<input>`
- Don't use `<div>` or `<span>` as buttons
- JavaScript-powered buttons need `tabindex="0"` and keyboard handlers
**Example (bad):**
```html
<!-- ❌ Not keyboard accessible -->
<div onclick="doSomething()">Click me</div>
```
**Example (good):**
```html
<!-- ✅ Keyboard accessible -->
<button onclick="doSomething()">Click me</button>
```
---
### Missing Form Labels
**Problem:** Form fields (search, contact forms) don't have associated labels.
**Fix in HTML/Liquid:**
```html
<!-- ❌ No label -->
<input type="text" placeholder="Search..." />
<!-- ✅ Proper label -->
<label for="search">Search publications:</label>
<input id="search" type="text" placeholder="Search..." />
```
---
### Heading Hierarchy Broken
**Problem:** Headings skip levels (H1 → H3, missing H2) confusing screen reader users.
**Fix:**
```markdown
# ✅ Correct hierarchy
# Main Title (H1)
## Section 1 (H2)
### Subsection (H3)
## Section 2 (H2)
# ❌ Broken hierarchy
# Main Title (H1)
### Subsection (H3) — should be H2!
## Section 2 (H2)
```
**Rule:** Always use sequential heading levels; don't skip.
---
## Accessibility Best Practices
### Writing Content
- **Use clear language** – Short sentences, common words
- **Avoid jargon** – Explain technical terms
- **Use lists** – Easier to scan than paragraphs
- **Short paragraphs** – 3-4 lines max
- **Descriptive headings** – Say what the section is about
### Images and Media
- **Alt text for images** – Describe the content
- **Captions for videos** – Include transcript too
- **Audio transcripts** – Full text of spoken content
- **Color alone is not enough** – Use patterns, labels too
### Links
- **Descriptive link text** – Don't use "click here"
- **Visible focus states** – Already in al-folio by default
- **External links** – Indicate they open in new window
- **Avoid misleading links** – Don't link email addresses to mailto (confuses readers)
### Code and Math
**Code blocks:**
````markdown
# ✅ Good: Language specified for syntax highlighting
```python
def hello():
print("Hello world")
```
````
````
**Math equations:**
```markdown
# ✅ Include alt text for complex equations
The equation $E = mc^2$ (energy equals mass times light speed squared)
represents mass-energy equivalence.
````
### PDFs and Documents
- **Accessible PDFs** – Use proper headings, alt text in PDF itself
- **Link to PDF content** – Offer plain text or HTML version too
- **Avoid scanned images as PDFs** – Use OCR to make text selectable
---
## Testing Tools
| Tool | Purpose | Cost | Type |
| --------------------------- | ---------------------------------- | ---- | -------------------------- |
| **axe DevTools** | Automated accessibility testing | Free | Browser extension |
| **WAVE** | Identify accessibility errors | Free | Browser extension |
| **NVDA** | Screen reader testing | Free | Windows screen reader |
| **VoiceOver** | Screen reader testing | Free | Mac screen reader |
| **WebAIM Contrast Checker** | Color contrast validation | Free | Web tool |
| **Lighthouse** | Performance & accessibility audits | Free | Built into Chrome DevTools |
| **JAWS** | Premium screen reader (testing) | Paid | Windows screen reader |
---
## Resources
- **[WCAG 2.1 Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)** – Official web accessibility standards
- **[WebAIM](https://webaim.org/)** – Practical accessibility guides
- **[A11y Project](https://www.a11yproject.com/)** – Community accessibility resource
- **[MDN Accessibility Docs](https://developer.mozilla.org/en-US/docs/Web/Accessibility)** – Technical reference
- **[Inclusive Components](https://inclusive-components.design/)** – Design patterns for accessibility
---
## Quick Checklist
Before publishing content, ensure:
- [ ] All images have alt text
- [ ] All links are descriptive
- [ ] Heading hierarchy is correct (no skipping levels)
- [ ] Color contrast is sufficient (test with contrast checker)
- [ ] Navigation works with keyboard only
- [ ] No autoplay video/audio
- [ ] Forms have proper labels
- [ ] Your site passes axe accessibility tests
---
## Need Help?
- **GitHub Copilot Customization Agent** – Ask for help making specific changes accessible
- **[GitHub Discussions](https://github.com/alshedivat/al-folio/discussions)** – Ask the community
- **[WebAIM](https://webaim.org/)** – Detailed guidance on accessibility techniques
---
**Remember:** Accessibility is an ongoing process, not a one-time task. Test regularly, fix issues as you find them, and keep your content accessible as you update it.

268
ANALYTICS.md Normal file
View File

@ -0,0 +1,268 @@
# Analytics Setup Guide
This guide helps you add website analytics to track visitor statistics and behavior.
<!--ts-->
- [Analytics Setup Guide](#analytics-setup-guide)
- [Overview](#overview)
- [Google Analytics](#google-analytics)
- [Setup Steps](#setup-steps)
- [Configuration](#configuration)
- [Privacy-Friendly Alternatives](#privacy-friendly-alternatives)
- [Plausible Analytics](#plausible-analytics)
- [GoAccess (Self-hosted)](#goaccess-self-hosted)
- [Pirsch Analytics](#pirsch-analytics)
- [Openpanel Analytics](#openpanel-analytics)
- [Other Analytics Services](#other-analytics-services)
- [Cronitor](#cronitor)
- [GDPR and Privacy Considerations](#gdpr-and-privacy-considerations)
- [Comparing Analytics Services](#comparing-analytics-services)
<!--te-->
## Overview
Analytics help you understand your website visitors: where they come from, which pages they visit, and how they interact with your content. al-folio supports multiple analytics providers.
**Available analytics in al-folio:**
- **Google Analytics** (free, feature-rich, but privacy concerns)
- **Plausible Analytics** (paid, privacy-first, GDPR-compliant)
- **Pirsch Analytics** (freemium, GDPR-compliant, European servers)
- **Openpanel Analytics** (open-source, self-hosted option)
- **Cronitor** (uptime monitoring + RUM analytics)
---
## Google Analytics
Google Analytics is free and widely used. It provides detailed insights into visitor behavior but collects more user data.
### Setup Steps
1. **Create a Google Analytics account:**
- Visit [Google Analytics](https://analytics.google.com)
- Sign in with your Google account
- Click **Start measuring** → **Create account**
2. **Create a property for your website:**
- Enter your website name and URL
- Accept terms and continue
- Choose your timezone and currency
3. **Get your Measurement ID:**
- In the left sidebar, go to **Admin** → **Properties**
- Click **Data Streams** → **Web** (or your existing stream)
- Copy the **Measurement ID** (format: `G-XXXXXXXXXX`)
4. **Add to your site:**
- Open `_config.yml` in your repository
- Find the `google_analytics:` line and add your ID:
```yaml
google_analytics: G-XXXXXXXXXX
```
- Commit and push
- Wait for deployment to complete
5. **Verify it's working:**
- Visit your website
- Go back to Google Analytics → **Real-time** tab
- You should see your visit appear within a few seconds
### Configuration
Google Analytics is auto-injected into your site once you set `google_analytics` in `_config.yml`. No additional code needed.
**Note:** Google Analytics takes 24-48 hours to start showing data trends.
---
## Privacy-Friendly Alternatives
If you're concerned about user privacy or GDPR compliance, consider these alternatives:
### Plausible Analytics
**Best for:** Privacy-conscious academics and researchers
**Features:**
- ✅ GDPR and privacy laws compliant
- ✅ No cookie consent banner needed
- ✅ Clear, simple dashboard
- ✅ Email reports
- ❌ Paid service ($9-20/month)
**Setup:**
1. Create an account at [Plausible.io](https://plausible.io)
2. Add your domain
3. Add this script to your site's `<head>` tag
4. Plausible provides installation instructions for Jekyll
**For al-folio:**
- Edit `_includes/head.liquid`
- Add the Plausible script before the closing `</head>` tag (around line 185)
- Or use a custom analytics integration (see below)
---
### GoAccess (Self-hosted)
**Best for:** Cost-conscious users with access to server logs
**Features:**
- ✅ Completely free
- ✅ No privacy concerns (analyze your own logs)
- ✅ Self-hosted
- ❌ Requires server/GitHub Pages access
- ❌ Less user-friendly than cloud services
**How it works:**
- Analyzes your web server access logs
- Generates HTML dashboard
- Run locally on your machine
- Script available in `_scripts/` directory
**See also:** [GoAccess documentation](https://goaccess.io/)
---
### Pirsch Analytics
**Best for:** GDPR-compliant analytics without complex setup
**Features:**
- ✅ GDPR compliant
- ✅ European servers
- ✅ Free tier available
- ✅ Simple integration
- ✅ No cookie consent needed
**Setup:**
1. Sign up at [Pirsch.io](https://pirsch.io)
2. Add your domain
3. Copy the tracking code
4. In `_config.yml`, add:
```yaml
pirsch_analytics: YOUR_SITE_ID # Format: 32 characters
```
5. Commit and push
(The site ID appears in your Pirsch dashboard.)
---
### Openpanel Analytics
**Best for:** Open-source and privacy-conscious developers
**Features:**
- ✅ Open-source
- ✅ Self-hosted option available
- ✅ Privacy-focused
- ✅ Modern dashboard
- ❌ Younger project (fewer features)
**Setup:**
1. Sign up at [Openpanel.dev](https://openpanel.dev)
2. Create a project for your website
3. Get your **Client ID**
4. In `_config.yml`, add:
```yaml
openpanel_analytics: YOUR_CLIENT_ID # Format: UUID
```
5. Commit and push
---
## Other Analytics Services
### Cronitor
Cronitor is an **uptime monitoring** service with RUM (Real User Monitoring) analytics.
**Best for:** Tracking if your site is online + basic performance metrics
**Setup:**
1. Create account at [Cronitor.io](https://cronitor.io)
2. Get your **Site ID**
3. In `_config.yml`, add:
```yaml
cronitor_analytics: YOUR_SITE_ID
```
4. Commit and push
---
## GDPR and Privacy Considerations
If you're in the European Union or serve EU visitors, consider GDPR requirements:
### GDPR Checklist
- [ ] If using Google Analytics: Add cookie consent banner
- [ ] Display a privacy policy explaining what analytics you use
- [ ] Allow users to opt-out if using tracking cookies
- [ ] Use privacy-first alternatives when possible
### Privacy-first services (No GDPR cookie banner needed)
- ✅ Plausible Analytics
- ✅ Pirsch Analytics
- ✅ Openpanel Analytics
- ✅ GoAccess
### Services requiring cookie consent
- ❌ Google Analytics (EU users must consent first)
### Simple Privacy Policy Template
Add a privacy policy page at `_pages/privacy.md`:
```markdown
---
layout: page
title: Privacy Policy
permalink: /privacy/
---
## Analytics
This website uses [Service Name] to understand visitor behavior. [Service Name] is GDPR-compliant and does not use cookies.
For more information, see [Service Name's privacy policy](link-to-privacy-policy).
```
---
## Comparing Analytics Services
| Service | Free | GDPR | Setup | Features | Best for |
| -------------------- | ------------ | ------------------- | ------ | ---------------- | --------------- |
| **Google Analytics** | ✅ | ⚠️ Requires consent | Easy | Detailed reports | Large sites |
| **Plausible** | ❌ | ✅ | Easy | Simple, clear | Privacy-focused |
| **Pirsch** | ✅ Free tier | ✅ | Easy | Balanced | GDPR compliance |
| **Openpanel** | ✅ | ✅ | Medium | Modern dashboard | Developers |
| **Cronitor** | Paid | ✅ | Easy | Uptime + RUM | Monitoring |
| **GoAccess** | ✅ | ✅ | Hard | Self-hosted logs | Cost-conscious |
---
## Next Steps
1. **Choose a service** based on your needs (privacy, features, budget)
2. **Follow the setup guide** for your chosen service
3. **Verify it's working** by visiting your site and checking the analytics dashboard
4. **(Optional) Add a privacy policy** to your website
For more customization help, see [CUSTOMIZE.md](CUSTOMIZE.md) or use the **GitHub Copilot Customization Agent**.

12
CUSTOMIZE.md
View File

@ -288,7 +288,7 @@ Understanding how these technologies work together will help you customize al-fo
## Modifying the CV information
Your CV can be created using one of two formats. Choose the format that works best for you:
Your CV can be created using one of two formats. Choose the format that works best for you, or use both simultaneously by switching between them:
### RenderCV Format (Recommended)
@ -297,11 +297,11 @@ Your CV can be created using one of two formats. Choose the format that works be
**If you choose this format:**
1. Edit your CV data in [`_data/cv.yml`](_data/cv.yml)
2. Delete [`assets/json/resume.json`](assets/json/resume.json) so the website uses the YAML file
3. (Optional) Customize how the PDF is styled by editing:
2. Optionally customize how the PDF is styled by editing:
- [`assets/rendercv/design.yaml`](assets/rendercv/design.yaml) — Design and styling
- [`assets/rendercv/locale.yaml`](assets/rendercv/locale.yaml) — Localization and formatting
- [`assets/rendercv/settings.yaml`](assets/rendercv/settings.yaml) — RenderCV settings
3. To display only this format, delete [`assets/json/resume.json`](assets/json/resume.json) (optional)
### JSONResume Format
@ -310,11 +310,11 @@ Your CV can be created using one of two formats. Choose the format that works be
**If you choose this format:**
1. Edit your CV data in [`assets/json/resume.json`](assets/json/resume.json)
2. Delete [`_data/cv.yml`](_data/cv.yml) so the website uses the JSON file
2. To display only this format, delete [`_data/cv.yml`](_data/cv.yml) (optional)
### Switching CV Sources (Without Deleting Files)
### Using Both Formats Simultaneously
If you keep both CV files in your repository, you can switch which format displays on your website by setting the `cv_format` variable in the frontmatter of [`_pages/cv.md`](_pages/cv.md):
You can keep both [`_data/cv.yml`](_data/cv.yml) and [`assets/json/resume.json`](assets/json/resume.json) in your repository and switch between them on your website by setting the `cv_format` frontmatter variable in [`_pages/cv.md`](_pages/cv.md):
```yaml
---

47
INSTALL.md
View File

@ -27,21 +27,29 @@
## Recommended Approach
The recommended approach for using **al-folio** is to first create your own site using the template with as few changes as possible, and only when it is up and running customize it however you like. This way it is easier to pinpoint what causes a potential issue in case of a bug. The minimum steps required to create your own site are ([video tutorial here](assets/video/tutorial_al_folio.mp4)):
The recommended approach for using **al-folio** is to first create your own site using the template with as few changes as possible, and only when it is up and running customize it however you like. This way it is easier to pinpoint what causes a potential issue in case of a bug.
1. Create a new repository using this template. For this, click on [Use this template -> Create a new repository](https://github.com/new?template_name=al-folio&template_owner=alshedivat) above the file list. If you plan to upload your site to `<your-github-username>.github.io`, note that the name of your repository :warning: **MUST BE** :warning: `<your-github-username>.github.io` or `<your-github-orgname>.github.io`, as stated in the [GitHub pages docs](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites).
2. In this new repository, go to [Settings -> Actions -> General -> Workflow permissions](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/enabling-features-for-your-repository/managing-github-actions-settings-for-a-repository#configuring-the-default-github_token-permissions) and give `Read and write permissions` to GitHub Actions.
3. Open file `_config.yml`, set `url` to `https://<your-github-username>.github.io` and leave `baseurl` **empty** (do NOT delete it), as `baseurl:`.
4. Wait until the GitHub action with subtitle `Deploy site` finishes (check your repository **Actions** tab), which takes ~4 min. Now, in addition to the `main` branch, your repository has a newly built `gh-pages` branch.
5. Finally, in the repository page go to `Settings -> Pages -> Build and deployment`, make sure that `Source` is set to `Deploy from a branch` and set the branch to `gh-pages` (NOT to main).
6. Wait until the GitHub action `pages-build-deployment` finishes (check your repository **Actions** tab), which takes ~45s, then simply navigate to `https://<your-github-username>.github.io` in your browser. At this point you should see a copy of the theme's [demo website](https://alshedivat.github.io/al-folio/).
After everything is set up, you can download the repository to your machine and start customizing it. To do so, run the following commands:
**For the quickest setup**, follow the [Quick Start Guide](QUICKSTART.md), which will have you up and running in 5 minutes.
### Important Notes for GitHub Pages Sites
If you plan to upload your site to `<your-github-username>.github.io`, the repository name :warning: **MUST BE** :warning: `<your-github-username>.github.io` or `<your-github-orgname>.github.io`, as stated in the [GitHub pages docs](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#types-of-github-pages-sites).
When configuring `_config.yml`, set `url` to `https://<your-github-username>.github.io` and leave `baseurl` **empty** (do NOT delete it), setting it as `baseurl:`.
### Automatic Deployment
Starting version [v0.3.5](https://github.com/alshedivat/al-folio/releases/tag/v0.3.5), **al-folio** will automatically re-deploy your webpage each time you push new changes to your repository! :sparkles:
### Local Development
Once everything is deployed, you can download the repository to your machine and start customizing it locally:
```bash
$ git clone git@github.com:<your-username>/<your-repo-name>.git
```
Starting version [v0.3.5](https://github.com/alshedivat/al-folio/releases/tag/v0.3.5), **al-folio** will automatically re-deploy your webpage each time you push new changes to your repository! :sparkles:
See [Local setup using Docker](#local-setup-using-docker-recommended) or other sections below for local development options.
## Local setup on Windows
@ -238,30 +246,15 @@ In its default configuration, al-folio will copy the top-level `README.md` to th
## Maintaining Dependencies
**al-folio** uses **Bundler** (a Ruby dependency manager) to keep track of all the Ruby packages (called "gems") needed to run Jekyll and its plugins. Over time, these packages may receive updates that include bug fixes, security patches, and new features.
**al-folio** uses **Bundler** (a Ruby dependency manager) to keep track of Ruby packages (called "gems") needed to run Jekyll and its plugins. For detailed information about dependency management, updating safely, testing, and handling breaking changes, see [MAINTENANCE.md § Dependency Management](MAINTENANCE.md#dependency-management).
### Updating the bundler itself
The bundler tool itself should be kept up to date. To update bundler to the latest version, run:
```bash
$ bundle update --bundler
```
### Updating all dependencies
To update all Ruby gems to their latest compatible versions (as specified in your `Gemfile`), run:
**Quick reference:**
```bash
$ bundle update --all
```
After updating dependencies, test your site locally to ensure everything still works correctly:
- If using Docker: `docker compose up`
- If using local setup: `bundle exec jekyll serve`
> **Note:** Dependency updates may occasionally introduce breaking changes. If your site fails after updating, check the [FAQ](FAQ.md) for troubleshooting, or revert to the previous version with `bundle lock --add-platform ruby` and `git checkout Gemfile.lock`.
After updating, test locally to ensure everything still works. If your site fails after updating, check the [FAQ](FAQ.md) for troubleshooting.
## Upgrading from a previous version

837
MAINTENANCE.md Normal file
View File

@ -0,0 +1,837 @@
# Maintenance & Updates Guide
This guide helps you maintain your al-folio website and keep it up-to-date with the latest features and security patches.
<!--ts-->
- [Maintenance \& Updates Guide](#maintenance--updates-guide)
- [Overview](#overview)
- [Dependency Management](#dependency-management)
- [Understanding Dependencies](#understanding-dependencies)
- [Checking for Updates](#checking-for-updates)
- [Updating Gems (Ruby)](#updating-gems-ruby)
- [Updating Node Packages (JavaScript)](#updating-node-packages-javascript)
- [Releasing New Versions](#releasing-new-versions)
- [When to Release](#when-to-release)
- [Semantic Versioning](#semantic-versioning)
- [Release Process](#release-process)
- [Annual Site Review](#annual-site-review)
- [Content Review](#content-review)
- [Technical Review](#technical-review)
- [SEO Review](#seo-review)
- [Performance Review](#performance-review)
- [Security Review](#security-review)
- [Upgrading Jekyll](#upgrading-jekyll)
- [Before Upgrading](#before-upgrading)
- [Major Version Upgrades](#major-version-upgrades)
- [Testing After Upgrade](#testing-after-upgrade)
- [Backup and Disaster Recovery](#backup-and-disaster-recovery)
- [What to Back Up](#what-to-back-up)
- [Disaster Recovery Checklist](#disaster-recovery-checklist)
- [Monitoring and Alerts](#monitoring-and-alerts)
- [GitHub Notifications](#github-notifications)
- [Website Monitoring](#website-monitoring)
- [Uptime Monitoring](#uptime-monitoring)
- [Common Maintenance Tasks](#common-maintenance-tasks)
- [Updating Your CV](#updating-your-cv)
- [Adding Publications](#adding-publications)
- [Archiving Old Posts](#archiving-old-posts)
- [Updating Broken Links](#updating-broken-links)
- [Breaking Changes to Watch For](#breaking-changes-to-watch-for)
- [Jekyll Major Version Updates](#jekyll-major-version-updates)
- [Theme Updates](#theme-updates)
- [Maintenance Schedule](#maintenance-schedule)
- [Weekly (Automated)](#weekly-automated)
- [Monthly](#monthly)
- [Quarterly (Every 3 months)](#quarterly-every-3-months)
- [Annually (Every year)](#annually-every-year)
- [Resources](#resources)
- [Quick Maintenance Checklist](#quick-maintenance-checklist)
## Overview
Maintenance keeps your site secure, fast, and up-to-date. This guide provides:
- When and how to update dependencies
- Annual review checklist
- How to handle major upgrades
- Disaster recovery procedures
Most maintenance is minimal—usually just dependency updates 2-3 times per year.
---
## Dependency Management
### Understanding Dependencies
Your site depends on external libraries:
**Ruby (Backend):**
- Located in `Gemfile`
- Includes Jekyll, jekyll-scholar, plugins, etc.
- Installed via Bundler
**JavaScript (Frontend):**
- Located in `package.json`
- Includes build tools, code formatters, etc.
- Installed via npm
**External Libraries (via CDN):**
- Bootstrap, MathJax, Font Awesome, etc.
- Versions specified in `_config.yml`
---
### Checking for Updates
**Check Ruby gems:**
```bash
bundle outdated
```
Shows all outdated gems with current and latest versions.
**Check Node packages:**
```bash
npm outdated
```
Shows all outdated packages.
**Check for security vulnerabilities:**
```bash
bundle audit # Check gems for security issues
npm audit # Check packages for security issues
```
---
### Updating Gems (Ruby)
**Safe update (minor versions only):**
```bash
bundle update --conservative
```
Updates to latest patch versions (e.g., 4.1.0 → 4.1.5) but not major versions.
**Full update (all versions):**
```bash
bundle update
```
Updates to latest version including major versions (e.g., 4.x → 5.x).
**After updating:**
1. Test locally: `bundle exec jekyll serve`
2. Check for errors in terminal output
3. Visit your site and test all features
4. Deploy: `git add Gemfile.lock && git commit -m "Update dependencies"`
**If something breaks:**
- See [Breaking Changes section](#breaking-changes-to-watch-for)
- Revert with `git revert <commit>`
- Ask for help in [GitHub Discussions](https://github.com/alshedivat/al-folio/discussions)
---
### Updating Node Packages (JavaScript)
**Check for updates:**
```bash
npm outdated
```
**Update all packages:**
```bash
npm update
```
**Update a specific package:**
```bash
npm install package-name@latest
```
**After updating:**
1. Test locally: `npm run build` or `docker compose up`
2. Check for TypeScript/linting errors
3. Test your site
4. Commit: `git add package.json package-lock.json && git commit -m "Update packages"`
---
## Releasing New Versions
### When to Release
A new version of al-folio **must** be released on GitHub whenever:
- **Dependency changes occur** – Adding, removing, or upgrading any gems (Ruby) or packages (JavaScript)
- **Major features are added** – New functionality that benefits users
- **Bug fixes are made** – Issues affecting functionality or security
- **Breaking changes occur** – Changes that affect how users configure or use the theme
Dependency updates are significant because they:
- May introduce security patches
- Could include bug fixes or new features
- Might have breaking changes that affect the theme
- Affect Docker image consistency
### Semantic Versioning
al-folio follows [Semantic Versioning](https://semver.org/) with the format `MAJOR.MINOR.PATCH`:
**MAJOR version** (e.g., `1.0.0` → `2.0.0`):
- Breaking changes that require users to manually update their configuration
- Major feature overhauls
- Dropping support for older tools or dependencies
- Example: Jekyll 4 → Jekyll 5 migration
**MINOR version** (e.g., `1.0.0` → `1.1.0`):
- New features that don't break existing functionality
- New optional configuration options
- New plugins or integrations
- Example: Adding a new collection type
**PATCH version** (e.g., `1.0.0` → `1.0.1`):
- Bug fixes
- Security patches
- Dependency updates that don't break functionality
- Documentation improvements
- Example: Fixing CSS styling issues or updating gems
### Release Process
When releasing a new version:
1. **Update version numbers** in your repository:
```bash
# Update docker-compose.yml
# Change: image: amirpourmand/al-folio:vX.X.X
# Example: v0.16.2 → v0.17.0
```
Edit `docker-compose.yml` and update the image tag in the `jekyll` service:
```yaml
services:
jekyll:
image: amirpourmand/al-folio:v0.17.0 # Update this version
```
2. **Update documentation** to reference the new version:
- [INSTALL.md](INSTALL.md) – Update any version references in upgrade instructions
- [QUICKSTART.md](QUICKSTART.md) – Update if version-specific instructions changed
- [README.md](README.md) – Update release badges and version references
- Any other docs mentioning the current version
3. **Create a GitHub Release:**
- Go to your repository → **Releases** → **Create a new release**
- Tag version: `v0.17.0` (match the format in `docker-compose.yml`)
- Release title: Describe the changes (e.g., "Security patch: Update Jekyll" or "New feature: Add xyz")
- Release notes: List all changes, including:
- Breaking changes (if any)
- New features
- Bug fixes
- Dependency updates
- Example format:
```markdown
## What's Changed
### Breaking Changes
- (none)
### New Features
- Added support for XYZ
### Bug Fixes
- Fixed styling issue with mobile nav
### Dependencies Updated
- Updated Jekyll from 4.2.0 to 4.3.0
- Updated jekyll-scholar from 5.x to 6.x
- Updated Bootstrap from 5.1 to 5.2
```
4. **Build and publish the Docker image** (if applicable):
- Tag the Docker image with the new version
- Push to Docker Hub so users can `docker compose pull` the latest version
- Ensure the Docker image tag matches the version in `docker-compose.yml`
5. **Communicate the update:**
- Add a GitHub Discussion announcing the release
- If breaking changes, provide migration guide
- Link to release notes in important places
**User impact:**
Users running older versions can upgrade to the new version by:
```bash
# Update docker-compose.yml to reference the new version
# Then rebuild and restart
docker compose up --build
```
Or if using git:
```bash
git fetch upstream
git rebase vX.X.X # Replace with new version tag
```
---
## Annual Site Review
### Content Review
**Every year, review:**
- [ ] Is your bio still accurate?
- [ ] Are your research interests current?
- [ ] Have you added recent publications?
- [ ] Are past events still listed (or archived)?
- [ ] Do old projects still represent your work?
- [ ] Are social media links still active?
**Content updates:**
```bash
# Edit your bio in _pages/about.md
# Update your CV in _data/cv.yml or assets/json/resume.json
# Add new publications to _bibliography/papers.bib
```
---
### Technical Review
**Every year, check:**
- [ ] All external links still work (use browser extensions or CI tools)
- [ ] Images load properly
- [ ] PDFs are accessible
- [ ] No deprecated code or plugins used
- [ ] Site works on modern browsers
- [ ] Mobile view is responsive
**Run automated tests:**
```bash
# Broken links test (in GitHub Actions)
# Lighthouse performance audit
# Accessibility tests (axe)
```
---
### SEO Review
**Every year, review:**
- [ ] Page titles and descriptions are still accurate
- [ ] Alt text is on all images
- [ ] No broken links that hurt SEO
- [ ] Site speed hasn't degraded
- [ ] Search Console shows no errors
- [ ] Publications indexed on Google Scholar
**Check in Google Search Console:**
- Impressions and click-through rate (are you visible?)
- Any crawl errors or coverage issues
- Mobile usability warnings
---
### Performance Review
**Every year, run:**
- [ ] Google PageSpeed Insights: `https://pagespeed.web.dev/`
- [ ] Lighthouse audit (built into Chrome)
- [ ] Check site load time
**Typical targets:**
- Load time: < 3 seconds
- Lighthouse score: > 90
- Mobile friendly: Yes
**If performance degraded:**
- Check image sizes (compress if needed)
- Review page complexity
- Check for unused CSS/JS
- See al-folio performance guide
---
### Security Review
**Every year:**
- [ ] Run `bundle audit` for gem vulnerabilities
- [ ] Run `npm audit` for package vulnerabilities
- [ ] Update Gemfile and package.json if issues found
- [ ] Check GitHub Security tab for alerts
- [ ] Review GitHub Actions permissions
**Security checklist:**
- [ ] No secrets (API keys, tokens) in code
- [ ] All dependencies up-to-date
- [ ] GitHub token permissions are minimal (read-only by default)
- [ ] Site uses HTTPS (GitHub Pages default)
---
## Upgrading Jekyll
### Before Upgrading
**Check current version:**
```bash
jekyll --version
```
**Read release notes:**
- Check [Jekyll releases](https://jekyllrb.com/news/)
- Check [al-folio releases](https://github.com/alshedivat/al-folio/releases)
- Look for breaking changes
**Backup your site (see [Disaster Recovery](#backup-and-disaster-recovery)):**
```bash
git branch backup-current-version
```
---
### Major Version Upgrades
**Example: Upgrading Jekyll 4.x → 5.x**
1. **Update Gemfile:**
```bash
bundle update jekyll
```
2. **Update other gems:**
```bash
bundle update
```
3. **Test locally:**
```bash
bundle exec jekyll serve
```
4. **Look for errors:**
- Check terminal output for warnings
- Visit `http://localhost:4000` and test features
5. **If major issues:**
```bash
git revert HEAD # Undo the update
bundle install # Restore old version
```
6. **If successful:**
```bash
git add Gemfile.lock
git commit -m "Upgrade Jekyll to 5.x"
```
---
### Testing After Upgrade
**Comprehensive testing:**
```bash
# 1. Build the site locally
bundle exec jekyll build
# 2. Check for errors
echo "Check for error messages above"
# 3. Start local server
bundle exec jekyll serve
# 4. Test key features:
# - Blog posts display correctly
# - Publications show up
# - Navigation works
# - Styling looks right
# - Search works
# - Comments work (if enabled)
```
**Before deploying:**
- Test on mobile
- Test on different browsers (Chrome, Firefox, Safari)
- Test keyboard navigation
- Check all external links
---
## Backup and Disaster Recovery
### What to Back Up
**Your content (most important):**
- `_posts/` – Blog posts
- `_projects/` – Project pages
- `_pages/` – Custom pages
- `_data/` – CV, social links, publications metadata
- `_bibliography/papers.bib` – Your publications
- `assets/` – Your images, PDFs, documents
**Configuration:**
- `_config.yml` – Site settings
- `Gemfile`, `package.json` – Dependencies
**Everything else is auto-generated** (themes, layouts, built site).
### Disaster Recovery Checklist
**If your repository gets corrupted:**
1. **Check GitHub:** Is the current version safe?
```bash
git status
```
2. **Revert to a previous commit:**
```bash
git log --oneline | head -20 # See recent commits
git revert <commit-hash> # Undo a specific commit
# OR
git reset --hard <commit-hash> # Go back to a specific point
```
3. **If GitHub is corrupted, restore locally:**
```bash
# You have local backups in your git history
git reflog # See all actions you've done
git reset --hard <reference>
```
4. **Nuclear option (last resort):**
```bash
# Clone a fresh copy of the repo
git clone https://github.com/yourusername/yourrepo.git new-copy
# Your content in _posts/, _projects/, _data/ is safe
# Just copy those folders to the new clone
```
**To prevent loss:**
- GitHub keeps your full history
- Regular pushes = automatic backups
- Consider exporting your content periodically
---
## Monitoring and Alerts
### GitHub Notifications
**Watch your repository for:**
- Dependabot alerts (automatic security updates)
- Issues and pull requests
- GitHub Actions failures
**Configuration:**
- Go to repository **Settings** → **Notifications**
- Set how and when you want alerts
**Recommended:**
- Email for security alerts (critical)
- No email for regular notifications (too noisy)
---
### Website Monitoring
**Monitor broken links:**
- al-folio includes a GitHub Actions workflow for link checking
- Results posted to pull requests
- Fix before merging
**Monitor accessibility:**
- The axe accessibility workflow runs automatically
- Review results in GitHub Actions tab
---
### Uptime Monitoring
**Optional: Monitor if your site is down**
Tools:
- [Cronitor](https://cronitor.io) – Simple uptime monitoring
- [Uptimerobot](https://uptimerobot.com) – Free tier available
- [Statuspage.io](https://www.statuspage.io/) – Public status page
**Setup (example with Cronitor):**
1. Create free account
2. Add your site URL
3. Get notified if it's down
4. Typical response time: 5 minutes
---
## Common Maintenance Tasks
### Updating Your CV
**Option 1: JSON Resume format (recommended):**
- Edit `assets/json/resume.json`
- Update education, experience, skills
- Format follows [JSON Resume standard](https://jsonresume.org/)
**Option 2: YAML format:**
- Edit `_data/cv.yml`
- If this file exists, it's used instead of JSON
- More human-readable than JSON
**After updating:**
```bash
git add assets/json/resume.json # or _data/cv.yml
git commit -m "Update CV"
git push
```
---
### Adding Publications
**Add to BibTeX:**
```bash
# Edit _bibliography/papers.bib
# Add a new entry:
@article{newpaper2024,
title={Your Paper Title},
author={Your Name and Others},
journal={Journal Name},
year={2024},
volume={1},
pages={1-10},
doi={10.1234/doi},
pdf={newpaper.pdf} # If you have a PDF
}
```
**If you have a PDF:**
1. Save to `assets/pdf/newpaper.pdf`
2. Add `pdf={newpaper.pdf}` to BibTeX entry
**After updating:**
```bash
git add _bibliography/papers.bib assets/pdf/
git commit -m "Add new paper"
git push
```
---
### Archiving Old Posts
**Move to archive (don't delete):**
```bash
# Don't delete posts, just move them
# Old posts stay indexed in search engines this way
# Option 1: Add to frontmatter
---
layout: post
title: Old Post (Archived)
date: 2015-01-01
hidden: true
---
# Option 2: Create an archive page
# See _pages/blog.md for archive configuration
```
---
### Updating Broken Links
**Find broken links:**
- Use [Broken Link Checker](https://www.brokenlinkcheck.com/)
- Or use al-folio's broken-link GitHub Actions workflow
- Or browser extension like Checklinks
**Fix them:**
```bash
# Find and replace in files
grep -r "broken-url.com" .
# Update in:
# - Blog posts (_posts/)
# - Pages (_pages/)
# - Data files (_data/)
# - BibTeX entries (_bibliography/)
```
---
## Breaking Changes to Watch For
### Jekyll Major Version Updates
Watch for breaking changes in:
- **Liquid syntax** – How templates work
- **Plugin compatibility** – Some plugins may not work
- **Configuration changes** – New or deprecated options
- **Folder structure** – Where files go
**Check al-folio releases** before upgrading Jekyll. Major Jekyll updates may require al-folio changes too.
---
### Theme Updates
If you customize CSS/layouts:
- Backup your customizations
- Test updates carefully
- Watch for file renames or structure changes
---
## Maintenance Schedule
### Weekly (Automated)
- ✅ GitHub Actions tests (automated)
- ✅ Lighthouse performance (automated)
- ✅ Accessibility checks (automated)
### Monthly
- Check GitHub Dependabot alerts
- Review GitHub Actions log for errors
- Quick visual inspection (is site still working?)
### Quarterly (Every 3 months)
- Update dependencies: `bundle update --conservative`
- Test local build thoroughly
- Check Google Search Console for errors
### Annually (Every year)
- Full content review (see [Annual Site Review](#annual-site-review))
- Security audit (`bundle audit`, `npm audit`)
- Performance review (Google PageSpeed)
- Technology update assessment
- Consider major version upgrades
---
## Resources
- **[Jekyll Documentation](https://jekyllrb.com/)** – Official Jekyll docs
- **[Bundler Guide](https://bundler.io/)** – Ruby dependency management
- **[npm Documentation](https://docs.npmjs.com/)** – JavaScript package manager
- **[GitHub Pages Help](https://docs.github.com/en/pages)** – GitHub Pages docs
- **[al-folio Releases](https://github.com/alshedivat/al-folio/releases)** – Track updates
- **[al-folio Discussions](https://github.com/alshedivat/al-folio/discussions)** – Ask for help
---
## Quick Maintenance Checklist
**Monthly:**
- [ ] Check GitHub notifications
- [ ] Review any Dependabot alerts
**Quarterly:**
```bash
bundle outdated # Check for updates
bundle update --conservative # Update minor versions
bundle exec jekyll build # Test locally
```
**Annually:**
- [ ] Run full annual review (see above)
- [ ] Update major dependencies if needed
- [ ] Security audit
- [ ] Review and update CV/publications
- [ ] Update bio if changed
**When deploying:**
- [ ] Test locally first
- [ ] Check GitHub Actions log
- [ ] Verify site looks correct
- [ ] Test on mobile
---
**Remember:** The best maintenance is regular testing and staying aware of updates. Spend 30 minutes every month checking for updates—it's easier than fixing major issues later!

98
QUICKSTART.md Normal file
View File

@ -0,0 +1,98 @@
# 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.
<!--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)
<!--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**
> **Video Tutorial:** Watch a walkthrough of these steps [here](assets/video/tutorial_al_folio.mp4)
## 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
```
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 (~4 minutes, look for a green checkmark)
3. Go to **Settings** → **Pages** → set Source to `gh-pages` branch
4. 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](CUSTOMIZE.md)
- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
- Installation options: [INSTALL.md](INSTALL.md)
- Frequently asked questions: [FAQ.md](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](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! 🎉

24
README.md
View File

@ -257,6 +257,7 @@ Run the test yourself: [Google Lighthouse PageSpeed Insights](https://pagespeed.
- [GitHub Copilot Agents](#github-copilot-agents)
- [Customization Agent](#customization-agent)
- [Documentation Agent](#documentation-agent)
- [Documentation](#documentation)
- [Features](#features)
- [Light/Dark Mode](#lightdark-mode)
- [CV](#cv)
@ -281,6 +282,8 @@ Run the test yourself: [Google Lighthouse PageSpeed Insights](https://pagespeed.
- [Star History](#star-history)
- [License](#license)
<!--te-->
## Getting started
Want to learn more about Jekyll? Check out [this tutorial](https://www.taniarascia.com/make-a-static-website-with-jekyll/). Why Jekyll? Read [Andrej Karpathy's blog post](https://karpathy.github.io/2014/07/01/switching-to-jekyll/)! Why write a blog? Read [Rachel Thomas blog post](https://medium.com/@racheltho/why-you-yes-you-should-blog-7d2544ac1045).
@ -321,6 +324,20 @@ See [CONTRIBUTING.md § GitHub Copilot Agents](CONTRIBUTING.md#github-copilot-ag
> **Requirements:** Both agents require a [GitHub Copilot](https://github.com/features/copilot) subscription. For more information about GitHub Copilot and how to use agents, see the [GitHub Copilot documentation](https://docs.github.com/en/copilot).
## Documentation
Comprehensive guides for all aspects of your al-folio website:
- **[Quick Start](QUICKSTART.md)** – Get running in 5 minutes
- **[Installation & Deployment](INSTALL.md)** – Set up your site on GitHub Pages or other platforms
- **[Customization Guide](CUSTOMIZE.md)** – Personalize your website (CVs, publications, themes, etc.)
- **[Troubleshooting](TROUBLESHOOTING.md)** – Fix common issues (deployment, build, styling, content)
- **[FAQ](FAQ.md)** – Frequently asked questions and solutions
- **[Analytics](ANALYTICS.md)** – Add website analytics and visitor tracking
- **[Accessibility](ACCESSIBILITY.md)** – Ensure your site is accessible to all visitors
- **[SEO Guide](SEO.md)** – Optimize for search engines and improve discoverability
- **[Maintenance Guide](MAINTENANCE.md)** – Keep your site updated and secure
## Features
### Light/Dark Mode
@ -336,9 +353,12 @@ This template has a built-in light/dark mode. It detects the user preferred colo
### CV
There are currently 2 different ways of generating the CV page content. The first one is by using a json file located in [assets/json/resume.json](assets/json/resume.json). It is a [known standard](https://jsonresume.org/) for creating a CV programmatically. The second one, currently used as a fallback when the json file is not found, is by using a yml file located in [\_data/cv.yml](_data/cv.yml). This was the original way of creating the CV page content and since it is more human readable than a json file we decided to keep it as an option.
Your CV can be generated in one of two modern formats:
What this means is, if there is no resume data defined in [\_config.yml](_config.yml) and loaded via a json file, it will load the contents of [\_data/cv.yml](_data/cv.yml) as fallback.
- **[RenderCV](https://rendercv.com/) Format** (recommended): Edit [`_data/cv.yml`](_data/cv.yml) using the human-readable RenderCV YAML format. This format enables automatic PDF generation via GitHub Actions and provides professional styling options.
- **[JSONResume](https://jsonresume.org/) Format**: Edit [`assets/json/resume.json`](assets/json/resume.json) using the standardized JSON format. This is compatible with other resume tools and services.
You can use both formats simultaneously and switch which one is rendered on your CV page using the `cv_format` frontmatter variable, or maintain just the one you prefer. The two files are independent data sources: if you choose to keep both, you must update each file separately—there is no automatic synchronization between them.
[![CV Preview](readme_preview/cv.png)](https://alshedivat.github.io/al-folio/cv/)

536
SEO.md Normal file
View File

@ -0,0 +1,536 @@
# SEO Best Practices Guide
This guide helps you optimize your al-folio website for search engines so your research and work are discoverable.
<!--ts-->
- [SEO Best Practices Guide](#seo-best-practices-guide)
- [Overview](#overview)
- [Basic SEO Setup](#basic-seo-setup)
- [Sitemap and Robots](#sitemap-and-robots)
- [Site URL and Metadata](#site-url-and-metadata)
- [Enabling Open Graph (Social Media Previews)](#enabling-open-graph-social-media-previews)
- [What is Open Graph?](#what-is-open-graph)
- [Enable in al-folio](#enable-in-al-folio)
- [Test Your Setup](#test-your-setup)
- [Schema.org Markup](#schemaorg-markup)
- [What is Schema.org?](#what-is-schemaorg)
- [Enable in al-folio](#enable-in-al-folio-1)
- [What Gets Marked Up](#what-gets-marked-up)
- [Search Console Setup](#search-console-setup)
- [Google Search Console](#google-search-console)
- [Bing Webmaster Tools](#bing-webmaster-tools)
- [Publication Indexing](#publication-indexing)
- [Google Scholar](#google-scholar)
- [DBLP (Computer Science)](#dblp-computer-science)
- [arXiv](#arxiv)
- [Content Optimization](#content-optimization)
- [Page Titles and Descriptions](#page-titles-and-descriptions)
- [Heading Structure](#heading-structure)
- [Image Optimization](#image-optimization)
- [Internal Linking](#internal-linking)
- [RSS Feed for Discovery](#rss-feed-for-discovery)
- [Performance & Mobile](#performance--mobile)
- [SEO Checklist](#seo-checklist)
- [Resources](#resources)
<!--te-->
## Overview
SEO (Search Engine Optimization) makes your website discoverable on Google, Bing, and other search engines. For academics, this means:
- Your research becomes discoverable when people search for your work
- Your CV/bio appears in search results
- Your publications rank higher
- More citations and collaborations
al-folio includes SEO basics, but you can optimize further.
---
## Basic SEO Setup
### Sitemap and Robots
al-folio auto-generates a `sitemap.xml` and `robots.txt` for you. These tell search engines what pages exist.
**Verify they exist:**
- Visit `https://your-site.com/sitemap.xml` – Should show an XML list of pages
- Visit `https://your-site.com/robots.txt` – Should show instructions for search engines
If they're missing:
1. Check `_config.yml` has a valid `url`
2. Rebuild: `bundle exec jekyll build`
3. Check `_site/` directory has both files
**No configuration needed** – al-folio handles this automatically.
---
### Site URL and Metadata
Ensure `_config.yml` has correct metadata:
```yaml
title: Your Full Name or Site Title
description: > # Brief description (1-2 sentences)
A description of your research and expertise.
This appears in search results.
author: Your Name
keywords: machine learning, research, academia, etc.
url: https://your-domain.com
lang: en
```
All fields are important for SEO. **Avoid leaving fields blank.**
---
## Enabling Open Graph (Social Media Previews)
### What is Open Graph?
When someone shares your page on Twitter, Facebook, LinkedIn, etc., Open Graph controls what preview appears.
**Without Open Graph:**
- Generic title
- No image
- Ugly preview
**With Open Graph:**
- Your custom title
- Your custom image (photo, diagram, etc.)
- Custom description
- Professional preview
### Enable in al-folio
Open Graph is disabled by default. To enable:
1. **Edit `_config.yml`:**
```yaml
serve_og_meta: true # Change from false to true
og_image: /assets/img/og-image.png # Path to your image (1200x630px recommended)
```
2. **Create your OG image:**
- Size: 1200x630 pixels
- Format: PNG or JPG
- Content: Your name/logo + key info
- Save to: `assets/img/og-image.png`
3. **Commit and deploy**
4. **Test it:**
- Use [Facebook's Sharing Debugger](https://developers.facebook.com/tools/debug/sharing/)
- Paste your site URL
- You should see your custom image and title
**Per-page OG images:**
Add to the frontmatter of a blog post or page:
```markdown
---
layout: post
title: My Research Paper
og_image: /assets/img/paper-diagram.png
---
```
---
## Schema.org Markup
### What is Schema.org?
Schema.org is structured data that tells search engines what kind of content is on your page:
- "This is a Person" (your bio page)
- "This is a Publication" (your paper)
- "This is a BlogPosting" (your article)
Benefits:
- Rich snippets in search results
- Better knowledge graph information
- Schema validation helps Google understand your site
### Enable in al-folio
Enable in `_config.yml`:
```yaml
serve_schema_org: true # Change from false to true
```
That's it! al-folio automatically marks up:
- **Author info** (Person schema with name, URL, photo)
- **Blog posts** (BlogPosting schema with date, title, description)
- **Publications** (CreativeWork/ScholarlyArticle schema)
### What Gets Marked Up
**Homepage (Person):**
- Your name, photo, description
- Links to your profiles (LinkedIn, GitHub, etc.)
**Blog posts (BlogPosting):**
- Title, date, author, description
- Content
- Publication date and modified date
**Publications (ScholarlyArticle):**
- Title, authors, abstract
- Publication date, venue
- URL and PDF links
---
## Search Console Setup
### Google Search Console
**Google Search Console** lets you monitor how your site appears in Google search results.
**Setup:**
1. Go to [Google Search Console](https://search.google.com/search-console)
2. Add your website:
- Click **"URL prefix"**
- Enter your site URL: `https://your-domain.com`
3. Verify ownership (choose one method):
- **HTML file upload** – Download file, add to repository root
- **HTML tag** – Copy meta tag to `_config.yml` → redeploy
- **Google Analytics** – If you already use Google Analytics
- **DNS record** – Advanced (if you own the domain)
**Add to `_config.yml`:**
```yaml
google_site_verification: YOUR_VERIFICATION_CODE
```
(Replace `YOUR_VERIFICATION_CODE` with the code from Search Console.)
**Monitor in Search Console:**
- **Performance** – Which queries bring traffic, your ranking position
- **Coverage** – Any indexing errors
- **Enhancements** – Schema.org validation
- **Sitemaps** – Your sitemap status
---
### Bing Webmaster Tools
Similar to Google Search Console but for Bing search:
1. Go to [Bing Webmaster Tools](https://www.bing.com/webmasters)
2. Add your site
3. Verify (usually auto-verifies if you verified Google)
4. Add to `_config.yml`:
```yaml
bing_site_verification: YOUR_BING_CODE
```
**Note:** Bing commands are optional but recommended. Check both console dashboards regularly.
---
## Publication Indexing
### Google Scholar
**Goal:** Get your publications listed on Google Scholar so they show up in scholar search results.
**Google Scholar auto-crawls:**
- Your website automatically (if publicly accessible)
- Your publications page if it has proper markup
- PDFs linked from your site
**To improve Scholar indexing:**
1. **Ensure BibTeX has proper format:**
```bibtex
@article{mykey,
title={Your Paper Title},
author={Your Name and Co-Author},
journal={Journal Name},
year={2024},
volume={1},
pages={1-10},
doi={10.1234/doi}
}
```
2. **Add PDFs to BibTeX:**
```bibtex
@article{mykey,
# ... other fields ...
pdf={my-paper.pdf} # File at assets/pdf/my-paper.pdf
}
```
3. **Submit to Google Scholar (optional):**
- Go to [Google Scholar Author Profile](https://scholar.google.com/citations)
- Create a profile
- Google will find your papers automatically within weeks
4. **Wait 3-6 months** – Google Scholar takes time to index
---
### DBLP (Computer Science)
If your research is computer science related:
1. Go to [DBLP](https://dblp.org/)
2. Search for yourself or your papers
3. If missing, [Submit via DBLP](https://dblp.org/db/contrib/) (requires account)
4. DBLP will verify and add your work
---
### arXiv
If you have preprints:
1. Go to [arXiv.org](https://arxiv.org/)
2. Submit your preprint
3. Once listed, arXiv automatically indexes it across search engines
**Add arXiv link to BibTeX:**
```bibtex
@article{mykey,
# ... other fields ...
arxiv={2024.12345} # arXiv ID
}
```
---
## Content Optimization
### Page Titles and Descriptions
Every page needs a title and description. These show in search results.
**In `_config.yml`:**
```yaml
title: Jane Smith - Computer Science Researcher
description: >
Academic website of Jane Smith, focusing on machine learning and AI ethics.
```
**In page/post frontmatter:**
```markdown
---
layout: post
title: Novel Deep Learning Architecture for Climate Modeling
description: A new approach to improving climate model accuracy with deep learning
---
```
**Checklist:**
- [ ] Title under 60 characters (so it doesn't get cut off)
- [ ] Description 120-160 characters
- [ ] Include your name in the site title
- [ ] Include keywords naturally
---
### Heading Structure
Use proper HTML heading hierarchy for both SEO and accessibility:
```markdown
# H1: Main Page Title
Use one H1 per page, usually your blog post or page title
## H2: Section Heading
### H3: Subsection
### H3: Another subsection
## H2: Another Section
```
**Benefits:**
- Search engines understand your content structure
- Screen readers can navigate better
- Visitors can scan your content
---
### Image Optimization
**For SEO:**
- Use descriptive filenames: `neural-network-architecture.png` (not `img1.png`)
- Add alt text (also helps accessibility):
```markdown
![Neural network showing three layers with training accuracy of 95%](assets/img/neural-network.png)
```
**For performance:**
- Optimize image file size (use tools like TinyPNG)
- Use modern formats (WebP instead of large JPGs)
- Responsive images (different sizes for mobile vs desktop)
---
### Internal Linking
Link between your own pages strategically:
```markdown
See my [publication on climate AI](./publications/) or my [blog post on neural networks](/blog/2024/neural-networks/).
```
**Benefits:**
- Search engines crawl through your links
- Users discover more of your content
- Distributes "authority" across your site
---
## RSS Feed for Discovery
al-folio auto-generates an RSS feed at `/feed.xml`.
**Why RSS matters:**
- Content aggregators pick up your posts
- Researchers can subscribe to your updates
- Improves discoverability
**Ensure your feed works:**
```yaml
# In _config.yml
title: Your Site
description: Your site description
url: https://your-domain.com # MUST be complete URL
```
**Test your feed:**
- Visit `https://your-site.com/feed.xml`
- Should show XML with your recent posts
- Try subscribing in a feed reader (Feedly, etc.)
---
## Performance & Mobile
Search engines favor fast, mobile-friendly sites.
**Check your site:**
- Use [Google PageSpeed Insights](https://pagespeed.web.dev/)
- Enter your site URL
- Review recommendations
- al-folio already optimizes for performance, but you can improve further:
- Compress images
- Minimize CSS/JS (enabled by default)
- Use lazy loading (already enabled)
**Mobile optimization:**
- al-folio is responsive by default
- Test on phones/tablets
- Ensure buttons are large enough to tap
- Check readability on small screens
---
## SEO Checklist
Before considering your site "SEO optimized":
**Basic Setup:**
- [ ] `_config.yml` has `title`, `description`, `author`, `url`
- [ ] Sitemap accessible at `/sitemap.xml`
- [ ] `robots.txt` accessible at `/robots.txt`
- [ ] Mobile-friendly (test on phone)
**Search Console:**
- [ ] Google Search Console linked
- [ ] Bing Webmaster Tools linked (optional but recommended)
- [ ] No major indexing errors
- [ ] Sitemaps submitted
**Schema/Open Graph:**
- [ ] `serve_og_meta: true` (for social sharing)
- [ ] `serve_schema_org: true` (for structured data)
- [ ] Test OG with [Facebook Debugger](https://developers.facebook.com/tools/debug/sharing/)
- [ ] Validate schema at [Schema.org Validator](https://validator.schema.org/)
**Content:**
- [ ] Every page has unique title (under 60 chars)
- [ ] Every page has description (120-160 chars)
- [ ] Blog posts have proper dates
- [ ] Images have descriptive alt text
- [ ] Headings follow proper hierarchy
**Publications:**
- [ ] BibTeX entries have proper format
- [ ] PDFs linked from BibTeX
- [ ] Submitted to Google Scholar (optional)
- [ ] Indexed on DBLP or arXiv (if applicable)
**Performance:**
- [ ] Site loads under 3 seconds (check PageSpeed)
- [ ] No broken links (use lighthouse or similar)
- [ ] RSS feed works (check `/feed.xml`)
---
## Resources
- **[Google Search Central](https://developers.google.com/search)** – Official SEO guide
- **[Moz SEO Checklist](https://moz.com/beginners-guide-to-seo)** – Beginner-friendly guide
- **[Google PageSpeed Insights](https://pagespeed.web.dev/)** – Performance analysis
- **[Schema.org](https://schema.org/)** – Structured data reference
- **[WebAIM](https://webaim.org/)** – Accessibility (helps SEO too)
- **[Lighthouse Audit](https://chrome.google.com/webstore/detail/lighthouse/blipmdconlkpombljlkpstvnztVTNyZe)** – Browser extension
---
**Next Steps:**
1. Enable Open Graph and Schema.org in `_config.yml`
2. Set up Google Search Console and Bing Webmaster Tools
3. Optimize your page titles and descriptions
4. Add alt text to images and PDFs to your BibTeX
5. Monitor search console regularly for indexing issues
Your research will be more discoverable with these optimizations! 🔍

453
TROUBLESHOOTING.md Normal file
View File

@ -0,0 +1,453 @@
# Troubleshooting Guide
This guide covers common issues and their solutions. For more information, see [FAQ.md](FAQ.md) or check [GitHub Discussions](https://github.com/alshedivat/al-folio/discussions).
<!--ts-->
- [Troubleshooting Guide](#troubleshooting-guide)
- [Deployment Issues](#deployment-issues)
- [Site fails to deploy on GitHub Pages](#site-fails-to-deploy-on-github-pages)
- [Custom domain becomes blank after deployment](#custom-domain-becomes-blank-after-deployment)
- [GitHub Actions: "Unknown tag 'toc'" error](#github-actions-unknown-tag-toc-error)
- [Local Build Issues](#local-build-issues)
- [Docker build fails](#docker-build-fails)
- [Ruby dependency issues](#ruby-dependency-issues)
- [Port already in use](#port-already-in-use)
- [Styling & Layout Problems](#styling--layout-problems)
- [CSS and JS not loading properly](#css-and-js-not-loading-properly)
- [Site looks broken after deployment](#site-looks-broken-after-deployment)
- [Theme colors not applying](#theme-colors-not-applying)
- [Content Not Appearing](#content-not-appearing)
- [Blog posts not showing up](#blog-posts-not-showing-up)
- [Publications not displaying](#publications-not-displaying)
- [Images not loading](#images-not-loading)
- [Configuration Issues](#configuration-issues)
- [YAML syntax errors](#yaml-syntax-errors)
- [Feed (RSS/Atom) not working](#feed-rssatom-not-working)
- [Search not working](#search-not-working)
- [Feature-Specific Issues](#feature-specific-issues)
- [Comments (Giscus) not appearing](#comments-giscus-not-appearing)
- [Related posts broken](#related-posts-broken)
- [Code formatting issues](#code-formatting-issues)
- [Getting Help](#getting-help)
<!--te-->
## Deployment Issues
### Site fails to deploy on GitHub Pages
**Problem:** GitHub Actions shows an error when deploying.
**Solution:**
1. Check your repository **Actions** tab for error messages
2. Ensure you followed [Step 2 of QUICKSTART.md](QUICKSTART.md#step-2-configure-deployment-1-min) (Workflow permissions)
3. Verify your `_config.yml` has correct `url` and `baseurl`:
- Personal site: `url: https://username.github.io` and `baseurl:` (empty)
- Project site: `url: https://username.github.io` and `baseurl: /repo-name/`
4. Check that you're pushing to the `main` (or `master`) branch, NOT `gh-pages`
5. Commit and push a small change to trigger redeployment
**For YAML syntax errors:**
- Run `bundle exec jekyll build` locally to see the exact error
- Check for unquoted special characters (`:`, `&`, `#`) in YAML strings
---
### Custom domain becomes blank after deployment
**Problem:** You set a custom domain (e.g., `example.com`), but it resets to blank after deployment.
**Solution:**
1. Create a file named `CNAME` (no extension) in your repository root
2. Add your domain to it: `example.com` (one domain per line)
3. Commit and push
4. The domain will persist after future deployments
(See [DNS configuration instructions in INSTALL.md](INSTALL.md#deployment) for initial custom domain setup.)
---
### GitHub Actions: "Unknown tag 'toc'" error
**Problem:** Local build works, but GitHub Actions fails with `Unknown tag 'toc'`.
**Solution:**
1. Check your **Settings** → **Pages** → **Source** is set to `Deploy from a branch`
2. Ensure the branch is set to `gh-pages` (NOT `main`)
3. Wait 5 minutes and check Actions again
4. The issue usually resolves after you verify the gh-pages branch is set
---
## Local Build Issues
### Docker build fails
**Problem:** `docker compose up` fails or shows errors.
**Solution:**
1. Update Docker: `docker compose pull`
2. Rebuild: `docker compose up --build`
3. If still failing, check your system resources (disk space, RAM)
4. For M1/M2 Mac users, verify you're using a compatible Docker version
5. Check Docker Desktop is running
**For permission issues:**
- Linux users may need to add your user to the docker group: `sudo usermod -aG docker $USER`
- Then log out and log back in
---
### Ruby dependency issues
**Problem:** `Gemfile.lock` conflicts or bundle errors.
**Solution:**
1. Delete `Gemfile.lock`: `rm Gemfile.lock`
2. Update Bundler: `bundle update`
3. Install gems: `bundle install`
4. Try serving again: `bundle exec jekyll serve`
---
### Port already in use
**Problem:** "Address already in use" when running `jekyll serve`.
**Solution - Docker:**
```bash
docker compose down # Stop the running container
docker compose up # Start fresh
```
**Solution - Local Ruby:**
```bash
# Find and kill the Jekyll process
lsof -i :4000 | grep LISTEN | awk '{print $2}' | xargs kill
# Or specify a different port
bundle exec jekyll serve --port 5000
```
---
## Styling & Layout Problems
### CSS and JS not loading properly
**Problem:** Site looks broken: no colors, fonts wrong, links don't work.
**Common cause:** Incorrect `url` and `baseurl` in `_config.yml`.
**Solution:**
1. **Personal/organization site:**
```yaml
url: https://username.github.io
baseurl: # MUST be empty (not deleted)
```
2. **Project site:**
```yaml
url: https://username.github.io
baseurl: /repository-name/ # Must match your repo name
```
3. **Clear browser cache:**
- Chrome: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
- Firefox: `Ctrl+F5` (Windows/Linux) or `Cmd+R` (Mac)
- Or open a private/incognito window
4. Redeploy: Make a small change and push to trigger GitHub Actions again
---
### Site looks broken after deployment
**Checklist:**
- [ ] Is `baseurl` correct (and not accidentally deleted)?
- [ ] Did you clear your browser cache?
- [ ] Wait 5 minutes for GitHub Pages to update
- [ ] Check GitHub Actions completed successfully
---
### Theme colors not applying
**Problem:** You changed `_config.yml` color settings but nothing changed.
**Solution:**
1. Check your color name is valid in `_sass/_variables.scss`
2. Clear browser cache (see above)
3. Rebuild: `docker compose up --build` (Docker) or `bundle exec jekyll build` (Ruby)
4. Wait for GitHub Actions to complete
5. Visit the site in a private/incognito window
---
## Content Not Appearing
### Blog posts not showing up
**Problem:** Created a post in `_posts/` but it's not on the blog page.
**Checklist:**
- [ ] Filename format is correct: `YYYY-MM-DD-title.md` (e.g., `2024-01-15-my-post.md`)
- [ ] File is in the `_posts/` directory (not in a subdirectory)
- [ ] Post has required frontmatter:
```markdown
---
layout: post
title: My Post Title
date: 2024-01-15
---
```
- [ ] Post date is NOT in the future (Jekyll doesn't publish future-dated posts by default)
- [ ] Blog posts are enabled in `_config.yml`: `blog_page: true`
**To fix:**
1. Check the filename format (uppercase, dashes, no spaces)
2. Verify the date is today or in the past
3. Rebuild: `bundle exec jekyll build` and check for error messages
---
### Publications not displaying
**Problem:** You added a BibTeX entry to `papers.bib` but it's not showing on the publications page.
**Checklist:**
- [ ] File is at `_bibliography/papers.bib`
- [ ] BibTeX syntax is correct (check for missing commas, unmatched braces)
- [ ] Entry has a unique citation key: `@article{einstein1905, ...}`
- [ ] Publication page is enabled: Check `publications_page: true` in `_config.yml`
**To debug BibTeX errors:**
```bash
# Local Ruby setup
bundle exec jekyll build 2>&1 | grep -i bibtex
# Docker
docker compose run --rm web jekyll build 2>&1 | grep -i bibtex
```
---
### Images not loading
**Problem:** Image paths broken or showing as missing.
**Common causes:**
- Wrong path in Markdown (use relative paths)
- Image file doesn't exist at the specified location
- Case sensitivity (Linux/Mac are case-sensitive)
**Solutions:**
1. **Correct path format:**
```markdown
![Alt text](assets/img/image-name.jpg)
```
2. **Check the file exists:**
- Personal images: `assets/img/`
- Paper PDFs: `assets/pdf/`
- Use lowercase filenames, no spaces
3. **For BibTeX PDF links:**
```bibtex
@article{mykey,
pdf={my-paper.pdf}, % File should be at assets/pdf/my-paper.pdf
}
```
---
## Configuration Issues
### YAML syntax errors
**Problem:** GitHub Actions fails with YAML error, or build is silent.
**Common mistakes:**
```yaml
# ❌ Wrong: Unquoted colons or ampersands
title: My Site: Research & Teaching
# ✅ Correct: Quote special characters
title: "My Site: Research & Teaching"
```
```yaml
# ❌ Wrong: Inconsistent indentation
nav:
- name: Home
url: /
- name: About # Extra space!
url: /about/
# ✅ Correct: Consistent 2-space indentation
nav:
- name: Home
url: /
- name: About
url: /about/
```
**To find errors:**
1. Use a YAML validator: [yamllint.com](https://www.yamllint.com/)
2. Run locally: `bundle exec jekyll build` shows the exact error line
3. Check that you didn't delete required lines (like `baseurl:`)
---
### Feed (RSS/Atom) not working
**Problem:** RSS feed at `/feed.xml` is empty or broken.
**Solution:**
1. Verify required `_config.yml` fields:
```yaml
title: Your Site Title
description: Brief description
url: https://your-domain.com # MUST be absolute URL
```
2. Ensure `baseurl` is correct
3. Check at least one blog post exists (with correct date)
4. Rebuild and wait for GitHub Actions to complete
---
### Search not working
**Problem:** Search box is empty or always returns nothing.
**Solution:**
1. Ensure search is enabled in `_config.yml`:
```yaml
search_enabled: true
```
2. Check that `_config.yml` has a valid `url` (required for search)
3. Rebuild the site
4. Search index is generated during build; give it a minute after push
---
## Feature-Specific Issues
### Comments (Giscus) not appearing
**Problem:** You enabled Giscus in `_config.yml` but comments don't show.
**Solution:**
1. Verify you have a GitHub repository for discussions (usually your main repo)
2. Check `_config.yml` has correct settings:
```yaml
disqus_shortname: false # Make sure this is false
giscus:
repo: username/repo-name
repo_id: YOUR_REPO_ID
category_id: YOUR_CATEGORY_ID
```
3. Visit [Giscus.app](https://giscus.app) to get your IDs and verify setup
4. Check the GitHub repo has Discussions enabled (Settings → Features)
---
### Related posts broken
**Problem:** Related posts feature crashes or shows errors.
**Solution:**
1. Related posts requires more gems. If you disabled it in `_config.yml`, that's fine:
```yaml
related_blog_posts:
enabled: false
```
2. If you want to enable it, ensure `Gemfile` has all dependencies installed:
```bash
bundle install
bundle exec jekyll build
```
---
### Code formatting issues
**Problem:** Code blocks don't have syntax highlighting or look wrong.
**Solution:**
1. Use proper markdown syntax:
````markdown
```python
# Your code here
print("hello")
```
````
2. For inline code:
```markdown
Use `code-here` for inline code.
```
3. Check that your language is supported by Pygments (Python, Ruby, JavaScript, etc. are all supported)
---
## Getting Help
If you're stuck:
1. **Check existing documentation:**
- [QUICKSTART.md](QUICKSTART.md) – Get started in 5 minutes
- [INSTALL.md](INSTALL.md) – Installation and deployment
- [CUSTOMIZE.md](CUSTOMIZE.md) – Full customization guide
- [FAQ.md](FAQ.md) – Frequently asked questions
2. **Search for your issue:**
- [GitHub Discussions](https://github.com/alshedivat/al-folio/discussions) – Q&A from community
- [GitHub Issues](https://github.com/alshedivat/al-folio/issues) – Bug reports and feature requests
3. **Get help from AI:**
- Use the **GitHub Copilot Customization Agent** (requires Copilot subscription) to get step-by-step help
- See [CUSTOMIZE.md § GitHub Copilot Customization Agent](CUSTOMIZE.md#github-copilot-customization-agent)
4. **Create a new discussion:**
- [Ask a question](https://github.com/alshedivat/al-folio/discussions/new?category=q-a) on GitHub
- Include error messages and what you're trying to do
---
**Most issues are resolved by:**
1. Checking `url` and `baseurl` in `_config.yml`
2. Clearing browser cache
3. Waiting for GitHub Actions to complete (~5 minutes)

168
_bibliography/papers.bib
View File

@ -4,112 +4,112 @@
@string{aps = {American Physical Society,}}
@book{einstein1920relativity,
title={Relativity: the Special and General Theory},
author={Einstein, Albert},
year={1920},
publisher={Methuen & Co Ltd},
html={relativity.html}
title = {Relativity: the Special and General Theory},
author = {Einstein, Albert},
year = {1920},
publisher = {Methuen & Co Ltd},
html = {relativity.html}
}
@book{einstein1956investigations,
bibtex_show={true},
title={Investigations on the Theory of the Brownian Movement},
author={Einstein, Albert},
year={1956},
publisher={Courier Corporation},
preview={brownian-motion.gif}
bibtex_show = {true},
title = {Investigations on the Theory of the Brownian Movement},
author = {Einstein, Albert},
year = {1956},
publisher = {Courier Corporation},
preview = {brownian-motion.gif}
}
@article{einstein1950meaning,
abbr={AJP},
bibtex_show={true},
title={The meaning of relativity},
author={Einstein, Albert and Taub, AH},
journal={American Journal of Physics},
volume={18},
number={6},
pages={403--404},
year={1950},
publisher={American Association of Physics Teachers}
abbr = {AJP},
bibtex_show = {true},
title = {The meaning of relativity},
author = {Einstein, Albert and Taub, AH},
journal = {American Journal of Physics},
volume = {18},
number = {6},
pages = {403--404},
year = {1950},
publisher = {American Association of Physics Teachers}
}
@article{PhysRev.47.777,
abbr={PhysRev},
title={Can Quantum-Mechanical Description of Physical Reality Be Considered Complete?},
author={Einstein*†, A. and Podolsky*, B. and Rosen*, N.},
abstract={In a complete theory there is an element corresponding to each element of reality. A sufficient condition for the reality of a physical quantity is the possibility of predicting it with certainty, without disturbing the system. In quantum mechanics in the case of two physical quantities described by non-commuting operators, the knowledge of one precludes the knowledge of the other. Then either (1) the description of reality given by the wave function in quantum mechanics is not complete or (2) these two quantities cannot have simultaneous reality. Consideration of the problem of making predictions concerning a system on the basis of measurements made on another system that had previously interacted with it leads to the result that if (1) is false then (2) is also false. One is thus led to conclude that the description of reality as given by a wave function is not complete.},
journal={Phys. Rev.},
location={New Jersey},
volume={47},
issue={10},
pages={777--780},
numpages={0},
year={1935},
month={May},
publisher=aps,
doi={10.1103/PhysRev.47.777},
url={http://link.aps.org/doi/10.1103/PhysRev.47.777},
html={https://journals.aps.org/pr/abstract/10.1103/PhysRev.47.777},
pdf={example_pdf.pdf},
altmetric={248277},
dimensions={true},
google_scholar_id={qyhmnyLat1gC},
video={https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ},
additional_info={. *More Information* can be [found here](https://github.com/alshedivat/al-folio/)},
annotation={* Example use of superscripts<br>† Albert Einstein},
selected={true},
abbr = {PhysRev},
title = {Can Quantum-Mechanical Description of Physical Reality Be Considered Complete?},
author = {Einstein*†, A. and Podolsky*, B. and Rosen*, N.},
abstract = {In a complete theory there is an element corresponding to each element of reality. A sufficient condition for the reality of a physical quantity is the possibility of predicting it with certainty, without disturbing the system. In quantum mechanics in the case of two physical quantities described by non-commuting operators, the knowledge of one precludes the knowledge of the other. Then either (1) the description of reality given by the wave function in quantum mechanics is not complete or (2) these two quantities cannot have simultaneous reality. Consideration of the problem of making predictions concerning a system on the basis of measurements made on another system that had previously interacted with it leads to the result that if (1) is false then (2) is also false. One is thus led to conclude that the description of reality as given by a wave function is not complete.},
journal = {Phys. Rev.},
location = {New Jersey},
volume = {47},
issue = {10},
pages = {777--780},
numpages = {0},
year = {1935},
month = {May},
publisher = aps,
doi = {10.1103/PhysRev.47.777},
url = {https://link.aps.org/doi/10.1103/PhysRev.47.777},
html = {https://journals.aps.org/pr/abstract/10.1103/PhysRev.47.777},
pdf = {example_pdf.pdf},
altmetric = {248277},
dimensions = {true},
google_scholar_id = {qyhmnyLat1gC},
video = {https://www.youtube-nocookie.com/embed/aqz-KE-bpKQ},
additional_info = {. *More Information* can be [found here](https://github.com/alshedivat/al-folio/)},
annotation = {* Example use of superscripts<br>† Albert Einstein},
selected = {true},
inspirehep_id = {3255}
}
@article{einstein1905molekularkinetischen,
title={{\"U}ber die von der molekularkinetischen Theorie der W{\"a}rme geforderte Bewegung von in ruhenden Fl{\"u}ssigkeiten suspendierten Teilchen},
author={Einstein, A.},
journal={Annalen der physik},
volume={322},
number={8},
pages={549--560},
year={1905},
publisher={Wiley Online Library}
title = {{\"U}ber die von der molekularkinetischen Theorie der W{\"a}rme geforderte Bewegung von in ruhenden Fl{\"u}ssigkeiten suspendierten Teilchen},
author = {Einstein, A.},
journal = {Annalen der physik},
volume = {322},
number = {8},
pages = {549--560},
year = {1905},
publisher = {Wiley Online Library}
}
@article{einstein1905movement,
abbr={Ann. Phys.},
title={Un the movement of small particles suspended in statiunary liquids required by the molecular-kinetic theory 0f heat},
author={Einstein, A.},
journal={Ann. Phys.},
volume={17},
pages={549--560},
year={1905}
abbr = {Ann. Phys.},
title = {Un the movement of small particles suspended in statiunary liquids required by the molecular-kinetic theory 0f heat},
author = {Einstein, A.},
journal = {Ann. Phys.},
volume = {17},
pages = {549--560},
year = {1905}
}
@article{einstein1905electrodynamics,
title={On the electrodynamics of moving bodies},
author={Einstein, A.},
year={1905}
title = {On the electrodynamics of moving bodies},
author = {Einstein, A.},
year = {1905}
}
@Article{einstein1905photoelectriceffect,
bibtex_show={true},
abbr={Ann. Phys.},
title="{{\"U}ber einen die Erzeugung und Verwandlung des Lichtes betreffenden heuristischen Gesichtspunkt}",
author={Albert Einstein},
abstract={This is the abstract text.},
journal={Ann. Phys.},
volume={322},
number={6},
pages={132--148},
year={1905},
doi={10.1002/andp.19053220607},
award={Albert Einstein receveid the **Nobel Prize in Physics** 1921 *for his services to Theoretical Physics, and especially for his discovery of the law of the photoelectric effect*},
award_name={Nobel Prize}
@article{einstein1905photoelectriceffect,
bibtex_show = {true},
abbr = {Ann. Phys.},
title = {{{\"U}ber einen die Erzeugung und Verwandlung des Lichtes betreffenden heuristischen Gesichtspunkt}},
author = {Albert Einstein},
abstract = {This is the abstract text.},
journal = {Ann. Phys.},
volume = {322},
number = {6},
pages = {132--148},
year = {1905},
doi = {10.1002/andp.19053220607},
award = {Albert Einstein receveid the **Nobel Prize in Physics** 1921 *for his services to Theoretical Physics, and especially for his discovery of the law of the photoelectric effect*},
award_name = {Nobel Prize}
}
@book{przibram1967letters,
bibtex_show={true},
title={Letters on wave mechanics},
author={Einstein, Albert and Schrödinger, Erwin and Planck, Max and Lorentz, Hendrik Antoon and Przibram, Karl},
year={1967},
publisher={Vision},
preview={wave-mechanics.gif},
abbr={Vision}
bibtex_show = {true},
title = {Letters on wave mechanics},
author = {Einstein, Albert and Schrödinger, Erwin and Planck, Max and Lorentz, Hendrik Antoon and Przibram, Karl},
year = {1967},
publisher = {Vision},
preview = {wave-mechanics.gif},
abbr = {Vision}
}

2
_includes/disqus.liquid
View File

@ -9,5 +9,5 @@
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
</div>

8
_includes/head.liquid
View File

@ -1,6 +1,14 @@
<!-- Metadata, OpenGraph and Schema.org -->
{% include metadata.liquid %}
<!-- Security: Content Security Policy -->
<!-- Permissive CSP suitable for academic websites. Allows external images, videos, and common embed services. -->
<!-- To customize for your needs, see: https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
<meta
http-equiv="Content-Security-Policy"
content="default-src 'self'; script-src 'self' 'unsafe-inline' https:; style-src 'self' 'unsafe-inline' https:; img-src 'self' data: https:; font-src 'self' data: https:; media-src 'self' https:; frame-src 'self' https:; connect-src 'self' https:;"
>
<!-- Bootstrap & MDB -->
<link rel="stylesheet" href="{{ '/assets/css/bootstrap.min.css' | relative_url | bust_file_cache }}">
<link

16
_layouts/book-review.liquid
View File

@ -110,12 +110,20 @@ layout: default
Cover of <em>{{ page.title }}</em>
</figcaption>
{% elsif page.olid %}
<img class="empty-review-cover" alt="{{ page.title }} cover" src="http://covers.openlibrary.org/b/olid/{{ page.olid }}-L.jpg?default=false">
<img
class="empty-review-cover"
alt="{{ page.title }} cover"
src="https://covers.openlibrary.org/b/olid/{{ page.olid }}-L.jpg?default=false"
>
<figcaption class="empty-review-caption">
Cover of <em>{{ page.title }}</em> on the <a href="https://openlibrary.org/olid/{{ page.olid }}">Open Library</a>.
</figcaption>
{% elsif page.isbn %}
<img class="empty-review-cover" alt="{{ page.title }} cover" src="http://covers.openlibrary.org/b/isbn/{{ page.isbn }}-L.jpg?default=false">
<img
class="empty-review-cover"
alt="{{ page.title }} cover"
src="https://covers.openlibrary.org/b/isbn/{{ page.isbn }}-L.jpg?default=false"
>
<figcaption class="empty-review-caption">
Cover of <em>{{ page.title }}</em> on the <a href="https://openlibrary.org/isbn/{{ page.isbn }}">Open Library</a>.
</figcaption>
@ -133,12 +141,12 @@ layout: default
Cover of <em>{{ page.title }}</em>
</figcaption>
{% elsif page.olid %}
<img alt="{{ page.title }} cover" src="http://covers.openlibrary.org/b/olid/{{ page.olid }}-L.jpg?default=false">
<img alt="{{ page.title }} cover" src="https://covers.openlibrary.org/b/olid/{{ page.olid }}-L.jpg?default=false">
<figcaption>
Cover of <em>{{ page.title }}</em> on the <a href="https://openlibrary.org/olid/{{ page.olid }}">Open Library</a>.
</figcaption>
{% elsif page.isbn %}
<img alt="{{ page.title }} cover" src="http://covers.openlibrary.org/b/isbn/{{ page.isbn }}-L.jpg?default=false">
<img alt="{{ page.title }} cover" src="https://covers.openlibrary.org/b/isbn/{{ page.isbn }}-L.jpg?default=false">
<figcaption>
Cover of <em>{{ page.title }}</em> on the <a href="https://openlibrary.org/isbn/{{ page.isbn }}">Open Library</a>.
</figcaption>

4
_layouts/book-shelf.liquid
View File

@ -24,9 +24,9 @@ layout: page
{% if item.cover %}
<img alt="{{ item.title }} cover" src="{{ item.cover | prepend: page.covers | relative_url }}" style="height:200px">
{% elsif item.olid %}
<img alt="{{ item.title }} cover" src="http://covers.openlibrary.org/b/olid/{{ item.olid }}-L.jpg?default=false" style="height:200px">
<img alt="{{ item.title }} cover" src="https://covers.openlibrary.org/b/olid/{{ item.olid }}-L.jpg?default=false" style="height:200px">
{% elsif item.isbn %}
<img alt="{{ item.title }} cover" src="http://covers.openlibrary.org/b/isbn/{{ item.isbn }}-L.jpg?default=false" style="height:200px">
<img alt="{{ item.title }} cover" src="https://covers.openlibrary.org/b/isbn/{{ item.isbn }}-L.jpg?default=false" style="height:200px">
{% endif %}
{% if item.status %}
{% assign statuses = 'abandoned,finished,interested,paused,queued,reading,reread' | split: ',' %}

2
_plugins/details.rb
View File

@ -1,4 +1,4 @@
# Code from http://movb.de/jekyll-details-support.html
# Code from https://movb.de/jekyll-details-support.html
module Jekyll
module Tags

2
_posts/2015-10-20-math.md
View File

@ -26,4 +26,4 @@ MathJax will automatically number equations:
and by adding `\label{...}` inside the equation environment, we can now refer to the equation using `\eqref`.
Note that MathJax 3 is [a major re-write of MathJax](https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html) that brought a significant improvement to the loading and rendering speed, which is now [on par with KaTeX](http://www.intmath.com/cg5/katex-mathjax-comparison.php).
Note that MathJax 3 is [a major re-write of MathJax](https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html) that brought a significant improvement to the loading and rendering speed, which is now [on par with KaTeX](https://www.intmath.com/cg5/katex-mathjax-comparison.php).

8
_posts/2018-12-22-distill.md
View File

@ -93,7 +93,7 @@ $$
\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)
$$
Note that MathJax 3 is [a major re-write of MathJax](https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html) that brought a significant improvement to the loading and rendering speed, which is now [on par with KaTeX](http://www.intmath.com/cg5/katex-mathjax-comparison.php).
Note that MathJax 3 is [a major re-write of MathJax](https://docs.mathjax.org/en/latest/upgrading/whats-new-3.0.html) that brought a significant improvement to the loading and rendering speed, which is now [on par with KaTeX](https://www.intmath.com/cg5/katex-mathjax-comparison.php).
---
@ -1433,14 +1433,14 @@ Strikethrough uses two tildes. ~~Scratch this.~~
Or leave it empty and use the [link text itself].
URLs and URLs in angle brackets will automatically get turned into links.
http://www.example.com or <http://www.example.com> and sometimes
https://www.example.com or <https://www.example.com> and sometimes
example.com (but not on Github, for example).
Some text to show that the reference links can follow later.
[arbitrary case-insensitive reference text]: https://www.mozilla.org
[1]: http://slashdot.org
[link text itself]: http://www.reddit.com
[1]: https://slashdot.org
[link text itself]: https://www.reddit.com
Here's our logo (hover to see the title text):

7
_sass/_layout.scss
View File

@ -40,13 +40,16 @@ body.sticky-bottom-footer {
}
}
// TODO: redefine content layout.
// Content layout uses Bootstrap's grid system with responsive columns
// Main content flows naturally through container-mt-5 and Bootstrap grid classes
// See _layouts/default.liquid and _includes/projects.liquid for examples
/******************************************************************************
* Publications
******************************************************************************/
// TODO: redefine publications layout.
// Publications layout is defined in _includes/bib_search.liquid
// Uses jekyll-scholar for BibTeX parsing and Bootstrap cards for display
/*****************************************************************************
* Projects

2
_scripts/search.liquid.js
View File

@ -182,7 +182,7 @@ ninja.data = [
{%- when "lattes_id" -%}
{%- assign social_id = "social-lattes" -%}
{%- assign social_title = "Lattes" -%}
{%- capture social_url %}"http://lattes.cnpq.br/{{ social[1] }}"{% endcapture -%}
{%- capture social_url %}"https://lattes.cnpq.br/{{ social[1] }}"{% endcapture -%}
{%- when "leetcode_id" -%}
{%- assign social_id = "social-leetcode" -%}
{%- assign social_title = "LeetCode" -%}