Added copilot instructions, AGENTS.md, improved README files (#3486)
This pull request introduces several documentation improvements and adds comprehensive Copilot and agent instruction files to the al-folio repository. The most significant changes are the addition of repository-wide and path-specific Copilot instructions, updates to agent documentation to reference these instructions, and improvements to the documentation structure and clarity regarding file purposes and workflows. **Copilot and Agent Instruction Enhancements:** - Added a new `.github/copilot-instructions.md` file providing detailed, repository-wide setup, build, CI/CD, troubleshooting, and file format guidance for Copilot coding agents. - Introduced `.github/instructions/bibtex-bibliography.instructions.md` with specific instructions for editing and validating BibTeX files, including custom keywords, formatting rules, and integration with Jekyll-Scholar. - Updated agent documentation files (`customize.agent.md`, `docs.agent.md`) to reference the new Copilot instruction files and explain their purpose and usage for both repository-wide and path-specific scenarios. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[2]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L107-R122) [[3]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51) [[4]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137) **Documentation Structure and Clarity Improvements:** - Clarified and reorganized the documentation file list in agent files, removing references to deprecated or merged files (e.g., `MAINTENANCE.md`, `ACCESSIBILITY.md`) and updating descriptions to reflect current usage. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L21-R21) [[3]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137) - Enhanced documentation on the purpose and application of each documentation file, and added detailed explanations of Copilot instruction files and their role in project development. **Workflow and Validation Updates:** - Updated references and descriptions for GitHub Actions workflows in agent documentation to include the Copilot environment setup and clarify pre-commit and CI/CD requirements. [[1]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[2]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51) - Corrected references for accessibility guidance, now directing users to `TROUBLESHOOTING.md` instead of the removed `ACCESSIBILITY.md`. These changes collectively improve the onboarding experience for both human contributors and AI agents, ensuring consistent adherence to project conventions and reducing errors. **References:** [[1]](diffhunk://#diff-227c2c26cb2ee0ce0f46a320fc48fbcbdf21801a57f59161b1d0861e8aad55f5R1-R253) [[2]](diffhunk://#diff-6fd2827fb8d9c2dd6dc973572201853487ecbbd1120b00425d4f1c21dfdcf35fR1-R174) [[3]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L57-R65) [[4]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L107-R122) [[5]](diffhunk://#diff-15864f2655921f50a97689076e3b8feba0da320463750845be6a76eb2e30bfe4L550-R562) [[6]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L21-R21) [[7]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L49-R51) [[8]](diffhunk://#diff-961a46180ce568ce43c20bf7129dc5e4926a9aa4e0d7bc19926ca5ee3ff95cd0L106-R137) --------- Signed-off-by: George Araújo <george.gcac@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
This commit is contained in:
George
GitHub
parent
6eeea92254
commit
25b758805c
28
.github/agents/customize.agent.md
vendored
28
.github/agents/customize.agent.md
vendored
@ -54,14 +54,15 @@ You are an expert customization assistant for the al-folio Jekyll academic websi
|
|||||||
- `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content
|
- `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content
|
||||||
- `.devcontainer/` – Development container configuration for VS Code
|
- `.devcontainer/` – Development container configuration for VS Code
|
||||||
- `.github/` – GitHub-specific configuration:
|
- `.github/` – GitHub-specific configuration:
|
||||||
- `.github/workflows/` – GitHub Actions for deployment, CI/CD, CV PDF generation, link checking, code quality
|
- `.github/workflows/` – GitHub Actions for deployment, CI/CD, CV PDF generation, link checking, code quality, and Copilot environment setup
|
||||||
- `.github/agents/` – AI agent configuration files
|
- `.github/agents/` – AI agent configuration files
|
||||||
|
- `.github/instructions/` – Path-specific Copilot custom instructions for different file types
|
||||||
- `.github/ISSUE_TEMPLATE/` – GitHub issue templates
|
- `.github/ISSUE_TEMPLATE/` – GitHub issue templates
|
||||||
- `.pre-commit-config.yaml` – Pre-commit hooks configuration
|
- `.pre-commit-config.yaml` – Pre-commit hooks configuration
|
||||||
- `bin/` – Executable scripts and utilities
|
- `bin/` – Executable scripts and utilities
|
||||||
- `package.json`, `purgecss.config.js` – Node.js dependencies and build tools
|
- `package.json`, `purgecss.config.js` – Node.js dependencies and build tools
|
||||||
- `Gemfile`, `Gemfile.lock`, `.ruby-version` – Ruby dependencies and version
|
- `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`
|
- Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `QUICKSTART.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md`
|
||||||
- `robots.txt` – SEO and crawler configuration
|
- `robots.txt` – SEO and crawler configuration
|
||||||
- `Dockerfile`, `docker-compose.yml`, `docker-compose-slim.yml` – Docker configuration
|
- `Dockerfile`, `docker-compose.yml`, `docker-compose-slim.yml` – Docker configuration
|
||||||
|
|
||||||
@ -104,10 +105,21 @@ You have access to the complete documentation for al-folio:
|
|||||||
5. **FAQ.md** – Frequently asked questions and common solutions
|
5. **FAQ.md** – Frequently asked questions and common solutions
|
||||||
6. **TROUBLESHOOTING.md** – Troubleshooting guide for common issues
|
6. **TROUBLESHOOTING.md** – Troubleshooting guide for common issues
|
||||||
7. **CONTRIBUTING.md** – Guidelines for contributing to the project
|
7. **CONTRIBUTING.md** – Guidelines for contributing to the project
|
||||||
8. **MAINTENANCE.md** – Maintenance notes for maintainers
|
|
||||||
9. **ACCESSIBILITY.md** – Accessibility standards and features
|
8. **ANALYTICS.md** – Analytics and tracking configuration
|
||||||
10. **ANALYTICS.md** – Analytics and tracking configuration
|
9. **SEO.md** – Search engine optimization guide
|
||||||
11. **SEO.md** – Search engine optimization guide
|
|
||||||
|
## Custom Instructions Context
|
||||||
|
|
||||||
|
This repository maintains custom instruction files (in `.github/instructions/` and `.github/copilot-instructions.md`) to guide Copilot agents when working with specific file types. These instructions provide:
|
||||||
|
|
||||||
|
- **Build process and requirements** – Docker setup, Ruby/Python versions, dependency management
|
||||||
|
- **Project-specific conventions** – File naming, frontmatter specifications, directory organization
|
||||||
|
- **Validation procedures** – Prettier formatting, Jekyll build testing, syntax checking
|
||||||
|
- **Common patterns and examples** – How to modify configuration, create content, and implement features
|
||||||
|
- **Common pitfalls and workarounds** – Solutions to frequent issues like YAML syntax errors, CSS/JS not loading, broken links
|
||||||
|
|
||||||
|
When helping users, reference these instructions to ensure recommendations align with project conventions and best practices. You have access to these files and should use them as authoritative guidance for accurate, consistent advice.
|
||||||
|
|
||||||
## Commands You Can Use
|
## Commands You Can Use
|
||||||
|
|
||||||
@ -547,7 +559,7 @@ Help users avoid these frequent errors:
|
|||||||
| Add custom page | Create `_pages/name.md`, update nav | CUSTOMIZE.md § Creating pages |
|
| Add custom page | Create `_pages/name.md`, update nav | CUSTOMIZE.md § Creating pages |
|
||||||
| Customize fonts/spacing | `_sass/_variables.scss` | CUSTOMIZE.md § Customization |
|
| Customize fonts/spacing | `_sass/_variables.scss` | CUSTOMIZE.md § Customization |
|
||||||
| Improve SEO | `_config.yml`, `robots.txt` | SEO.md |
|
| Improve SEO | `_config.yml`, `robots.txt` | SEO.md |
|
||||||
| Ensure accessibility | Check markup, alt text, contrast | ACCESSIBILITY.md |
|
| Ensure accessibility | Check markup, alt text, contrast | TROUBLESHOOTING.md |
|
||||||
|
|
||||||
## Using Community Context in Your Responses
|
## Using Community Context in Your Responses
|
||||||
|
|
||||||
|
|||||||
43
.github/agents/docs.agent.md
vendored
43
.github/agents/docs.agent.md
vendored
@ -18,7 +18,7 @@ You are a documentation specialist for the al-folio Jekyll theme project.
|
|||||||
- **Key Dependencies:** jekyll-scholar, jekyll-archives-v2, jekyll-paginate-v2, MathJax, Bootstrap, Prettier, pre-commit hooks
|
- **Key Dependencies:** jekyll-scholar, jekyll-archives-v2, jekyll-paginate-v2, MathJax, Bootstrap, Prettier, pre-commit hooks
|
||||||
- **File Structure:**
|
- **File Structure:**
|
||||||
- `_config.yml` – Main Jekyll configuration file
|
- `_config.yml` – Main Jekyll configuration file
|
||||||
- `*.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`
|
- `*.md` (root) – Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `QUICKSTART.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md`
|
||||||
- `_pages/` – Website pages (Markdown with frontmatter)
|
- `_pages/` – Website pages (Markdown with frontmatter)
|
||||||
- `_posts/` – Blog posts
|
- `_posts/` – Blog posts
|
||||||
- `_projects/`, `_news/`, `_books/`, `_teachings/` – Jekyll collections
|
- `_projects/`, `_news/`, `_books/`, `_teachings/` – Jekyll collections
|
||||||
@ -46,8 +46,9 @@ You are a documentation specialist for the al-folio Jekyll theme project.
|
|||||||
- `assets/bibliography/`, `assets/libs/` – Support files
|
- `assets/bibliography/`, `assets/libs/` – Support files
|
||||||
- `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content
|
- `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content
|
||||||
- `.github/` – GitHub configuration:
|
- `.github/` – GitHub configuration:
|
||||||
- `.github/workflows/` – GitHub Actions (deployment, CI/CD, CV PDF generation, link checking, code quality)
|
- `.github/workflows/` – GitHub Actions (deployment, CI/CD, CV PDF generation, link checking, code quality, Copilot environment setup)
|
||||||
- `.github/agents/` – AI agent configuration files
|
- `.github/agents/` – AI agent configuration files (customize.agent.md, docs.agent.md)
|
||||||
|
- `.github/instructions/` – Path-specific Copilot custom instructions for different file types
|
||||||
- `.github/ISSUE_TEMPLATE/` – GitHub issue templates
|
- `.github/ISSUE_TEMPLATE/` – GitHub issue templates
|
||||||
- `_scripts/` – Helper scripts and utilities
|
- `_scripts/` – Helper scripts and utilities
|
||||||
- `bin/` – Executable scripts
|
- `bin/` – Executable scripts
|
||||||
@ -103,11 +104,37 @@ You are a documentation specialist for the al-folio Jekyll theme project.
|
|||||||
|
|
||||||
## Documentation file purposes
|
## Documentation file purposes
|
||||||
|
|
||||||
- `README.md` – Project overview, features showcase, quick start links
|
- `ANALYTICS.md` – Analytics and tracking configuration options
|
||||||
- `INSTALL.md` – Installation and deployment instructions (Docker, GitHub Pages, local setup)
|
- `CONTRIBUTING.md` – Guidelines for contributors and development
|
||||||
- `CUSTOMIZE.md` – Customization guide (configuration, adding content, styling)
|
- `CUSTOMIZE.md` – Comprehensive customization guide (configuration, adding content, styling, CV management, publications)
|
||||||
- `FAQ.md` – Frequently asked questions and troubleshooting
|
- `FAQ.md` – Frequently asked questions and common issues
|
||||||
- `CONTRIBUTING.md` – Guidelines for contributors
|
- `INSTALL.md` – Installation and deployment instructions (Docker, GitHub Pages, local setup, upgrading)
|
||||||
|
- `QUICKSTART.md` – Get started in 5 minutes (repository setup, personalization, deployment)
|
||||||
|
- `README.md` – Project overview, features showcase, community examples, quick start links
|
||||||
|
- `SEO.md` – Search engine optimization guide
|
||||||
|
- `TROUBLESHOOTING.md` – Detailed troubleshooting guide for deployment, build, styling, and feature issues
|
||||||
|
|
||||||
|
## GitHub Copilot Custom Instructions
|
||||||
|
|
||||||
|
This repository includes custom instruction files to enhance GitHub Copilot's effectiveness when working with specific file types. These files are located in `.github/instructions/` and `.github/copilot-instructions.md`:
|
||||||
|
|
||||||
|
**Main Instructions:**
|
||||||
|
|
||||||
|
- `.github/copilot-instructions.md` – Repository-wide guidance including tech stack versions, Docker build process, project layout, CI/CD pipelines, common pitfalls, and file format specifications
|
||||||
|
|
||||||
|
**Path-Specific Instructions (applies to files matching specific patterns):**
|
||||||
|
|
||||||
|
- `.github/instructions/liquid-templates.instructions.md` (applies to `**/*.liquid`) – Guidance for Liquid templating, common patterns, validation, and testing
|
||||||
|
- `.github/instructions/yaml-configuration.instructions.md` (applies to `_config.yml,_data/**/*.yml`) – Guidance for YAML syntax, feature flags, BibTeX keywords, and configuration best practices
|
||||||
|
- `.github/instructions/bibtex-bibliography.instructions.md` (applies to `**/*.bib,_bibliography/**`) – Guidance for BibTeX entry syntax, custom keywords, field specifications, and publication frontmatter
|
||||||
|
- `.github/instructions/markdown-content.instructions.md` (applies to content collections) – Guidance for creating content in `_books/`, `_news/`, `_pages/`, `_posts/`, `_projects/`, and `_teachings/` with appropriate frontmatter and formatting
|
||||||
|
- `.github/instructions/javascript-scripts.instructions.md` (applies to `_scripts/**/*.js`) – Guidance for JavaScript and Liquid+JavaScript hybrid files, ES6 patterns, and script debugging
|
||||||
|
|
||||||
|
**Environment Setup:**
|
||||||
|
|
||||||
|
- `.github/workflows/copilot-setup-steps.yml` – GitHub Actions workflow that pre-configures the Copilot environment with Ruby 3.3.5, Python 3.13, Node.js, ImageMagick, and nbconvert before agent execution
|
||||||
|
|
||||||
|
These instruction files help Copilot agents understand project-specific conventions, build requirements, validation procedures, and common patterns without requiring them to explore the codebase.
|
||||||
|
|
||||||
## Writing style
|
## Writing style
|
||||||
|
|
||||||
|
|||||||
253
.github/copilot-instructions.md
vendored
Normal file
253
.github/copilot-instructions.md
vendored
Normal file
@ -0,0 +1,253 @@
|
|||||||
|
# Copilot Coding Agent Instructions
|
||||||
|
|
||||||
|
## Repository Overview
|
||||||
|
|
||||||
|
**al-folio** is a simple, clean, and responsive [Jekyll](https://jekyllrb.com/) theme for academics and researchers. It enables users to create professional portfolio and blog websites with minimal configuration. The repository serves both as a template and as a reference implementation.
|
||||||
|
|
||||||
|
- **Type:** Jekyll static site generator template
|
||||||
|
- **Target Users:** Academics, researchers, and professionals
|
||||||
|
- **Key Features:** CV display, publication bibliography, blog posts, projects, news/announcements, course listings
|
||||||
|
|
||||||
|
## Tech Stack & Versions
|
||||||
|
|
||||||
|
**Core Technologies:**
|
||||||
|
|
||||||
|
- **Jekyll:** v4.x (Ruby static site generator)
|
||||||
|
- **Ruby:** 3.3.5 (primary CI/CD version), 3.2.2 (some workflows)
|
||||||
|
- **Python:** 3.13 (for nbconvert, jupyter notebook support)
|
||||||
|
- **Node.js:** Latest (for purgecss and prettier)
|
||||||
|
- **Docker:** Uses prebuilt image `amirpourmand/al-folio:v0.16.3` (Ruby slim-based)
|
||||||
|
|
||||||
|
**Build Dependencies (from Gemfile):**
|
||||||
|
|
||||||
|
- `classifier-reborn` – Related posts calculation
|
||||||
|
- `jekyll-archives-v2` – Archive page generation
|
||||||
|
- `jekyll-jupyter-notebook` – Jupyter notebook embedding
|
||||||
|
- `jekyll-minifier` – CSS/JS minification
|
||||||
|
- `jekyll-paginate-v2` – Pagination
|
||||||
|
- `jekyll-scholar` – Bibliography management
|
||||||
|
- `jekyll-tabs` – Tab UI components
|
||||||
|
- `jekyll-toc` – Table of contents generation
|
||||||
|
- `jemoji` – Emoji support
|
||||||
|
- Multiple other specialized jekyll plugins
|
||||||
|
|
||||||
|
**Code Quality Tools:**
|
||||||
|
|
||||||
|
- **Prettier:** v3.8.0+ with `@shopify/prettier-plugin-liquid` – Code formatter (mandatory for PRs)
|
||||||
|
- **Purgecss:** CSS purification for production builds
|
||||||
|
|
||||||
|
## Building & Local Development
|
||||||
|
|
||||||
|
### Docker (Recommended Approach)
|
||||||
|
|
||||||
|
**Always use Docker for local development.** This ensures consistency with CI/CD and avoids Ruby/Python environment issues.
|
||||||
|
|
||||||
|
**Initial Setup:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose pull # Pull prebuilt image
|
||||||
|
docker compose up # Start development server
|
||||||
|
# Site runs at http://localhost:8080
|
||||||
|
```
|
||||||
|
|
||||||
|
**Rebuilding with Updated Dependencies:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose up --build # Rebuilds Docker image from Dockerfile
|
||||||
|
docker compose up --force-recreate # Forces complete rebuild
|
||||||
|
```
|
||||||
|
|
||||||
|
**For slim Docker image (if image size is critical):**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose -f docker-compose-slim.yml up
|
||||||
|
```
|
||||||
|
|
||||||
|
**If Docker build fails:**
|
||||||
|
|
||||||
|
- Check disk space and available RAM
|
||||||
|
- Kill any existing jekyll processes: `docker compose down`
|
||||||
|
- For M1/M2 Mac: Ensure Docker Desktop is up-to-date
|
||||||
|
- Linux users may need Docker group permissions: `sudo usermod -aG docker $USER` (then logout/login)
|
||||||
|
|
||||||
|
### Bundle/Jekyll (Legacy, Use Docker Instead)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
bundle install # Install Ruby gems
|
||||||
|
pip install jupyter # Install Python dependencies
|
||||||
|
bundle exec jekyll serve --port 4000 # Run at http://localhost:4000
|
||||||
|
```
|
||||||
|
|
||||||
|
### Important Build Requirements
|
||||||
|
|
||||||
|
- **ImageMagick must be installed** – Required for image processing plugins
|
||||||
|
- Docker: Installed automatically
|
||||||
|
- Local: `sudo apt-get install imagemagick` (Linux) or `brew install imagemagick` (Mac)
|
||||||
|
- **nbconvert must be upgraded before build** – `pip3 install --upgrade nbconvert`
|
||||||
|
- **Always set JEKYLL_ENV=production for production builds** – Required for CSS/JS minification
|
||||||
|
|
||||||
|
## Project Layout & Key Files
|
||||||
|
|
||||||
|
### Root Directory Structure
|
||||||
|
|
||||||
|
- `_bibliography/papers.bib` – BibTeX bibliography for publications
|
||||||
|
- `_config.yml` – **Primary configuration file** (title, author, URLs, baseurl, feature flags)
|
||||||
|
- `_data/` – YAML data files (socials.yml, coauthors.yml, cv.yml, citations.yml, venues.yml, repositories.yml)
|
||||||
|
- `_includes/` – Reusable Liquid template components
|
||||||
|
- `_layouts/` – Page layout templates (about.liquid, post.liquid, bib.liquid, distill.liquid, cv.liquid, etc.)
|
||||||
|
- `_news/` – News/announcement entries
|
||||||
|
- `_pages/` – Static pages (about.md, cv.md, publications.md, projects.md, teaching.md, etc.)
|
||||||
|
- `_posts/` – Blog posts (format: YYYY-MM-DD-title.md)
|
||||||
|
- `_projects/` – Project showcase entries
|
||||||
|
- `_sass/` – SCSS stylesheets
|
||||||
|
- `_scripts/` – JavaScript files for functionality
|
||||||
|
- `_teachings/` – Course and teaching entries
|
||||||
|
- `assets/img/` – Images, profile pictures
|
||||||
|
- `docker-compose.yml` – Docker compose configuration
|
||||||
|
- `Dockerfile` – Docker image definition
|
||||||
|
- `Gemfile` & `Gemfile.lock` – Ruby dependency specifications
|
||||||
|
- `package.json` – Node.js dependencies (prettier only)
|
||||||
|
- `purgecss.config.js` – PurgeCSS configuration for production CSS optimization
|
||||||
|
|
||||||
|
### Configuration Priority
|
||||||
|
|
||||||
|
When making changes:
|
||||||
|
|
||||||
|
1. **Always start with `_config.yml`** for site-wide settings
|
||||||
|
2. **Feature flags are in `_config.yml`** – Look for `enabled: true/false` options
|
||||||
|
3. **Social media links:** `_data/socials.yml`
|
||||||
|
4. **Content data:** Respective `_data/*.yml` files
|
||||||
|
5. **Styling:** `_sass/` directory (uses SCSS)
|
||||||
|
|
||||||
|
## CI/CD Pipeline & Validation
|
||||||
|
|
||||||
|
### GitHub Workflows (in `.github/workflows/`)
|
||||||
|
|
||||||
|
- **deploy.yml** – Main deployment workflow (runs on push/PR to main/master)
|
||||||
|
- Sets up Ruby 3.3.5, Python 3.13
|
||||||
|
- Installs imagemagick, nbconvert
|
||||||
|
- Runs `bundle exec jekyll build` with JEKYLL_ENV=production
|
||||||
|
- Runs purgecss for CSS optimization
|
||||||
|
- Commits built site to gh-pages branch
|
||||||
|
- **Triggers on:** Changes to site files, assets, config (NOT documentation files alone)
|
||||||
|
- **prettier.yml** – Code formatting validation (mandatory)
|
||||||
|
- Runs prettier on all files
|
||||||
|
- **Fails PRs if code is not properly formatted**
|
||||||
|
- Generates HTML diff artifact on failure
|
||||||
|
- Must install prettier locally to avoid failures: `npm install prettier @shopify/prettier-plugin-liquid`
|
||||||
|
- **broken-links.yml, broken-links-site.yml** – Link validation
|
||||||
|
- **axe.yml** – Accessibility testing
|
||||||
|
- **codeql.yml** – Security scanning
|
||||||
|
- **update-citations.yml** – Automatic citation updates
|
||||||
|
- **render-cv.yml** – CV rendering from RenderCV format
|
||||||
|
|
||||||
|
### Pre-commit Requirements
|
||||||
|
|
||||||
|
**You must run these locally before pushing:**
|
||||||
|
|
||||||
|
1. **Prettier formatting (mandatory):**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm install --save-dev prettier @shopify/prettier-plugin-liquid
|
||||||
|
npx prettier . --write
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Local build test with Jekyll:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose pull && docker compose up
|
||||||
|
# Let it build (wait 30-60 seconds)
|
||||||
|
# Visit http://localhost:8080 and verify site renders correctly
|
||||||
|
# Exit with Ctrl+C
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Or run full build simulation:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose up --build
|
||||||
|
bundle exec jekyll build
|
||||||
|
# Check for errors in output
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Pitfalls & Workarounds
|
||||||
|
|
||||||
|
### YAML Syntax Errors in \_config.yml
|
||||||
|
|
||||||
|
- **Problem:** Special characters (`:`, `&`, `#`) in values cause parse errors
|
||||||
|
- **Solution:** Quote string values: `title: "My: Cool Site"`
|
||||||
|
- **Debug:** Run locally to see detailed error: `bundle exec jekyll build`
|
||||||
|
|
||||||
|
### "Unknown tag 'toc'" Error on Deployment
|
||||||
|
|
||||||
|
- **Problem:** Deploy succeeds locally but fails on GitHub Actions
|
||||||
|
- **Cause:** Jekyll plugins don't load properly
|
||||||
|
- **Solution:** Verify gh-pages branch is set as deployment source in Settings → Pages
|
||||||
|
|
||||||
|
### CSS/JS Not Loading After Deploy
|
||||||
|
|
||||||
|
- **Problem:** Site loads but has no styling
|
||||||
|
- **Cause:** Incorrect `url` and `baseurl` in `_config.yml`
|
||||||
|
- **Fix:**
|
||||||
|
- Personal site: `url: https://username.github.io`, `baseurl:` (empty)
|
||||||
|
- Project site: `url: https://username.github.io`, `baseurl: /repo-name/`
|
||||||
|
- Clear browser cache (Ctrl+Shift+Del or private browsing)
|
||||||
|
|
||||||
|
### Prettier Formatting Failures
|
||||||
|
|
||||||
|
- **Problem:** PR fails prettier check after local builds passed
|
||||||
|
- **Solution:** Run prettier before committing:
|
||||||
|
```bash
|
||||||
|
npx prettier . --write
|
||||||
|
git add . && git commit -m "Format code with prettier"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Port 8080 or 4000 Already in Use
|
||||||
|
|
||||||
|
- **Docker:** `docker compose down` then `docker compose up`
|
||||||
|
- **Ruby:** Kill process: `lsof -i :4000 | grep LISTEN | awk '{print $2}' | xargs kill`
|
||||||
|
|
||||||
|
### Related Posts Errors ("Zero vectors cannot be normalized")
|
||||||
|
|
||||||
|
- **Cause:** Empty blog posts or posts with only stop words confuse classifier-reborn
|
||||||
|
- **Solution:** Add meaningful content to posts, or set `related_posts: false` in post frontmatter
|
||||||
|
|
||||||
|
## File Format Specifications
|
||||||
|
|
||||||
|
### Blog Post Frontmatter (\_posts/)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
layout: post
|
||||||
|
title: Post Title
|
||||||
|
date: YYYY-MM-DD
|
||||||
|
categories: category-name
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
### Project Frontmatter (\_projects/)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
layout: page
|
||||||
|
title: Project Name
|
||||||
|
description: Short description
|
||||||
|
img: /assets/img/project-image.jpg
|
||||||
|
importance: 1
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
### BibTeX Format (papers.bib)
|
||||||
|
|
||||||
|
- Standard BibTeX format
|
||||||
|
- al-folio supports custom keywords: `pdf`, `code`, `preview`, `doi`, etc.
|
||||||
|
- Check CUSTOMIZE.md for custom bibtex keyword documentation
|
||||||
|
|
||||||
|
## Trust These Instructions
|
||||||
|
|
||||||
|
This guidance documents the tested, working build process and project structure. **Trust these instructions and only perform additional searches if:**
|
||||||
|
|
||||||
|
1. Specific information contradicts what you observe in the codebase
|
||||||
|
2. You need implementation details beyond what's documented
|
||||||
|
3. Error messages reference features or files not mentioned here
|
||||||
|
|
||||||
|
The instructions are designed to reduce unnecessary exploration and allow you to focus on code changes.
|
||||||
174
.github/instructions/bibtex-bibliography.instructions.md
vendored
Normal file
174
.github/instructions/bibtex-bibliography.instructions.md
vendored
Normal file
@ -0,0 +1,174 @@
|
|||||||
|
---
|
||||||
|
applyTo: "**/*.bib,_bibliography/**"
|
||||||
|
excludeAgent: "code-review"
|
||||||
|
---
|
||||||
|
|
||||||
|
# BibTeX Bibliography Instructions
|
||||||
|
|
||||||
|
## BibTeX Format Basics
|
||||||
|
|
||||||
|
The al-folio repository uses BibTeX for managing publications. All entries are stored in `_bibliography/papers.bib`.
|
||||||
|
|
||||||
|
### Standard BibTeX Entry Types
|
||||||
|
|
||||||
|
```bibtex
|
||||||
|
@article{key,
|
||||||
|
title={Title},
|
||||||
|
author={Author, A. and Author, B.},
|
||||||
|
journal={Journal Name},
|
||||||
|
volume={10},
|
||||||
|
pages={1--20},
|
||||||
|
year={2023},
|
||||||
|
publisher={Publisher Name}
|
||||||
|
}
|
||||||
|
|
||||||
|
@inproceedings{key,
|
||||||
|
title={Title},
|
||||||
|
author={Author, A.},
|
||||||
|
booktitle={Proceedings of Conference},
|
||||||
|
year={2023}
|
||||||
|
}
|
||||||
|
|
||||||
|
@book{key,
|
||||||
|
title={Book Title},
|
||||||
|
author={Author, A.},
|
||||||
|
publisher={Publisher Name},
|
||||||
|
year={2023}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## al-folio Custom BibTeX Keywords
|
||||||
|
|
||||||
|
Beyond standard BibTeX fields, al-folio supports custom keywords for rich publications display:
|
||||||
|
|
||||||
|
### Available Custom Keywords
|
||||||
|
|
||||||
|
- **abstract:** Full abstract text (multi-line text in curly braces)
|
||||||
|
- **award:** Award or distinction (`award: Best Paper Award`)
|
||||||
|
- **code:** URL to source code repository (`code: https://github.com/user/repo`)
|
||||||
|
- **dimensions:** Dimensions badge ID for citation metrics
|
||||||
|
- **doi:** Digital Object Identifier (`doi: 10.1234/example`)
|
||||||
|
- **html:** URL to full text or project page (`html: https://example.com`)
|
||||||
|
- **pdf:** URL or path to PDF file (`pdf: /assets/papers/2023-paper.pdf`)
|
||||||
|
- **poster:** URL to conference poster (`poster: /assets/posters/poster.pdf`)
|
||||||
|
- **preview:** URL to preview image (`preview: /assets/img/papers/paper-preview.jpg`)
|
||||||
|
- **selected:** Boolean to feature on publications page (`selected: true`)
|
||||||
|
- **slides:** URL to presentation slides (`slides: /assets/slides/2023.pdf`)
|
||||||
|
|
||||||
|
### Example Entry with Custom Keywords
|
||||||
|
|
||||||
|
```bibtex
|
||||||
|
@article{smith2023important,
|
||||||
|
title={Important Research},
|
||||||
|
author={Smith, John and Doe, Jane},
|
||||||
|
journal={Nature},
|
||||||
|
volume={100},
|
||||||
|
pages={1--10},
|
||||||
|
year={2023},
|
||||||
|
publisher={Nature Publishing Group},
|
||||||
|
abstract={This is the full abstract text. It can span multiple lines.},
|
||||||
|
pdf={smith2023.pdf},
|
||||||
|
code={https://github.com/example/repo},
|
||||||
|
preview={smith2023.jpg},
|
||||||
|
doi={10.1234/nature.12345},
|
||||||
|
selected={true}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Formatting Rules
|
||||||
|
|
||||||
|
### Key Considerations
|
||||||
|
|
||||||
|
1. **Unique keys:** Each entry must have a unique key (first parameter)
|
||||||
|
2. **Author names:** Separate multiple authors with `and`
|
||||||
|
3. **Curly braces:** Protect capitalized words in titles with `{Curly Braces}` to preserve capitalization
|
||||||
|
4. **Special characters:** Use LaTeX escape sequences (`{\`e}`for é,`{\~n}` for ñ)
|
||||||
|
5. **URLs:** Place URLs in `{curly braces}` to prevent issues
|
||||||
|
6. **Alphabetical order:** Keep entries alphabetically sorted by key
|
||||||
|
|
||||||
|
### Common Mistakes to Avoid
|
||||||
|
|
||||||
|
- ❌ `author=Smith, John` → ✅ `author={Smith, John}`
|
||||||
|
- ❌ `journal=Science` → ✅ `journal={Science}` or `journal = "Science"`
|
||||||
|
- ❌ `title=Deep Learning` (loses capitalization) → ✅ `title={Deep Learning}` or `title={{D}eep {L}earning}`
|
||||||
|
- ❌ `pdf=http://...` → ✅ `pdf={http://...}`
|
||||||
|
|
||||||
|
## Jekyll-Scholar Integration
|
||||||
|
|
||||||
|
The `jekyll-scholar` plugin processes BibTeX and generates bibliography pages.
|
||||||
|
|
||||||
|
### How it Works
|
||||||
|
|
||||||
|
1. Entries in `_bibliography/papers.bib` are read
|
||||||
|
2. Pages marked with `layout: bib` render the bibliography
|
||||||
|
3. Posts/pages can reference entries using `{% cite key %}`
|
||||||
|
4. Custom keywords control what displays on publication entries
|
||||||
|
|
||||||
|
### Displaying Publications
|
||||||
|
|
||||||
|
In pages/posts, use:
|
||||||
|
|
||||||
|
- `{% cite key %}` – Cite an entry inline
|
||||||
|
- `{% bibliography %}` – Display full bibliography
|
||||||
|
|
||||||
|
## File Paths in BibTeX
|
||||||
|
|
||||||
|
When using `pdf`, `poster`, `preview`, or similar fields:
|
||||||
|
|
||||||
|
- **PDF files:** Use just the filename (automatically resolved to `assets/pdf/`)
|
||||||
|
- Example: `pdf={smith2023.pdf}` → resolves to `assets/pdf/smith2023.pdf`
|
||||||
|
- **Preview images:** Use just the filename (automatically resolved to `assets/img/publication_preview/`)
|
||||||
|
- Example: `preview={smith2023.jpg}` → resolves to `assets/img/publication_preview/smith2023.jpg`
|
||||||
|
- **Absolute URLs:** Include full URL for external resources
|
||||||
|
- Example: `code={https://github.com/user/repo}`
|
||||||
|
- Example: `html={https://example.com/paper}`
|
||||||
|
|
||||||
|
## Validation
|
||||||
|
|
||||||
|
### Before Committing BibTeX Changes
|
||||||
|
|
||||||
|
1. **Syntax check:** Verify no unclosed braces or quotes
|
||||||
|
2. **Build test:**
|
||||||
|
```bash
|
||||||
|
docker compose down
|
||||||
|
docker compose up
|
||||||
|
# Check output for "ERROR" or "Invalid bibtex"
|
||||||
|
# Publications should render at http://localhost:8080/publications/
|
||||||
|
```
|
||||||
|
3. **Publication page:** Open publications page and verify entries display correctly
|
||||||
|
|
||||||
|
### Common BibTeX Build Errors
|
||||||
|
|
||||||
|
- `Invalid bibtex reference 'key'` – Key doesn't exist in papers.bib
|
||||||
|
- `Unmatched braces` – Missing closing brace in entry
|
||||||
|
- `Unknown entry type` – Entry type (after @) is misspelled
|
||||||
|
- `PDF not found` – Path in pdf field is incorrect
|
||||||
|
|
||||||
|
## Editing and Maintenance
|
||||||
|
|
||||||
|
### Adding New Entries
|
||||||
|
|
||||||
|
1. Add entry to `_bibliography/papers.bib`
|
||||||
|
2. Use consistent key naming (e.g., `LastnameYear` or `Lastname2023details`)
|
||||||
|
3. Ensure all required fields are present
|
||||||
|
4. Test build: `docker compose up`
|
||||||
|
|
||||||
|
### Modifying Existing Entries
|
||||||
|
|
||||||
|
- Can change any BibTeX field without breaking Jekyll
|
||||||
|
- Adding custom keywords (pdf, code, etc.) enriches display
|
||||||
|
- Test build after modifications to verify display
|
||||||
|
|
||||||
|
### Removing Entries
|
||||||
|
|
||||||
|
- Delete or comment out (prefix with `%`) the entire entry
|
||||||
|
- No broken reference check needed; Jekyll-Scholar handles missing keys gracefully
|
||||||
|
|
||||||
|
## Trust These Instructions
|
||||||
|
|
||||||
|
When working with BibTeX:
|
||||||
|
|
||||||
|
- Follow the standard format shown in examples above
|
||||||
|
- Always test locally with `docker compose up` after changes
|
||||||
|
- Check the publications page at http://localhost:8080/publications to verify display
|
||||||
|
- Only search for additional details if encountering error messages not mentioned here
|
||||||
248
.github/instructions/javascript-scripts.instructions.md
vendored
Normal file
248
.github/instructions/javascript-scripts.instructions.md
vendored
Normal file
@ -0,0 +1,248 @@
|
|||||||
|
---
|
||||||
|
applyTo: "_scripts/**/*.js"
|
||||||
|
---
|
||||||
|
|
||||||
|
# JavaScript Scripts Instructions
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The `_scripts/` directory contains JavaScript files that provide frontend functionality for the al-folio website. These scripts handle:
|
||||||
|
|
||||||
|
- **Search functionality** – Ninja-keys integration for search bar
|
||||||
|
- **Analytics setup** – Google Analytics, Cronitor, Open Panel integrations
|
||||||
|
- **Gallery functionality** – PhotoSwipe lightbox initialization
|
||||||
|
- **Liquid template processing** – Files with `.liquid.js` extension process Jekyll Liquid syntax
|
||||||
|
|
||||||
|
## Key Script Files
|
||||||
|
|
||||||
|
### `search.liquid.js`
|
||||||
|
|
||||||
|
- **Purpose:** Generates searchable navigation data for the Ninja-keys search component
|
||||||
|
- **Type:** Liquid + JavaScript hybrid (Jekyll processes `.liquid.js` files)
|
||||||
|
- **Output:** Compiled to `/assets/js/search-data.js` via permalink frontmatter
|
||||||
|
- **Content:** Builds `ninja.data` array from site pages, posts, and navigation structure
|
||||||
|
- **Usage:** Included in `_includes/scripts.liquid` and loaded in layouts
|
||||||
|
|
||||||
|
### `photoswipe-setup.js`
|
||||||
|
|
||||||
|
- **Purpose:** Initializes PhotoSwipe lightbox for image galleries
|
||||||
|
- **Type:** Pure JavaScript with ES6 imports
|
||||||
|
- **Output:** Compiled to `/assets/js/photoswipe-setup.js`
|
||||||
|
- **Dependencies:** PhotoSwipe library (referenced via `site.third_party_libraries`)
|
||||||
|
- **Functionality:** Automatically converts `.pswp-gallery` elements into interactive lightbox galleries
|
||||||
|
|
||||||
|
### `google-analytics-setup.js`, `cronitor-analytics-setup.js`, `open-panel-analytics-setup.js`
|
||||||
|
|
||||||
|
- **Purpose:** Initialize third-party analytics services
|
||||||
|
- **Type:** Conditional setup scripts (may be excluded from production builds)
|
||||||
|
- **Usage:** Loaded conditionally based on `_config.yml` feature flags
|
||||||
|
- **Integration:** Each sets up tracking code for respective analytics platforms
|
||||||
|
|
||||||
|
## File Structure & Frontmatter
|
||||||
|
|
||||||
|
All scripts in `_scripts/` may include Jekyll frontmatter:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
---
|
||||||
|
permalink: /assets/js/filename.js
|
||||||
|
---
|
||||||
|
// JavaScript code here
|
||||||
|
```
|
||||||
|
|
||||||
|
**Key frontmatter fields:**
|
||||||
|
|
||||||
|
- `permalink:` – Specifies output path in compiled site (e.g., `/assets/js/search-data.js`)
|
||||||
|
- Comments/empty – Files with only JavaScript and no frontmatter are processed as-is
|
||||||
|
|
||||||
|
**Processing:**
|
||||||
|
|
||||||
|
- `.liquid.js` files – Processed by Jekyll's Liquid engine before JavaScript compilation
|
||||||
|
- `.js` files – Processed normally, passed through to assets directory
|
||||||
|
- **Note:** Files in `_scripts/` are ignored by Prettier (see `.prettierignore`) because `.liquid.js` files mix Liquid template syntax with JavaScript, which Prettier doesn't support
|
||||||
|
|
||||||
|
## JavaScript Patterns in al-folio
|
||||||
|
|
||||||
|
### Liquid + JavaScript Mixing (in `.liquid.js` files)
|
||||||
|
|
||||||
|
Example from `search.liquid.js`:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
---
|
||||||
|
permalink: /assets/js/search-data.js
|
||||||
|
---
|
||||||
|
// Regular JavaScript
|
||||||
|
const ninja = document.querySelector('ninja-keys');
|
||||||
|
|
||||||
|
// Liquid processing - Jekyll loops and variables
|
||||||
|
ninja.data = [
|
||||||
|
{%- for page in site.pages -%}
|
||||||
|
{
|
||||||
|
id: "nav-{{ page.title | slugify }}",
|
||||||
|
title: "{{ page.title }}",
|
||||||
|
handler: () => {
|
||||||
|
window.location.href = "{{ page.url | relative_url }}";
|
||||||
|
},
|
||||||
|
},
|
||||||
|
{%- endfor -%}
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
**Important:**
|
||||||
|
|
||||||
|
- Use Liquid filters (`| slugify`, `| relative_url`, `| escape`) to process Jekyll variables
|
||||||
|
- Curly braces `{{ }}` output variables
|
||||||
|
- Use `{%- -%}` (with hyphens) to control whitespace in generated output
|
||||||
|
- Keep JSON structures valid after Liquid processing
|
||||||
|
|
||||||
|
### ES6 Modules & Imports
|
||||||
|
|
||||||
|
Scripts use modern JavaScript with ES6 imports:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
import PhotoSwipeLightbox from "{{ site.third_party_libraries.photoswipe-lightbox.url.js }}";
|
||||||
|
import PhotoSwipe from "{{ site.third_party_libraries.photoswipe.url.js }}";
|
||||||
|
```
|
||||||
|
|
||||||
|
- Import third-party libraries via `site.third_party_libraries` configuration
|
||||||
|
- Libraries resolved from `_config.yml` CDN or local paths
|
||||||
|
|
||||||
|
### DOM Manipulation & Event Handlers
|
||||||
|
|
||||||
|
Scripts attach to specific DOM elements:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
const element = document.querySelector(".selector");
|
||||||
|
element.addEventListener("click", (event) => {
|
||||||
|
// Handle event
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Modification Patterns
|
||||||
|
|
||||||
|
### Adding a New Analytics Service
|
||||||
|
|
||||||
|
1. Create new file `_scripts/myservice-setup.js`:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
---
|
||||||
|
permalink: /assets/js/myservice-setup.js
|
||||||
|
---
|
||||||
|
(function() {
|
||||||
|
// Initialize your service
|
||||||
|
if (window.myService) {
|
||||||
|
console.log('MyService loaded');
|
||||||
|
}
|
||||||
|
})();
|
||||||
|
```
|
||||||
|
|
||||||
|
2. Add conditional loading to `_includes/scripts.liquid`:
|
||||||
|
|
||||||
|
```liquid
|
||||||
|
{% if site.myservice_enabled %}
|
||||||
|
<script src="{{ '/assets/js/myservice-setup.js' | relative_url }}"></script>
|
||||||
|
{% endif %}
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Add feature flag to `_config.yml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
myservice_enabled: false
|
||||||
|
```
|
||||||
|
|
||||||
|
### Modifying Search Data Structure
|
||||||
|
|
||||||
|
In `search.liquid.js`:
|
||||||
|
|
||||||
|
1. Identify the Liquid loop building `ninja.data` array
|
||||||
|
2. Add new properties to each object:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
{
|
||||||
|
id: "nav-{{ title | slugify }}",
|
||||||
|
title: "{{ title }}",
|
||||||
|
newField: "{{ page.new_property }}", // Add new field
|
||||||
|
handler: () => { ... }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Rebuild: `docker compose up` will regenerate `/assets/js/search-data.js`
|
||||||
|
|
||||||
|
### Updating Gallery Functionality
|
||||||
|
|
||||||
|
In `photoswipe-setup.js`:
|
||||||
|
|
||||||
|
1. Modify gallery selector or initialization options
|
||||||
|
2. Reference [PhotoSwipe documentation](https://photoswipe.com/) for available options
|
||||||
|
3. Update any CSS classes used in gallery markup
|
||||||
|
|
||||||
|
## Code Style Notes
|
||||||
|
|
||||||
|
**Prettier and \_scripts/:**
|
||||||
|
|
||||||
|
Files in `_scripts/` are **excluded from Prettier formatting** (defined in `.prettierignore`) because:
|
||||||
|
|
||||||
|
- `.liquid.js` files contain mixed Liquid template syntax and JavaScript
|
||||||
|
- Prettier doesn't understand or support this hybrid format
|
||||||
|
- Manual formatting consistency is required for these files
|
||||||
|
|
||||||
|
**When modifying \_scripts/ files:**
|
||||||
|
|
||||||
|
- Follow existing code style in the file (indentation, spacing, quotes)
|
||||||
|
- Maintain readability for Liquid + JavaScript mixed code
|
||||||
|
- Do NOT run Prettier on the `_scripts/` directory
|
||||||
|
- **DO run Prettier on the rest of the project** when making other changes: `npx prettier . --write`
|
||||||
|
|
||||||
|
## Validation & Testing
|
||||||
|
|
||||||
|
### Local Build Test
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose up
|
||||||
|
# Wait 30 seconds for Jekyll to build
|
||||||
|
# Check for errors in terminal output
|
||||||
|
# Visit http://localhost:8080 and verify functionality
|
||||||
|
```
|
||||||
|
|
||||||
|
### Checking Generated Output
|
||||||
|
|
||||||
|
After `docker compose up`, verify scripts compiled correctly:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Check if script files exist in _site/assets/js/
|
||||||
|
ls _site/assets/js/
|
||||||
|
|
||||||
|
# Verify no Liquid syntax in generated output (should be pure JavaScript)
|
||||||
|
cat _site/assets/js/search-data.js | head -20
|
||||||
|
```
|
||||||
|
|
||||||
|
### Debugging Script Issues
|
||||||
|
|
||||||
|
**Script not loading:**
|
||||||
|
|
||||||
|
- Check browser DevTools Console for HTTP 404 errors
|
||||||
|
- Verify `permalink:` frontmatter matches script inclusion paths
|
||||||
|
- Check that script is actually in `_site/assets/js/` after build
|
||||||
|
|
||||||
|
**Liquid syntax errors:**
|
||||||
|
|
||||||
|
- Jekyll build will fail with "Liquid Exception" messages
|
||||||
|
- Check file for unclosed `{% %}` or `{{ }}` tags
|
||||||
|
- Ensure Liquid filters exist (`| relative_url`, `| slugify`, etc.)
|
||||||
|
|
||||||
|
**JavaScript errors:**
|
||||||
|
|
||||||
|
- Check browser console for runtime errors
|
||||||
|
- Verify all imported libraries are defined in `site.third_party_libraries` in `_config.yml`
|
||||||
|
- Test in both Chrome and Firefox for compatibility
|
||||||
|
|
||||||
|
## Trust These Instructions
|
||||||
|
|
||||||
|
When modifying JavaScript scripts:
|
||||||
|
|
||||||
|
- `.liquid.js` files must have valid Liquid syntax AND valid JavaScript that remains valid after Jekyll processes the Liquid
|
||||||
|
- Do NOT run Prettier on `_scripts/` files (they are in `.prettierignore` because of Liquid + JavaScript mixing)
|
||||||
|
- Test locally with `docker compose up` to verify build succeeds and scripts work
|
||||||
|
- For site-wide script inclusion, modify `_includes/scripts.liquid`
|
||||||
|
- For configuration (feature flags, third-party URLs), see yaml-configuration.instructions.md
|
||||||
|
- Reference the actual script files in `_scripts/` as examples when adding new functionality
|
||||||
|
- Only search for additional details if errors occur during build or testing
|
||||||
100
.github/instructions/liquid-templates.instructions.md
vendored
Normal file
100
.github/instructions/liquid-templates.instructions.md
vendored
Normal file
@ -0,0 +1,100 @@
|
|||||||
|
---
|
||||||
|
applyTo: "**/*.liquid"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Liquid Templates Instructions
|
||||||
|
|
||||||
|
## Liquid Template Basics
|
||||||
|
|
||||||
|
This al-folio repository uses Liquid templating extensively. When modifying `.liquid` files:
|
||||||
|
|
||||||
|
### Key Directories
|
||||||
|
|
||||||
|
- `_includes/` – Reusable template components (imported with `{% include %}`)
|
||||||
|
- `_layouts/` – Page layout templates (specified in frontmatter with `layout: name`)
|
||||||
|
|
||||||
|
### Common Liquid Tags in al-folio
|
||||||
|
|
||||||
|
- `{% include filename.liquid %}` – Includes template component
|
||||||
|
- `{% for item in collection %}...{% endfor %}` – Loops
|
||||||
|
- `{% if condition %}...{% endif %}` – Conditionals
|
||||||
|
- `{{ variable }}` – Output variable
|
||||||
|
- `{% assign var = value %}` – Assign variable
|
||||||
|
- `{% capture %}...{% endcapture %}` – Capture output to variable
|
||||||
|
- `| date: format` – Date filtering
|
||||||
|
- `| where: "key", "value"` – Collection filtering
|
||||||
|
|
||||||
|
### Important al-folio Liquid Components
|
||||||
|
|
||||||
|
- `_includes/citation.liquid` – Bibliography entry rendering
|
||||||
|
- `_includes/distill_scripts.liquid` – Distill.pub specific scripts
|
||||||
|
- `_includes/footer.liquid` – Site footer
|
||||||
|
- `_includes/head.liquid` – Page <head> section
|
||||||
|
- `_includes/header.liquid` – Site header/navigation
|
||||||
|
- `_includes/projects.liquid` – Project display
|
||||||
|
- `_includes/scripts.liquid` – Global scripts
|
||||||
|
- `_includes/selected_papers.liquid` – Featured publications display
|
||||||
|
|
||||||
|
### Prettier Formatting for Liquid
|
||||||
|
|
||||||
|
Prettier with `@shopify/prettier-plugin-liquid` enforces formatting:
|
||||||
|
|
||||||
|
- Single quotes around strings in Liquid tags
|
||||||
|
- Consistent spacing
|
||||||
|
- Indentation with 2 spaces
|
||||||
|
- Run `npx prettier . --write` before committing
|
||||||
|
|
||||||
|
## Common Modification Patterns
|
||||||
|
|
||||||
|
### Modifying Site Header/Navigation
|
||||||
|
|
||||||
|
- Edit `_includes/header.liquid`
|
||||||
|
- Add links to navigation array in `_config.yml` (see yaml-configuration.instructions.md)
|
||||||
|
- Test by viewing site in browser: `docker compose up` → http://localhost:8080
|
||||||
|
|
||||||
|
### Adding a New Component Include
|
||||||
|
|
||||||
|
1. Create new file in `_includes/mycomponent.liquid`
|
||||||
|
2. Use Liquid syntax for conditionals, loops, and variable output
|
||||||
|
3. Call it from templates: `{% include mycomponent.liquid %}`
|
||||||
|
4. Test: `docker compose up`
|
||||||
|
|
||||||
|
### Adjusting Styling with Liquid
|
||||||
|
|
||||||
|
- Some SCSS variables can be controlled via Liquid logic
|
||||||
|
- Avoid mixing complex Liquid with CSS; keep templates focused
|
||||||
|
|
||||||
|
## Validation Before Committing
|
||||||
|
|
||||||
|
**Always run these checks:**
|
||||||
|
|
||||||
|
1. **Prettier format check:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx prettier _includes/ _layouts/ --check
|
||||||
|
npx prettier . --write # Fix formatting
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Build test:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose down
|
||||||
|
docker compose up
|
||||||
|
# Wait 30 seconds, check for errors in output
|
||||||
|
# No "Unknown tag" messages should appear
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Visual verification:**
|
||||||
|
- Open http://localhost:8080
|
||||||
|
- Check that your changes rendered correctly
|
||||||
|
- Verify no broken layout or missing content
|
||||||
|
|
||||||
|
## Trust These Instructions
|
||||||
|
|
||||||
|
When working with Liquid templates:
|
||||||
|
|
||||||
|
- Use `_includes/` and `_layouts/` as reference for syntax patterns
|
||||||
|
- Follow existing formatting in files (Prettier will enforce consistency)
|
||||||
|
- Always test locally before pushing (build must succeed)
|
||||||
|
- For configuration changes, see yaml-configuration.instructions.md
|
||||||
|
- Only search for additional details if error messages reference unfamiliar Liquid tags or Jekyll concepts
|
||||||
277
.github/instructions/markdown-content.instructions.md
vendored
Normal file
277
.github/instructions/markdown-content.instructions.md
vendored
Normal file
@ -0,0 +1,277 @@
|
|||||||
|
---
|
||||||
|
applyTo: "_books/**/*.md,_news/**/*.md,_pages/**/*.md,_posts/**/*.md,_projects/**/*.md,_teachings/**/*.md"
|
||||||
|
---
|
||||||
|
|
||||||
|
# Content Files (Markdown) Instructions
|
||||||
|
|
||||||
|
## File Organization
|
||||||
|
|
||||||
|
Content in al-folio is organized by type:
|
||||||
|
|
||||||
|
- **\_books/** – Book reviews and summaries
|
||||||
|
- **\_news/** – News/announcements
|
||||||
|
- **\_pages/** – Static pages (about, CV, publications, projects, etc.)
|
||||||
|
- **\_posts/** – Blog posts (format: `YYYY-MM-DD-title.md`)
|
||||||
|
- **\_projects/** – Project showcase entries
|
||||||
|
- **\_teachings/** – Course and teaching information
|
||||||
|
|
||||||
|
## Frontmatter Structure
|
||||||
|
|
||||||
|
Every markdown file requires YAML frontmatter at the top. The structure varies by content type.
|
||||||
|
|
||||||
|
### Book Frontmatter (\_books/)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
layout: book-review
|
||||||
|
title: Book Title
|
||||||
|
author: Book Author Name
|
||||||
|
publisher: Publisher Name
|
||||||
|
year: 2023
|
||||||
|
rating: 8/10
|
||||||
|
img: /assets/img/book-cover.jpg
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
### News Frontmatter (\_news/)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
layout: post
|
||||||
|
title: News Title
|
||||||
|
date: YYYY-MM-DD
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
### Page Frontmatter (\_pages/)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
layout: page
|
||||||
|
title: Page Title
|
||||||
|
permalink: /pathname/
|
||||||
|
description: Brief description for metadata
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
### Blog Post Frontmatter (\_posts/)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
layout: post
|
||||||
|
title: Post Title
|
||||||
|
date: YYYY-MM-DD
|
||||||
|
categories: category-name
|
||||||
|
description: Brief description
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
**Important:** Post filenames MUST follow format: `YYYY-MM-DD-title.md` (hyphen-separated words)
|
||||||
|
|
||||||
|
### Project Frontmatter (\_projects/)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
layout: page
|
||||||
|
title: Project Name
|
||||||
|
description: Short description
|
||||||
|
img: /assets/img/project-image.jpg
|
||||||
|
importance: 1
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
### Teaching/Course Frontmatter (\_teachings/)
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
---
|
||||||
|
layout: page
|
||||||
|
title: Course Title
|
||||||
|
description: Course description
|
||||||
|
---
|
||||||
|
```
|
||||||
|
|
||||||
|
## Special Frontmatter Fields
|
||||||
|
|
||||||
|
### For Books
|
||||||
|
|
||||||
|
- **author:** Author name or comma-separated list
|
||||||
|
- **publisher:** Publisher name
|
||||||
|
- **year:** Publication year
|
||||||
|
- **rating:** Personal rating (e.g., `8/10`)
|
||||||
|
- **img:** Path to book cover image (`/assets/img/...`)
|
||||||
|
|
||||||
|
### For Blog Posts
|
||||||
|
|
||||||
|
- **categories:** Tag for post organization (single word, no spaces)
|
||||||
|
- **related_posts:** Set to `false` to disable related posts display (useful for short posts)
|
||||||
|
|
||||||
|
### For Projects
|
||||||
|
|
||||||
|
- **importance:** Integer (1, 2, 3...) – higher = featured first
|
||||||
|
- **img:** Path to thumbnail image (`/assets/img/...`)
|
||||||
|
- **featured:** Set to `true` to display on main projects section
|
||||||
|
|
||||||
|
### Date Format
|
||||||
|
|
||||||
|
Always use ISO 8601: `YYYY-MM-DD` (e.g., `2023-12-25`)
|
||||||
|
|
||||||
|
## Markdown Content
|
||||||
|
|
||||||
|
### Basic Markdown Syntax
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Heading 1
|
||||||
|
|
||||||
|
## Heading 2
|
||||||
|
|
||||||
|
### Heading 3
|
||||||
|
|
||||||
|
**bold text**
|
||||||
|
_italic text_
|
||||||
|
`inline code`
|
||||||
|
|
||||||
|
- List item 1
|
||||||
|
- List item 2
|
||||||
|
|
||||||
|
[Link text](https://url.com)
|
||||||
|
|
||||||
|
|
||||||
|
```
|
||||||
|
|
||||||
|
### al-folio-Specific Features
|
||||||
|
|
||||||
|
#### Includes/Shortcodes
|
||||||
|
|
||||||
|
- `{% include figure.liquid ... %}` – Responsive images with captions
|
||||||
|
- `{% include audio.liquid ... %}` – Audio player
|
||||||
|
- `{% include video.liquid ... %}` – Video player
|
||||||
|
- `{% include bib_search.liquid ... %}` – Bibliography search
|
||||||
|
- `{% include calendar.liquid ... %}` – Event calendar
|
||||||
|
|
||||||
|
#### Math Support
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
Inline: $E = mc^2$
|
||||||
|
|
||||||
|
Display mode:
|
||||||
|
$$\int_0^1 f(x) dx$$
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Code Blocks
|
||||||
|
|
||||||
|
````markdown
|
||||||
|
```python
|
||||||
|
def hello():
|
||||||
|
print("Hello, world!")
|
||||||
|
```
|
||||||
|
````
|
||||||
|
|
||||||
|
#### Blockquotes
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
> This is a quote
|
||||||
|
>
|
||||||
|
> > Nested quote
|
||||||
|
```
|
||||||
|
|
||||||
|
### Jekyll Features Available
|
||||||
|
|
||||||
|
- **Liquid variables:** `{{ site.title }}`, `{{ page.title }}`
|
||||||
|
- **Collections:** `{{ site.posts }}`, `{{ site.projects }}`
|
||||||
|
- **Filters:** `| date: format`, `| where: key value`
|
||||||
|
- **Tags:** `{% if condition %} ... {% endif %}`
|
||||||
|
|
||||||
|
## Common Content Patterns
|
||||||
|
|
||||||
|
### Creating a Blog Post
|
||||||
|
|
||||||
|
1. Create file: `_posts/YYYY-MM-DD-my-post.md`
|
||||||
|
2. Add frontmatter with `layout: post`, `title`, `date`, `categories`
|
||||||
|
3. Write markdown content
|
||||||
|
4. Test: `docker compose up` → http://localhost:8080/blog
|
||||||
|
5. Post will appear in reverse chronological order
|
||||||
|
|
||||||
|
### Creating a Project Entry
|
||||||
|
|
||||||
|
1. Create file: `_projects/project-name.md`
|
||||||
|
2. Add frontmatter with `layout: page`, `title`, `description`, `img`, `importance`
|
||||||
|
3. Write markdown content describing the project
|
||||||
|
4. Test: `docker compose up` → http://localhost:8080/projects
|
||||||
|
|
||||||
|
### Adding Images
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
{% include figure.liquid path="/assets/img/example.jpg" title="Image caption" %}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Linking to Other Pages
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
[About Me](/about/)
|
||||||
|
[My CV](/cv/)
|
||||||
|
[Blog Post]({% link _posts/2023-01-15-my-post.md %})
|
||||||
|
```
|
||||||
|
|
||||||
|
## Testing & Validation
|
||||||
|
|
||||||
|
### Before Committing
|
||||||
|
|
||||||
|
1. **Frontmatter syntax:** Verify YAML is valid (no unclosed quotes, proper indentation)
|
||||||
|
2. **Date format:** Check `YYYY-MM-DD` format is correct
|
||||||
|
3. **Build test:**
|
||||||
|
```bash
|
||||||
|
docker compose down
|
||||||
|
docker compose up
|
||||||
|
# Wait for "Server running" message
|
||||||
|
# Navigate to your content in browser
|
||||||
|
# Verify formatting, images, and links work
|
||||||
|
```
|
||||||
|
|
||||||
|
### Common Issues
|
||||||
|
|
||||||
|
- **Post not appearing:** Check `date` is today or earlier, filename format is correct
|
||||||
|
- **Images not loading:** Verify path starts with `/assets/`, file exists
|
||||||
|
- **Related posts error:** Content has no meaningful words; add more text or set `related_posts: false`
|
||||||
|
|
||||||
|
## File Naming Conventions
|
||||||
|
|
||||||
|
### Blog Posts
|
||||||
|
|
||||||
|
- Format: `YYYY-MM-DD-title-with-hyphens.md`
|
||||||
|
- Example: `2023-12-25-christmas-post.md`
|
||||||
|
- Words separated by hyphens, no spaces
|
||||||
|
|
||||||
|
### Projects
|
||||||
|
|
||||||
|
- Format: `project-name.md`
|
||||||
|
- Example: `my-research-project.md`
|
||||||
|
- Use hyphens for readability
|
||||||
|
|
||||||
|
### Pages
|
||||||
|
|
||||||
|
- Format: `descriptive-name.md`
|
||||||
|
- Example: `about.md`, `teaching.md`, `cv.md`
|
||||||
|
|
||||||
|
## Markdown Linting & Formatting
|
||||||
|
|
||||||
|
The Prettier formatter applies to markdown files:
|
||||||
|
|
||||||
|
- **Line length:** Soft wrap at 88 characters
|
||||||
|
- **Lists:** Consistent bullet formatting
|
||||||
|
- **Code blocks:** Proper fence syntax
|
||||||
|
- **Spacing:** Consistent blank lines
|
||||||
|
|
||||||
|
**Always run before committing:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx prettier --write .
|
||||||
|
```
|
||||||
|
|
||||||
|
## Trust These Instructions
|
||||||
|
|
||||||
|
When creating or editing content:
|
||||||
|
|
||||||
|
- Follow the frontmatter structure for your content type
|
||||||
|
- Test locally with `docker compose up` to verify appearance
|
||||||
|
- Check date format, filename format, and image paths
|
||||||
|
- Only search for advanced features if frontmatter or markdown error messages appear
|
||||||
250
.github/instructions/yaml-configuration.instructions.md
vendored
Normal file
250
.github/instructions/yaml-configuration.instructions.md
vendored
Normal file
@ -0,0 +1,250 @@
|
|||||||
|
---
|
||||||
|
applyTo: "_config.yml,_data/**/*.yml"
|
||||||
|
---
|
||||||
|
|
||||||
|
# YAML Configuration Instructions
|
||||||
|
|
||||||
|
## YAML Configuration (\_config.yml)
|
||||||
|
|
||||||
|
### Critical Settings for Agents
|
||||||
|
|
||||||
|
When modifying `_config.yml`, always update these in pairs:
|
||||||
|
|
||||||
|
- **url** and **baseurl** must be consistent:
|
||||||
|
- Personal site: `url: https://username.github.io`, `baseurl:` (leave empty)
|
||||||
|
- Project site: `url: https://username.github.io`, `baseurl: /projectname/`
|
||||||
|
- **title, first_name, last_name** – Site header and metadata
|
||||||
|
- **description** – Used in RSS feeds and metadata
|
||||||
|
- **lang** – Language code (e.g., "en", "fr")
|
||||||
|
|
||||||
|
### Feature Flags in \_config.yml
|
||||||
|
|
||||||
|
Look for `enabled: false/true` patterns. Common ones:
|
||||||
|
|
||||||
|
- `blog.enabled`
|
||||||
|
- `news.enabled`
|
||||||
|
- `profile.image_circular`
|
||||||
|
- `profile.show_social_links`
|
||||||
|
- `projects.enabled`
|
||||||
|
- `publications.enabled`
|
||||||
|
- `related_blog_posts`
|
||||||
|
|
||||||
|
### YAML Syntax Rules
|
||||||
|
|
||||||
|
- Quote string values containing special characters: `":"`
|
||||||
|
- Use `>` for multi-line strings (ignore newlines)
|
||||||
|
- Use `|` for multi-line strings (preserve newlines)
|
||||||
|
- Indentation matters: always use spaces (2 spaces), never tabs
|
||||||
|
- No tabs allowed; use only spaces
|
||||||
|
|
||||||
|
### Testing YAML Syntax
|
||||||
|
|
||||||
|
If you modify `_config.yml`, verify syntax by running:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker compose up
|
||||||
|
# Site should start without YAML parse errors
|
||||||
|
# Check output for "YAML parse error" or "valid YAML"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Data Files (\_data/\*.yml)
|
||||||
|
|
||||||
|
Data files provide structured content that templates can access via Liquid. Each file serves a specific purpose.
|
||||||
|
|
||||||
|
### socials.yml
|
||||||
|
|
||||||
|
Defines social media links and contact information displayed on the site.
|
||||||
|
|
||||||
|
**Format:** Entries are displayed in the order they are defined (not alphabetically sorted)
|
||||||
|
|
||||||
|
**For standard socials:** Use the key with the appropriate value. Common built-in socials include:
|
||||||
|
|
||||||
|
- `email:` – Email address
|
||||||
|
- `cv_pdf:` – Path to CV PDF file
|
||||||
|
- `scholar_userid:` – Google Scholar ID
|
||||||
|
- `inspirehep_id:` – Inspire HEP author ID
|
||||||
|
- `rss_icon:` – Boolean to show/hide RSS icon
|
||||||
|
- And many others (see [jekyll-socials documentation](https://github.com/george-gca/jekyll-socials) for full list)
|
||||||
|
|
||||||
|
**For custom socials:** Define a custom entry with nested fields:
|
||||||
|
|
||||||
|
- `logo:` – URL or path to logo image
|
||||||
|
- `title:` – Display name
|
||||||
|
- `url:` – Profile or website URL
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
cv_pdf: /assets/pdf/example_pdf.pdf
|
||||||
|
email: you@example.com
|
||||||
|
scholar_userid: qc6CJjYAAAAJ
|
||||||
|
github_username: username
|
||||||
|
linkedin_username: username
|
||||||
|
|
||||||
|
custom_social:
|
||||||
|
logo: https://example.com/logo.png
|
||||||
|
title: Custom Profile
|
||||||
|
url: https://example.com/
|
||||||
|
```
|
||||||
|
|
||||||
|
For more information, see the [jekyll-socials documentation](https://github.com/george-gca/jekyll-socials).
|
||||||
|
|
||||||
|
### cv.yml
|
||||||
|
|
||||||
|
CV content in **RenderCV format** (recommended approach for generating professional CVs).
|
||||||
|
|
||||||
|
**Format:** [RenderCV](https://rendercv.com/) YAML format — human-readable and designed specifically for professional resumes with automatic PDF generation capability.
|
||||||
|
|
||||||
|
**Key Files:**
|
||||||
|
|
||||||
|
- [`_data/cv.yml`](_data/cv.yml) — Main CV content in RenderCV format
|
||||||
|
- [`assets/rendercv/design.yaml`](assets/rendercv/design.yaml) — Design and styling customization
|
||||||
|
- [`assets/rendercv/locale.yaml`](assets/rendercv/locale.yaml) — Localization and text formatting
|
||||||
|
- [`assets/rendercv/settings.yaml`](assets/rendercv/settings.yaml) — RenderCV-specific settings
|
||||||
|
|
||||||
|
**Usage:** Rendered by `cv.liquid` layout on CV page; displayed in `about.liquid` on home page.
|
||||||
|
|
||||||
|
**Automatic PDF Generation:** When using RenderCV format, a GitHub Actions workflow (`render-cv.yml`) automatically generates a PDF version whenever you push changes to `_data/cv.yml`. The generated PDF is saved to `assets/rendercv/rendercv_output/` and can be linked via `cv_pdf` setting in `_config.yml`.
|
||||||
|
|
||||||
|
**Alternative Format (JSONResume):** For an alternative format, see `assets/json/resume.json` which uses the [JSONResume](https://jsonresume.org/) standard. Switch between formats using the `cv_format` frontmatter variable in `_pages/cv.md` (options: `rendercv` or `jsonresume`).
|
||||||
|
|
||||||
|
**For more details:** See [CUSTOMIZE.md § Modifying the CV information](CUSTOMIZE.md#modifying-the-cv-information) for setup, switching formats, and PDF generation configuration.
|
||||||
|
|
||||||
|
### citations.yml
|
||||||
|
|
||||||
|
Social media citation counts and metrics.
|
||||||
|
|
||||||
|
**Format:** Varies by platform (Google Scholar, ORCID, etc.)
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
scholar_userid: YOUR_SCHOLAR_ID
|
||||||
|
```
|
||||||
|
|
||||||
|
### repositories.yml
|
||||||
|
|
||||||
|
GitHub repository listing for the repositories page.
|
||||||
|
|
||||||
|
**Format:** List of repository information
|
||||||
|
|
||||||
|
**Usage:** Used by repositories page to display GitHub projects
|
||||||
|
|
||||||
|
### coauthors.yml
|
||||||
|
|
||||||
|
Co-author information for bibliography/publications.
|
||||||
|
|
||||||
|
**Mapping:** Author names to profile URLs and affiliations
|
||||||
|
|
||||||
|
**Format:** Maps full names to contact info
|
||||||
|
|
||||||
|
**Example:**
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
"Einstein, Albert":
|
||||||
|
url: https://en.wikipedia.org/wiki/Albert_Einstein
|
||||||
|
affiliation: Princeton University
|
||||||
|
```
|
||||||
|
|
||||||
|
## Common Modification Patterns
|
||||||
|
|
||||||
|
### Adding a New Feature Flag
|
||||||
|
|
||||||
|
1. Add to `_config.yml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
my_feature:
|
||||||
|
enabled: true
|
||||||
|
```
|
||||||
|
|
||||||
|
2. In Liquid templates use:
|
||||||
|
|
||||||
|
```liquid
|
||||||
|
{% if site.my_feature.enabled %}
|
||||||
|
... content ...
|
||||||
|
{% endif %}
|
||||||
|
```
|
||||||
|
|
||||||
|
3. Document the flag in CUSTOMIZE.md
|
||||||
|
|
||||||
|
### Updating Social Media Links
|
||||||
|
|
||||||
|
1. Edit `_data/socials.yml`
|
||||||
|
2. Keep entries alphabetically sorted
|
||||||
|
3. Ensure `icon` identifiers match available icons (Academicons or Font Awesome)
|
||||||
|
4. Use full profile URLs in `url` field
|
||||||
|
5. Test: `docker compose up` → check social icons on site
|
||||||
|
|
||||||
|
### Modifying Site Metadata
|
||||||
|
|
||||||
|
Update these in `_config.yml`:
|
||||||
|
|
||||||
|
- **title** – Site name
|
||||||
|
- **first_name, last_name** – Your name
|
||||||
|
- **email** – Contact email
|
||||||
|
- **description** – Site tagline (used in RSS, metadata)
|
||||||
|
- **keywords** – Search keywords
|
||||||
|
|
||||||
|
### Adding Co-authors
|
||||||
|
|
||||||
|
1. Edit `_data/coauthors.yml`
|
||||||
|
2. Add entry with author name as key
|
||||||
|
3. Include `url:` and `affiliation:` fields
|
||||||
|
4. This maps author names in BibTeX to profile links
|
||||||
|
|
||||||
|
## Validation Before Committing
|
||||||
|
|
||||||
|
**Always run these checks:**
|
||||||
|
|
||||||
|
1. **YAML syntax check:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Run Jekyll build to validate YAML
|
||||||
|
docker compose down
|
||||||
|
docker compose up
|
||||||
|
# Wait for "Server running" message
|
||||||
|
# Check output for "YAML parse error" messages
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Prettier format check:**
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx prettier _config.yml _data/ --check
|
||||||
|
npx prettier . --write # Fix formatting
|
||||||
|
```
|
||||||
|
|
||||||
|
3. **Visual verification:**
|
||||||
|
- Open http://localhost:8080
|
||||||
|
- Check that your changes appear correctly
|
||||||
|
- Verify navigation, social links, and metadata work
|
||||||
|
- Check site title and description in page source
|
||||||
|
|
||||||
|
## Common Issues
|
||||||
|
|
||||||
|
### "YAML parse error"
|
||||||
|
|
||||||
|
- Check for unquoted special characters (`:`, `&`, `#`, `|`, `>`)
|
||||||
|
- Verify indentation uses only spaces (2 spaces per level)
|
||||||
|
- Ensure closing quotes and braces are present
|
||||||
|
|
||||||
|
### Feature flag not working
|
||||||
|
|
||||||
|
- Check syntax: `feature: enabled: true` (colon after feature name)
|
||||||
|
- Verify spelling in Liquid template: `{% if site.feature.enabled %}`
|
||||||
|
- Clear browser cache if using old cached pages
|
||||||
|
|
||||||
|
### Social links not appearing
|
||||||
|
|
||||||
|
- Verify `_data/socials.yml` has correct entries
|
||||||
|
- Check icon identifiers exist in Font Awesome or Academicons
|
||||||
|
- Ensure `url:` field is not empty
|
||||||
|
|
||||||
|
## Trust These Instructions
|
||||||
|
|
||||||
|
When working with YAML configuration:
|
||||||
|
|
||||||
|
- Always test locally with `docker compose up` after changes
|
||||||
|
- Quote any string containing special characters
|
||||||
|
- Keep indentation consistent (2 spaces)
|
||||||
|
- Check output for YAML parse errors before committing
|
||||||
|
- Only search for additional details if encountering error messages not mentioned here
|
||||||
2
.github/workflows/broken-links.yml
vendored
2
.github/workflows/broken-links.yml
vendored
@ -51,4 +51,4 @@ jobs:
|
|||||||
with:
|
with:
|
||||||
fail: true
|
fail: true
|
||||||
# removed md files that include liquid tags
|
# removed md files that include liquid tags
|
||||||
args: --user-agent 'curl/7.54' --exclude-path README.md --exclude-path _pages/404.md --exclude-path _pages/blog.md --exclude-path _posts/2018-12-22-distill.md --exclude-path _posts/2023-04-24-videos.md --exclude-path _books/the_godfather.md --verbose --no-progress './**/*.md' './**/*.html'
|
args: --user-agent 'curl/7.54' --exclude-path README.md --exclude-path _pages/404.md --exclude-path _pages/blog.md --exclude-path _posts/2018-12-22-distill.md --exclude-path _posts/2023-04-24-videos.md --exclude-path _books/the_godfather.md --exclude-path .github/instructions/bibtex-bibliography.instructions.md --exclude-path .github/instructions/yaml-configuration.instructions.md --exclude-path .github/instructions/markdown-content.instructions.md --exclude-path .github/instructions/liquid-templates.instructions.md --exclude-path AGENTS.md --exclude-path SEO.md --verbose --no-progress './**/*.md' './**/*.html'
|
||||||
|
|||||||
58
.github/workflows/copilot-setup-steps.yml
vendored
Normal file
58
.github/workflows/copilot-setup-steps.yml
vendored
Normal file
@ -0,0 +1,58 @@
|
|||||||
|
name: "Copilot Setup Steps"
|
||||||
|
|
||||||
|
# Automatically run the setup steps when they are changed to allow for easy validation, and
|
||||||
|
# allow manual testing through the repository's "Actions" tab
|
||||||
|
on:
|
||||||
|
workflow_dispatch:
|
||||||
|
push:
|
||||||
|
paths:
|
||||||
|
- .github/workflows/copilot-setup-steps.yml
|
||||||
|
pull_request:
|
||||||
|
paths:
|
||||||
|
- .github/workflows/copilot-setup-steps.yml
|
||||||
|
|
||||||
|
jobs:
|
||||||
|
# The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot.
|
||||||
|
copilot-setup-steps:
|
||||||
|
runs-on: ubuntu-latest
|
||||||
|
|
||||||
|
# Set the permissions to the lowest permissions possible needed for your steps.
|
||||||
|
# Copilot will be given its own token for its operations.
|
||||||
|
permissions:
|
||||||
|
contents: read
|
||||||
|
|
||||||
|
# You can define any steps you want, and they will run before the agent starts.
|
||||||
|
# If you do not check out your code, Copilot will do this for you.
|
||||||
|
steps:
|
||||||
|
- name: Checkout code
|
||||||
|
uses: actions/checkout@v4
|
||||||
|
|
||||||
|
- name: Setup Ruby
|
||||||
|
uses: ruby/setup-ruby@v1
|
||||||
|
with:
|
||||||
|
ruby-version: "3.3.5"
|
||||||
|
bundler-cache: true
|
||||||
|
|
||||||
|
- name: Setup Python
|
||||||
|
uses: actions/setup-python@v5
|
||||||
|
with:
|
||||||
|
python-version: "3.13"
|
||||||
|
cache: "pip"
|
||||||
|
|
||||||
|
- name: Setup Node.js
|
||||||
|
uses: actions/setup-node@v4
|
||||||
|
with:
|
||||||
|
node-version: "latest"
|
||||||
|
cache: "npm"
|
||||||
|
|
||||||
|
- name: Install system dependencies
|
||||||
|
run: |
|
||||||
|
sudo apt-get update
|
||||||
|
sudo apt-get install -y imagemagick
|
||||||
|
|
||||||
|
- name: Install Python dependencies
|
||||||
|
run: |
|
||||||
|
pip3 install --upgrade nbconvert
|
||||||
|
|
||||||
|
- name: Install Node.js dependencies
|
||||||
|
run: npm ci
|
||||||
@ -1,2 +1,14 @@
|
|||||||
linkedin.com
|
.github/instructions/bibtex-bibliography.instructions.md
|
||||||
reddit.com
|
.github/instructions/liquid-templates.instructions.md
|
||||||
|
.github/instructions/markdown-content.instructions.md
|
||||||
|
.github/instructions/yaml-configuration.instructions.md
|
||||||
|
_books/the_godfather.md
|
||||||
|
_pages/404.md
|
||||||
|
_pages/blog.md
|
||||||
|
_posts/2018-12-22-distill.md
|
||||||
|
_posts/2023-04-24-videos.md
|
||||||
|
AGENTS.md
|
||||||
|
https://www.linkedin.com/
|
||||||
|
https://www.reddit.com/
|
||||||
|
README.md
|
||||||
|
SEO.md
|
||||||
|
|||||||
401
ACCESSIBILITY.md
401
ACCESSIBILITY.md
@ -1,401 +0,0 @@
|
|||||||
# 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 ❌
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
# Good ✅
|
|
||||||
|
|
||||||
|
|
||||||
```
|
|
||||||
|
|
||||||
**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.
|
|
||||||
119
AGENTS.md
Normal file
119
AGENTS.md
Normal file
@ -0,0 +1,119 @@
|
|||||||
|
# Agent Guidelines for al-folio
|
||||||
|
|
||||||
|
This is a hub for AI agents and automation tools working with the al-folio repository. It directs you to specialized resources by role and task type.
|
||||||
|
|
||||||
|
## Quick Links by Role
|
||||||
|
|
||||||
|
**Are you a coding agent?** → Read [`.github/copilot-instructions.md`](.github/copilot-instructions.md) first (tech stack, build, CI/CD, common pitfalls & solutions)
|
||||||
|
**Customizing the site?** → See [`.github/agents/customize.agent.md`](.github/agents/customize.agent.md)
|
||||||
|
**Writing documentation?** → See [`.github/agents/docs.agent.md`](.github/agents/docs.agent.md)
|
||||||
|
**Need setup/deployment help?** → [INSTALL.md](INSTALL.md)
|
||||||
|
**Troubleshooting & FAQ?** → [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||||
|
**Customization & theming?** → [CUSTOMIZE.md](CUSTOMIZE.md)
|
||||||
|
**Quick 5-min start?** → [QUICKSTART.md](QUICKSTART.md)
|
||||||
|
|
||||||
|
## Essential Commands
|
||||||
|
|
||||||
|
### Local Development (Docker)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# Initial setup & start dev server
|
||||||
|
docker compose pull && docker compose up
|
||||||
|
# Site runs at http://localhost:8080
|
||||||
|
|
||||||
|
# Rebuild with updated dependencies
|
||||||
|
docker compose up --build
|
||||||
|
|
||||||
|
# Stop containers
|
||||||
|
docker compose down
|
||||||
|
```
|
||||||
|
|
||||||
|
### Pre-Commit Checklist
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Format code
|
||||||
|
npm install --save-dev prettier @shopify/prettier-plugin-liquid # (first time only)
|
||||||
|
npx prettier . --write
|
||||||
|
|
||||||
|
# 2. Build locally
|
||||||
|
docker compose up --build
|
||||||
|
|
||||||
|
# 3. Verify site
|
||||||
|
# → Visit http://localhost:8080 and check navigation, pages, images, dark mode
|
||||||
|
|
||||||
|
# 4. Commit with clear message
|
||||||
|
git add .
|
||||||
|
git commit -m "type: description" # See "Commit Format" below
|
||||||
|
```
|
||||||
|
|
||||||
|
## Critical Configuration
|
||||||
|
|
||||||
|
When modifying `_config.yml`, these **must be updated together**:
|
||||||
|
|
||||||
|
**Personal site:** `url: https://username.github.io` + `baseurl:` (empty)
|
||||||
|
**Project site:** `url: https://username.github.io` + `baseurl: /repo-name/`
|
||||||
|
**YAML errors:** Quote strings with special characters: `title: "My: Cool Site"`
|
||||||
|
|
||||||
|
## Common Issues
|
||||||
|
|
||||||
|
For troubleshooting common build, deployment, and configuration issues, see:
|
||||||
|
|
||||||
|
- [Common Pitfalls & Workarounds](https://github.com/alshedivat/al-folio/blob/master/.github/copilot-instructions.md#common-pitfalls--workarounds) in copilot-instructions.md
|
||||||
|
- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions
|
||||||
|
- [GitHub Issues](https://github.com/alshedivat/al-folio/issues) to search for your specific problem
|
||||||
|
|
||||||
|
## Commit Format
|
||||||
|
|
||||||
|
```
|
||||||
|
<type>: <subject>
|
||||||
|
|
||||||
|
<body (optional)>
|
||||||
|
```
|
||||||
|
|
||||||
|
**Types:** `feat` (feature), `fix` (bug), `docs` (docs), `style` (formatting), `config` (configuration), `chore` (maintenance)
|
||||||
|
|
||||||
|
**Examples:**
|
||||||
|
|
||||||
|
```
|
||||||
|
feat: Add dark mode toggle button to header
|
||||||
|
fix: Correct baseurl in project site configuration
|
||||||
|
docs: Update INSTALL.md with Docker troubleshooting
|
||||||
|
style: Format all Liquid templates with Prettier
|
||||||
|
config: Enable blog section in _config.yml
|
||||||
|
chore: Update Jekyll dependencies with bundle update --all
|
||||||
|
```
|
||||||
|
|
||||||
|
**Always git add explicitly** – Do not stage everything with `git add .` unless you're certain of what's being committed. Check `git status` first.
|
||||||
|
|
||||||
|
## Code-Specific Instructions
|
||||||
|
|
||||||
|
Always consult the relevant instruction file for your code type:
|
||||||
|
|
||||||
|
| File Type | Instruction File |
|
||||||
|
| --------------------------------------------- | ----------------------------------------------------------------------------------------------- |
|
||||||
|
| Markdown content (`_posts/`, `_pages/`, etc.) | [markdown-content.instructions.md](.github/instructions/markdown-content.instructions.md) |
|
||||||
|
| YAML config (`_config.yml`, `_data/`) | [yaml-configuration.instructions.md](.github/instructions/yaml-configuration.instructions.md) |
|
||||||
|
| BibTeX (`_bibliography/`) | [bibtex-bibliography.instructions.md](.github/instructions/bibtex-bibliography.instructions.md) |
|
||||||
|
| Liquid templates (`_includes/`, `_layouts/`) | [liquid-templates.instructions.md](.github/instructions/liquid-templates.instructions.md) |
|
||||||
|
| JavaScript (`_scripts/`) | [javascript-scripts.instructions.md](.github/instructions/javascript-scripts.instructions.md) |
|
||||||
|
|
||||||
|
## Auto-Loaded Context
|
||||||
|
|
||||||
|
The following files are automatically available to you in this agent context:
|
||||||
|
|
||||||
|
- [`.github/copilot-instructions.md`](.github/copilot-instructions.md) – Primary technical reference
|
||||||
|
- [`.github/instructions/*.md`](.github/instructions/) – Code-specific instruction files (loaded when editing relevant file types)
|
||||||
|
|
||||||
|
Other files need to be accessed explicitly.
|
||||||
|
|
||||||
|
## What NOT to Commit
|
||||||
|
|
||||||
|
**Always obey [`.gitignore`](.gitignore).** It prevents accidental commits of:
|
||||||
|
|
||||||
|
- Build outputs (`_site/`, `.jekyll-cache/`, etc.)
|
||||||
|
- Dependencies (`node_modules/`, `Gemfile.lock`, `vendor/`)
|
||||||
|
- OS files (`.DS_store`)
|
||||||
|
- Editor temp files (`.idea/`, `.swp`, `.swo`)
|
||||||
|
- Secrets and API keys (never commit credentials)
|
||||||
|
|
||||||
|
If you create new files, ensure they follow the patterns in `.gitignore`.
|
||||||
158
ANALYTICS.md
158
ANALYTICS.md
@ -6,37 +6,41 @@ This guide helps you add website analytics to track visitor statistics and behav
|
|||||||
|
|
||||||
- [Analytics Setup Guide](#analytics-setup-guide)
|
- [Analytics Setup Guide](#analytics-setup-guide)
|
||||||
- [Overview](#overview)
|
- [Overview](#overview)
|
||||||
|
- [Supported Analytics Services](#supported-analytics-services)
|
||||||
- [Google Analytics](#google-analytics)
|
- [Google Analytics](#google-analytics)
|
||||||
- [Setup Steps](#setup-steps)
|
- [Setup Steps](#setup-steps)
|
||||||
- [Configuration](#configuration)
|
|
||||||
- [Privacy-Friendly Alternatives](#privacy-friendly-alternatives)
|
- [Privacy-Friendly Alternatives](#privacy-friendly-alternatives)
|
||||||
- [Plausible Analytics](#plausible-analytics)
|
|
||||||
- [GoAccess (Self-hosted)](#goaccess-self-hosted)
|
|
||||||
- [Pirsch Analytics](#pirsch-analytics)
|
- [Pirsch Analytics](#pirsch-analytics)
|
||||||
- [Openpanel Analytics](#openpanel-analytics)
|
- [Openpanel Analytics](#openpanel-analytics)
|
||||||
- [Other Analytics Services](#other-analytics-services)
|
- [Monitoring \& Performance](#monitoring--performance)
|
||||||
- [Cronitor](#cronitor)
|
- [Cronitor](#cronitor)
|
||||||
- [GDPR and Privacy Considerations](#gdpr-and-privacy-considerations)
|
- [GDPR and Privacy Considerations](#gdpr-and-privacy-considerations)
|
||||||
|
- [GDPR Checklist](#gdpr-checklist)
|
||||||
|
- [Privacy-first services (No GDPR cookie banner needed)](#privacy-first-services-no-gdpr-cookie-banner-needed)
|
||||||
|
- [Services requiring cookie consent](#services-requiring-cookie-consent)
|
||||||
- [Comparing Analytics Services](#comparing-analytics-services)
|
- [Comparing Analytics Services](#comparing-analytics-services)
|
||||||
<!--te-->
|
- [Next Steps](#next-steps)
|
||||||
|
|
||||||
|
<!--te-->
|
||||||
|
|
||||||
## Overview
|
## 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.
|
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 several analytics providers that you can enable in `_config.yml`.
|
||||||
|
|
||||||
**Available analytics in al-folio:**
|
## Supported Analytics Services
|
||||||
|
|
||||||
- **Google Analytics** (free, feature-rich, but privacy concerns)
|
Currently implemented in al-folio:
|
||||||
- **Plausible Analytics** (paid, privacy-first, GDPR-compliant)
|
|
||||||
- **Pirsch Analytics** (freemium, GDPR-compliant, European servers)
|
- **Google Analytics** – Free, feature-rich, but collects user data
|
||||||
- **Openpanel Analytics** (open-source, self-hosted option)
|
- **Pirsch Analytics** – GDPR-compliant, free tier available, European servers
|
||||||
- **Cronitor** (uptime monitoring + RUM analytics)
|
- **Openpanel Analytics** – Open-source option, privacy-focused
|
||||||
|
- **Cronitor** – Uptime monitoring with Real User Monitoring (RUM) analytics
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Google Analytics
|
## Google Analytics
|
||||||
|
|
||||||
Google Analytics is free and widely used. It provides detailed insights into visitor behavior but collects more user data.
|
Google Analytics is free and widely used. It provides detailed insights into visitor behavior.
|
||||||
|
|
||||||
### Setup Steps
|
### Setup Steps
|
||||||
|
|
||||||
@ -55,24 +59,17 @@ Google Analytics is free and widely used. It provides detailed insights into vis
|
|||||||
- Click **Data Streams** → **Web** (or your existing stream)
|
- Click **Data Streams** → **Web** (or your existing stream)
|
||||||
- Copy the **Measurement ID** (format: `G-XXXXXXXXXX`)
|
- Copy the **Measurement ID** (format: `G-XXXXXXXXXX`)
|
||||||
|
|
||||||
4. **Add to your site:**
|
4. **Enable in your site:**
|
||||||
- Open `_config.yml` in your repository
|
- Open `_config.yml` in your repository
|
||||||
- Find the `google_analytics:` line and add your ID:
|
- Set `enable_google_analytics: true`
|
||||||
```yaml
|
- Add your Measurement ID: `google_analytics: G-XXXXXXXXXX`
|
||||||
google_analytics: G-XXXXXXXXXX
|
|
||||||
```
|
|
||||||
- Commit and push
|
- Commit and push
|
||||||
- Wait for deployment to complete
|
|
||||||
|
|
||||||
5. **Verify it's working:**
|
5. **Verify it's working:**
|
||||||
- Visit your website
|
- Visit your website
|
||||||
- Go back to Google Analytics → **Real-time** tab
|
- Go back to Google Analytics → **Real-time** tab
|
||||||
- You should see your visit appear within a few seconds
|
- 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.
|
**Note:** Google Analytics takes 24-48 hours to start showing data trends.
|
||||||
|
|
||||||
---
|
---
|
||||||
@ -81,56 +78,6 @@ Google Analytics is auto-injected into your site once you set `google_analytics`
|
|||||||
|
|
||||||
If you're concerned about user privacy or GDPR compliance, consider these 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
|
### Pirsch Analytics
|
||||||
|
|
||||||
**Best for:** GDPR-compliant analytics without complex setup
|
**Best for:** GDPR-compliant analytics without complex setup
|
||||||
@ -148,11 +95,9 @@ If you're concerned about user privacy or GDPR compliance, consider these altern
|
|||||||
1. Sign up at [Pirsch.io](https://pirsch.io)
|
1. Sign up at [Pirsch.io](https://pirsch.io)
|
||||||
2. Add your domain
|
2. Add your domain
|
||||||
3. Copy the tracking code
|
3. Copy the tracking code
|
||||||
4. In `_config.yml`, add:
|
4. In `_config.yml`, set `enable_pirsch_analytics: true`
|
||||||
```yaml
|
5. Add your Site ID: `pirsch_analytics: YOUR_SITE_ID` (format: 32 characters)
|
||||||
pirsch_analytics: YOUR_SITE_ID # Format: 32 characters
|
6. Commit and push
|
||||||
```
|
|
||||||
5. Commit and push
|
|
||||||
|
|
||||||
(The site ID appears in your Pirsch dashboard.)
|
(The site ID appears in your Pirsch dashboard.)
|
||||||
|
|
||||||
@ -168,22 +113,19 @@ If you're concerned about user privacy or GDPR compliance, consider these altern
|
|||||||
- ✅ Self-hosted option available
|
- ✅ Self-hosted option available
|
||||||
- ✅ Privacy-focused
|
- ✅ Privacy-focused
|
||||||
- ✅ Modern dashboard
|
- ✅ Modern dashboard
|
||||||
- ❌ Younger project (fewer features)
|
|
||||||
|
|
||||||
**Setup:**
|
**Setup:**
|
||||||
|
|
||||||
1. Sign up at [Openpanel.dev](https://openpanel.dev)
|
1. Sign up at [Openpanel.dev](https://openpanel.dev)
|
||||||
2. Create a project for your website
|
2. Create a project for your website
|
||||||
3. Get your **Client ID**
|
3. Get your **Client ID**
|
||||||
4. In `_config.yml`, add:
|
4. In `_config.yml`, set `enable_openpanel_analytics: true`
|
||||||
```yaml
|
5. Add your Client ID: `openpanel_analytics: YOUR_CLIENT_ID` (format: UUID)
|
||||||
openpanel_analytics: YOUR_CLIENT_ID # Format: UUID
|
6. Commit and push
|
||||||
```
|
|
||||||
5. Commit and push
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## Other Analytics Services
|
## Monitoring & Performance
|
||||||
|
|
||||||
### Cronitor
|
### Cronitor
|
||||||
|
|
||||||
@ -195,11 +137,9 @@ Cronitor is an **uptime monitoring** service with RUM (Real User Monitoring) ana
|
|||||||
|
|
||||||
1. Create account at [Cronitor.io](https://cronitor.io)
|
1. Create account at [Cronitor.io](https://cronitor.io)
|
||||||
2. Get your **Site ID**
|
2. Get your **Site ID**
|
||||||
3. In `_config.yml`, add:
|
3. In `_config.yml`, set `enable_cronitor_analytics: true`
|
||||||
```yaml
|
4. Add your Site ID: `cronitor_analytics: YOUR_SITE_ID`
|
||||||
cronitor_analytics: YOUR_SITE_ID
|
5. Commit and push
|
||||||
```
|
|
||||||
4. Commit and push
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -216,45 +156,24 @@ If you're in the European Union or serve EU visitors, consider GDPR requirements
|
|||||||
|
|
||||||
### Privacy-first services (No GDPR cookie banner needed)
|
### Privacy-first services (No GDPR cookie banner needed)
|
||||||
|
|
||||||
- ✅ Plausible Analytics
|
|
||||||
- ✅ Pirsch Analytics
|
- ✅ Pirsch Analytics
|
||||||
- ✅ Openpanel Analytics
|
- ✅ Openpanel Analytics
|
||||||
- ✅ GoAccess
|
|
||||||
|
|
||||||
### Services requiring cookie consent
|
### Services requiring cookie consent
|
||||||
|
|
||||||
- ❌ Google Analytics (EU users must consent first)
|
- ❌ Google Analytics (EU users must consent first)
|
||||||
|
- ❌ Cronitor (collects user data via RUM)
|
||||||
### 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
|
## Comparing Analytics Services
|
||||||
|
|
||||||
| Service | Free | GDPR | Setup | Features | Best for |
|
| Service | Free | GDPR | Setup | Features | Best for |
|
||||||
| -------------------- | ------------ | ------------------- | ------ | ---------------- | --------------- |
|
| -------------------- | ------------ | ------------------- | ------ | ---------------- | -------------------------- |
|
||||||
| **Google Analytics** | ✅ | ⚠️ Requires consent | Easy | Detailed reports | Large sites |
|
| **Google Analytics** | ✅ | ⚠️ Requires consent | Easy | Detailed reports | Detailed tracking |
|
||||||
| **Plausible** | ❌ | ✅ | Easy | Simple, clear | Privacy-focused |
|
| **Pirsch** | ✅ Free tier | ✅ | Easy | Balanced | GDPR compliance |
|
||||||
| **Pirsch** | ✅ Free tier | ✅ | Easy | Balanced | GDPR compliance |
|
| **Openpanel** | ✅ | ✅ | Medium | Modern dashboard | Privacy-focused developers |
|
||||||
| **Openpanel** | ✅ | ✅ | Medium | Modern dashboard | Developers |
|
| **Cronitor** | Paid | ⚠️ Requires consent | Easy | Uptime + RUM | Uptime monitoring |
|
||||||
| **Cronitor** | Paid | ✅ | Easy | Uptime + RUM | Monitoring |
|
|
||||||
| **GoAccess** | ✅ | ✅ | Hard | Self-hosted logs | Cost-conscious |
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@ -263,6 +182,5 @@ For more information, see [Service Name's privacy policy](link-to-privacy-policy
|
|||||||
1. **Choose a service** based on your needs (privacy, features, budget)
|
1. **Choose a service** based on your needs (privacy, features, budget)
|
||||||
2. **Follow the setup guide** for your chosen service
|
2. **Follow the setup guide** for your chosen service
|
||||||
3. **Verify it's working** by visiting your site and checking the analytics dashboard
|
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**.
|
For more customization help, see [CUSTOMIZE.md](CUSTOMIZE.md).
|
||||||
|
|||||||
@ -10,15 +10,6 @@ If you would like to implement a new feature or a bug, please make sure you (or
|
|||||||
|
|
||||||
Note that since [#2048](https://github.com/alshedivat/al-folio/pull/2048) al-folio uses the [prettier formatter](https://prettier.io/) for its code, meaning all new submitted code must conform to its standard. If you don't have `prettier` installed for your setup and the `prettier` code check fails when submitting a PR, you can check the referred failed action in our repo. In that action there will be an artifact with an HTML diff showing the needed changes.
|
Note that since [#2048](https://github.com/alshedivat/al-folio/pull/2048) al-folio uses the [prettier formatter](https://prettier.io/) for its code, meaning all new submitted code must conform to its standard. If you don't have `prettier` installed for your setup and the `prettier` code check fails when submitting a PR, you can check the referred failed action in our repo. In that action there will be an artifact with an HTML diff showing the needed changes.
|
||||||
|
|
||||||
### Adding new social media information
|
|
||||||
|
|
||||||
To add new social media information, there are a few places you might need to modify. Currently, the template supports icons from [Academicons](https://jpswalsh.github.io/academicons/) and [Font Awesome](https://fontawesome.com/). For an example PR, check [Add HAL id to socials](https://github.com/alshedivat/al-folio/pull/3206/files). Note that the information in all these files are alphabetically sorted.
|
|
||||||
|
|
||||||
- \_data/socials.yml - your social media information
|
|
||||||
- \_includes/metadata.liquid - add social media information to site metadata
|
|
||||||
- \_includes/social.liquid - where the social media icon will be displayed
|
|
||||||
- \_scripts/search.liquid.js - make the social media information appear in search
|
|
||||||
|
|
||||||
## GitHub Copilot Agents
|
## GitHub Copilot Agents
|
||||||
|
|
||||||
This repository includes two specialized GitHub Copilot agents to assist with development and documentation:
|
This repository includes two specialized GitHub Copilot agents to assist with development and documentation:
|
||||||
@ -45,6 +36,23 @@ The **Documentation Agent** (`.github/agents/docs.agent.md`) maintains the proje
|
|||||||
|
|
||||||
The documentation agent is primarily intended for maintainers and contributors who are updating the project documentation.
|
The documentation agent is primarily intended for maintainers and contributors who are updating the project documentation.
|
||||||
|
|
||||||
|
### Custom Instruction Files
|
||||||
|
|
||||||
|
To enhance GitHub Copilot's effectiveness when working with specific file types, this repository includes custom instruction files in `.github/instructions/`:
|
||||||
|
|
||||||
|
- **`.github/copilot-instructions.md`** – Main Copilot instructions with repository overview, build process, tech stack, project layout, CI/CD pipelines, and common pitfalls
|
||||||
|
- **`.github/instructions/liquid-templates.instructions.md`** – Guidance for modifying Liquid template files (`.liquid`)
|
||||||
|
- **`.github/instructions/yaml-configuration.instructions.md`** – Guidance for configuration and data files (`_config.yml`, `_data/**/*.yml`)
|
||||||
|
- **`.github/instructions/bibtex-bibliography.instructions.md`** – Guidance for bibliography files (`.bib`, `_bibliography/**`)
|
||||||
|
- **`.github/instructions/markdown-content.instructions.md`** – Guidance for content files across collections (`_books/`, `_news/`, `_pages/`, `_posts/`, `_projects/`, `_teachings/`)
|
||||||
|
- **`.github/instructions/javascript-scripts.instructions.md`** – Guidance for JavaScript files in `_scripts/`
|
||||||
|
|
||||||
|
These files help Copilot agents understand project conventions, build requirements, and development workflows without requiring codebase exploration.
|
||||||
|
|
||||||
|
### Copilot Environment Setup
|
||||||
|
|
||||||
|
A GitHub Actions workflow (`.github/workflows/copilot-setup-steps.yml`) automatically configures the Copilot environment with required dependencies (Ruby 3.3.5, Python 3.13, Node.js, ImageMagick, nbconvert) before agent execution.
|
||||||
|
|
||||||
### Important: Verify Agent Output
|
### Important: Verify Agent Output
|
||||||
|
|
||||||
While these agents are designed to assist you, **they can make mistakes or produce incorrect information**. Always review and verify the output before applying it to your repository:
|
While these agents are designed to assist you, **they can make mistakes or produce incorrect information**. Always review and verify the output before applying it to your repository:
|
||||||
|
|||||||
106
CUSTOMIZE.md
106
CUSTOMIZE.md
@ -126,6 +126,16 @@ The configuration file [\_config.yml](_config.yml) contains the main configurati
|
|||||||
|
|
||||||
All changes made to this file are only visible after you rebuild the website. That means that you need to run `bundle exec jekyll serve` again if you are running the website locally or push your changes to GitHub if you are using GitHub Pages. All other changes are visible immediately, you only need to refresh the page.
|
All changes made to this file are only visible after you rebuild the website. That means that you need to run `bundle exec jekyll serve` again if you are running the website locally or push your changes to GitHub if you are using GitHub Pages. All other changes are visible immediately, you only need to refresh the page.
|
||||||
|
|
||||||
|
If changes don't appear after refreshing, try:
|
||||||
|
|
||||||
|
- **Hard refresh** to reload the page ignoring cached content:
|
||||||
|
- [Shift + F5 on Chromium-based browsers](https://support.google.com/chrome/answer/157179#zippy=%2Cwebpage-shortcuts)
|
||||||
|
- [Ctrl + F5 on Firefox-based browsers](https://support.mozilla.org/en-US/kb/keyboard-shortcuts-perform-firefox-tasks-quickly)
|
||||||
|
- **Clear your browser cache** completely
|
||||||
|
- **Use a private/incognito session** to ensure no cached content:
|
||||||
|
- [Chrome](https://support.google.com/chrome/answer/95464)
|
||||||
|
- [Firefox](https://support.mozilla.org/en-US/kb/private-browsing-use-firefox-without-history)
|
||||||
|
|
||||||
## GitHub Copilot Customization Agent
|
## GitHub Copilot Customization Agent
|
||||||
|
|
||||||
This repository includes a specialized GitHub Copilot agent (`.github/agents/customize.agent.md`) designed to help you customize your al-folio website. The agent acts as an expert assistant that can:
|
This repository includes a specialized GitHub Copilot agent (`.github/agents/customize.agent.md`) designed to help you customize your al-folio website. The agent acts as an expert assistant that can:
|
||||||
@ -235,7 +245,7 @@ Understanding al-folio's technology stack will help you better customize and ext
|
|||||||
- **JavaScript**: Minimal JavaScript is used for interactive features like the dark mode toggle, search functionality, and dynamic content rendering.
|
- **JavaScript**: Minimal JavaScript is used for interactive features like the dark mode toggle, search functionality, and dynamic content rendering.
|
||||||
- **MathJax**: For rendering mathematical equations in LaTeX format on your pages and blog posts.
|
- **MathJax**: For rendering mathematical equations in LaTeX format on your pages and blog posts.
|
||||||
- **Mermaid**: For creating diagrams (flowcharts, sequence diagrams, etc.) directly in Markdown.
|
- **Mermaid**: For creating diagrams (flowcharts, sequence diagrams, etc.) directly in Markdown.
|
||||||
- **Font Awesome and Academicons**: Icon libraries used throughout the theme for visual elements.
|
- **Font Awesome, Academicons, and Scholar Icons**: Icon libraries used throughout the theme for visual elements.
|
||||||
|
|
||||||
### Backend
|
### Backend
|
||||||
|
|
||||||
@ -247,16 +257,16 @@ Understanding al-folio's technology stack will help you better customize and ext
|
|||||||
- Minify CSS and JavaScript
|
- Minify CSS and JavaScript
|
||||||
|
|
||||||
- **Ruby Gems** (Jekyll plugins): The project uses several Ruby plugins to extend Jekyll's functionality:
|
- **Ruby Gems** (Jekyll plugins): The project uses several Ruby plugins to extend Jekyll's functionality:
|
||||||
- `jekyll-scholar`: Manages bibliography files (BibTeX) and generates publication pages with citations
|
|
||||||
- `jekyll-archives-v2`: Creates archive pages for posts and collections organized by category, tag, or date
|
|
||||||
- `jekyll-paginate-v2`: Handles pagination for blog posts and archives
|
|
||||||
- `jekyll-feed`: Generates an Atom (RSS-like) feed for your content
|
|
||||||
- `jekyll-toc`: Automatically generates table of contents for pages with headers
|
|
||||||
- `jekyll-jupyter-notebook`: Integrates Jupyter notebooks into your site
|
|
||||||
- `jekyll-tabs`: Adds tabbed content support
|
|
||||||
- `jemoji`: Converts emoji shortcodes to emoji images
|
|
||||||
- `jekyll-minifier`: Minifies HTML, CSS, and JavaScript for better performance
|
|
||||||
- `classifier-reborn`: Used for categorizing and finding related blog posts
|
- `classifier-reborn`: Used for categorizing and finding related blog posts
|
||||||
|
- `jekyll-archives-v2`: Creates archive pages for posts and collections organized by category, tag, or date
|
||||||
|
- `jekyll-feed`: Generates an Atom (RSS-like) feed for your content
|
||||||
|
- `jekyll-jupyter-notebook`: Integrates Jupyter notebooks into your site
|
||||||
|
- `jekyll-minifier`: Minifies HTML, CSS, and JavaScript for better performance
|
||||||
|
- `jekyll-paginate-v2`: Handles pagination for blog posts and archives
|
||||||
|
- `jekyll-scholar`: Manages bibliography files (BibTeX) and generates publication pages with citations
|
||||||
|
- `jekyll-tabs`: Adds tabbed content support
|
||||||
|
- `jekyll-toc`: Automatically generates table of contents for pages with headers
|
||||||
|
- `jemoji`: Converts emoji shortcodes to emoji images
|
||||||
- Other utilities: `jekyll-link-attributes`, `jekyll-imagemagick`, `jekyll-twitter-plugin`, `jekyll-get-json`, and more
|
- Other utilities: `jekyll-link-attributes`, `jekyll-imagemagick`, `jekyll-twitter-plugin`, `jekyll-get-json`, and more
|
||||||
|
|
||||||
- **Python**: Used for utility scripts like citation updates via Google Scholar (located in `bin/`)
|
- **Python**: Used for utility scripts like citation updates via Google Scholar (located in `bin/`)
|
||||||
@ -403,7 +413,7 @@ You can easily create your own collections for any type of content—teaching ma
|
|||||||
|
|
||||||
### Creating a new collection
|
### Creating a new collection
|
||||||
|
|
||||||
To create a new collection, follow these steps. We will create a `teaching` collection, but you can replace `teaching` with any name you prefer:
|
To create a new collection, follow these steps. We will create a `courses` collection, but you can replace `courses` with any name you prefer:
|
||||||
|
|
||||||
1. **Add the collection to `_config.yml`**
|
1. **Add the collection to `_config.yml`**
|
||||||
|
|
||||||
@ -417,9 +427,9 @@ To create a new collection, follow these steps. We will create a `teaching` coll
|
|||||||
output: true
|
output: true
|
||||||
projects:
|
projects:
|
||||||
output: true
|
output: true
|
||||||
teaching:
|
courses:
|
||||||
output: true
|
output: true
|
||||||
permalink: /teaching/:path/
|
permalink: /courses/:path/
|
||||||
```
|
```
|
||||||
|
|
||||||
- `output: true` makes the collection items accessible as separate pages
|
- `output: true` makes the collection items accessible as separate pages
|
||||||
@ -428,10 +438,10 @@ To create a new collection, follow these steps. We will create a `teaching` coll
|
|||||||
|
|
||||||
2. **Create a folder for your collection items**
|
2. **Create a folder for your collection items**
|
||||||
|
|
||||||
Create a new folder in the root directory with an underscore prefix, matching your collection name. For a `teaching` collection, create `_teaching/`:
|
Create a new folder in the root directory with an underscore prefix, matching your collection name. For a `courses` collection, create `_courses/`:
|
||||||
|
|
||||||
```text
|
```text
|
||||||
_teaching/
|
_courses/
|
||||||
├── course_1.md
|
├── course_1.md
|
||||||
├── course_2.md
|
├── course_2.md
|
||||||
└── course_3.md
|
└── course_3.md
|
||||||
@ -439,30 +449,36 @@ To create a new collection, follow these steps. We will create a `teaching` coll
|
|||||||
|
|
||||||
3. **Create a landing page for your collection**
|
3. **Create a landing page for your collection**
|
||||||
|
|
||||||
Add a Markdown file in `_pages/` (e.g., `teaching.md`) that will serve as the main page for your collection. You can use [\_pages/projects.md](_pages/projects.md) or [\_pages/books.md](_pages/books.md) as a template and adapt it for your needs.
|
Add a Markdown file in `_pages/` (e.g., `courses.md`) that will serve as the main page for your collection. You can use [\_pages/projects.md](_pages/projects.md) or [\_pages/books.md](_pages/books.md) as a template and adapt it for your needs.
|
||||||
|
|
||||||
In your landing page, access your collection using the `site.COLLECTION_NAME` variable:
|
In your landing page, access your collection using the `site.COLLECTION_NAME` variable:
|
||||||
|
|
||||||
```liquid
|
```liquid
|
||||||
{% assign teaching_items = site.teaching | sort: 'date' | reverse %}
|
{% assign course_items = site.courses | sort: 'date' | reverse %}
|
||||||
|
|
||||||
{% for item in teaching_items %}
|
{% for item in course_items %}
|
||||||
<h3>{{ item.title }}</h3>
|
<h3>{{ item.title }}</h3>
|
||||||
<p>{{ item.content }}</p>
|
<p>{{ item.content }}</p>
|
||||||
{% endfor %}
|
{% endfor %}
|
||||||
```
|
```
|
||||||
|
|
||||||
Replace `COLLECTION_NAME` with your actual collection name (e.g., `site.teaching`).
|
4. **Add a navigation link to your collection page**
|
||||||
|
|
||||||
4. **Add a link to your collection page**
|
Update [\_pages/dropdown.md](_pages/dropdown.md) or the navigation configuration of your page. In the frontmatter of your collection landing page (e.g., `_pages/courses.md`), add:
|
||||||
|
|
||||||
Update [\_pages/dropdown.md](_pages/dropdown.md) or the navigation configuration in [\_config.yml](_config.yml) to add a menu link to your new page.
|
```yaml
|
||||||
|
nav: true
|
||||||
|
nav_order: 5
|
||||||
|
```
|
||||||
|
|
||||||
|
- `nav: true` makes the page appear in the navigation menu
|
||||||
|
- `nav_order` sets the position in the menu (1 = first, 2 = second, etc.)
|
||||||
|
|
||||||
5. **Create collection items**
|
5. **Create collection items**
|
||||||
|
|
||||||
Add Markdown files in your new collection folder (e.g., `_teaching/`) with appropriate frontmatter and content.
|
Add Markdown files in your new collection folder (e.g., `_courses/`) with appropriate frontmatter and content.
|
||||||
|
|
||||||
For more information regarding collections, check [Jekyll official documentation](https://jekyllrb.com/docs/collections/) and [step-by=step guide](https://jekyllrb.com/docs/step-by-step/09-collections/).
|
For more information regarding collections, check [Jekyll official documentation](https://jekyllrb.com/docs/collections/) and [step-by-step guide](https://jekyllrb.com/docs/step-by-step/09-collections/).
|
||||||
|
|
||||||
### Using frontmatter fields in your collection
|
### Using frontmatter fields in your collection
|
||||||
|
|
||||||
@ -625,20 +641,36 @@ A variety of beautiful theme colors have been selected for you to choose from. T
|
|||||||
You can customize the layout and user interface in [\_config.yml](_config.yml):
|
You can customize the layout and user interface in [\_config.yml](_config.yml):
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
navbar_fixed: true
|
|
||||||
footer_fixed: true
|
|
||||||
back_to_top: true
|
back_to_top: true
|
||||||
|
footer_fixed: true
|
||||||
max_width: 930px
|
max_width: 930px
|
||||||
|
navbar_fixed: true
|
||||||
```
|
```
|
||||||
|
|
||||||
- `navbar_fixed`: When `true`, the navigation bar stays fixed at the top of the page when scrolling. When `false`, it scrolls with the page content.
|
|
||||||
- `footer_fixed`: When `true`, the footer remains fixed at the bottom of the viewport. When `false`, it appears at the end of the page content.
|
|
||||||
- `back_to_top`: Displays a "back to top" button in the footer. When clicked, it smoothly scrolls the page back to the top.
|
- `back_to_top`: Displays a "back to top" button in the footer. When clicked, it smoothly scrolls the page back to the top.
|
||||||
|
- `footer_fixed`: When `true`, the footer remains fixed at the bottom of the viewport. When `false`, it appears at the end of the page content.
|
||||||
- `max_width`: Controls the maximum width of the main content area in pixels. The default is `930px`. You can adjust this to make your content wider or narrower.
|
- `max_width`: Controls the maximum width of the main content area in pixels. The default is `930px`. You can adjust this to make your content wider or narrower.
|
||||||
|
- `navbar_fixed`: When `true`, the navigation bar stays fixed at the top of the page when scrolling. When `false`, it scrolls with the page content.
|
||||||
|
|
||||||
## Adding social media information
|
## Adding social media information
|
||||||
|
|
||||||
You can add your social media links by adding the specified information in the [\_data/socials.yml](_data/socials.yml) file. This information will appear at the bottom of the `About` page and in the search results by default, but this could be changed to appear at the header of the page by setting `enable_navbar_social: true` and doesn't appear in the search by setting `socials_in_search: false`, both in [\_config.yml](_config.yml).
|
Social media information is managed through the [`jekyll-socials` plugin](https://github.com/george-gca/jekyll-socials). To add your social media links:
|
||||||
|
|
||||||
|
1. Edit [`_data/socials.yml`](_data/socials.yml) to add your social profiles
|
||||||
|
2. The plugin will automatically display the social icons based on the order they are defined in the file (see the comments at the top of `_data/socials.yml`)
|
||||||
|
|
||||||
|
The template supports icons from:
|
||||||
|
|
||||||
|
- [Academicons](https://jpswalsh.github.io/academicons/)
|
||||||
|
- [Font Awesome](https://fontawesome.com/)
|
||||||
|
- [Scholar Icons](https://louisfacun.github.io/scholar-icons/)
|
||||||
|
|
||||||
|
Social media links will appear at the bottom of the `About` page and in the search results by default. You can customize this behavior in [`_config.yml`](_config.yml):
|
||||||
|
|
||||||
|
- `enable_navbar_social: true` – Display social links in the navigation bar
|
||||||
|
- `socials_in_search: false` – Remove social links from search results
|
||||||
|
|
||||||
|
For more details, see the [`jekyll-socials` documentation](https://github.com/george-gca/jekyll-socials).
|
||||||
|
|
||||||
## Adding a newsletter
|
## Adding a newsletter
|
||||||
|
|
||||||
@ -651,16 +683,16 @@ Depending on your specified footer behavior, the sign up form either will appear
|
|||||||
The theme includes a powerful search functionality that can be customized in [\_config.yml](_config.yml):
|
The theme includes a powerful search functionality that can be customized in [\_config.yml](_config.yml):
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
bib_search: true
|
||||||
|
posts_in_search: true
|
||||||
search_enabled: true
|
search_enabled: true
|
||||||
socials_in_search: true
|
socials_in_search: true
|
||||||
posts_in_search: true
|
|
||||||
bib_search: true
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
- `bib_search`: Enables search within your publications/bibliography. When enabled, a search box appears on the publications page, allowing visitors to filter publications by title, author, venue, or year.
|
||||||
|
- `posts_in_search`: Includes blog posts in the search index. Users can search for posts by title, content, or tags.
|
||||||
- `search_enabled`: Enables the site-wide search feature. When enabled, a search box appears in the navigation bar, allowing users to search across your site content.
|
- `search_enabled`: Enables the site-wide search feature. When enabled, a search box appears in the navigation bar, allowing users to search across your site content.
|
||||||
- `socials_in_search`: Includes your social media links and contact information in search results. This makes it easier for visitors to find ways to connect with you.
|
- `socials_in_search`: Includes your social media links and contact information in search results. This makes it easier for visitors to find ways to connect with you.
|
||||||
- `posts_in_search`: Includes blog posts in the search index. Users can search for posts by title, content, or tags.
|
|
||||||
- `bib_search`: Enables search within your publications/bibliography. When enabled, a search box appears on the publications page, allowing visitors to filter publications by title, author, venue, or year.
|
|
||||||
|
|
||||||
All these search features work in real-time and do not require a page reload.
|
All these search features work in real-time and do not require a page reload.
|
||||||
|
|
||||||
@ -694,7 +726,7 @@ Place the image file in `assets/img/publication_preview/`.
|
|||||||
|
|
||||||
## Adding a Google Calendar
|
## Adding a Google Calendar
|
||||||
|
|
||||||
You can embed a Google Calendar on any page by using the `calendar.liquid` include. The calendar will automatically adapt to light and dark themes.
|
You can embed a Google Calendar on any page by using the `calendar.liquid` include.
|
||||||
|
|
||||||
### Basic usage
|
### Basic usage
|
||||||
|
|
||||||
@ -711,7 +743,7 @@ Replace:
|
|||||||
|
|
||||||
### Enable the calendar script for your page
|
### Enable the calendar script for your page
|
||||||
|
|
||||||
To prevent unnecessary script loading, add `calendar: true` to the frontmatter of any page that displays a calendar:
|
To enable the calendar on your page, add `calendar: true` to the frontmatter:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
---
|
---
|
||||||
@ -721,6 +753,8 @@ calendar: true
|
|||||||
---
|
---
|
||||||
```
|
```
|
||||||
|
|
||||||
|
This setting prevents unnecessary script loading for pages that don't display a calendar.
|
||||||
|
|
||||||
### Optional: Customize the calendar style
|
### Optional: Customize the calendar style
|
||||||
|
|
||||||
You can optionally customize the iframe styling using the `style` parameter:
|
You can optionally customize the iframe styling using the `style` parameter:
|
||||||
@ -750,7 +784,7 @@ third_party_libraries:
|
|||||||
|
|
||||||
- `download`: When `false` (default), libraries are loaded from CDNs. When `true`, the specified library versions are downloaded during build and served from your site. This can improve performance but increases your repository size.
|
- `download`: When `false` (default), libraries are loaded from CDNs. When `true`, the specified library versions are downloaded during build and served from your site. This can improve performance but increases your repository size.
|
||||||
- `version`: Specifies which version of each library to use. Update this to use a newer version.
|
- `version`: Specifies which version of each library to use. Update this to use a newer version.
|
||||||
- `url`: Template URLs for loading the library. The `{{version}}` placeholder is replaced with the version number.
|
- `url`: Template URLs for loading the library. The `{{version}}` placeholder is replaced with the version number automatically.
|
||||||
- `integrity`: [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hashes ensure that the library hasn't been tampered with. When updating a library version, you should also update its integrity hash.
|
- `integrity`: [Subresource Integrity (SRI)](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) hashes ensure that the library hasn't been tampered with. When updating a library version, you should also update its integrity hash.
|
||||||
|
|
||||||
To update a library:
|
To update a library:
|
||||||
@ -855,7 +889,7 @@ To remove the repositories, you can:
|
|||||||
|
|
||||||
### You can also remove pages through commenting out front-matter blocks
|
### You can also remove pages through commenting out front-matter blocks
|
||||||
|
|
||||||
For `.md` files in [\pages](_pages/) directory, if you do not want to completely edit or delete them but save for later use, you can temporarily disable these variables. But be aware that Jekyll only recognizes front matter when it appears as uncommented. The layout, permalink, and other front-matter behavior are disabled for that file.
|
For `.md` files in [\_pages](_pages/) directory, if you do not want to completely edit or delete them but save for later use, you can temporarily disable these variables. But be aware that Jekyll only recognizes front matter when it appears as uncommented. The layout, permalink, and other front-matter behavior are disabled for that file.
|
||||||
|
|
||||||
For example, books.md do:
|
For example, books.md do:
|
||||||
|
|
||||||
|
|||||||
12
FAQ.md
12
FAQ.md
@ -6,16 +6,16 @@ Here are some frequently asked questions. If you have a different question, plea
|
|||||||
|
|
||||||
- [Frequently Asked Questions](#frequently-asked-questions)
|
- [Frequently Asked Questions](#frequently-asked-questions)
|
||||||
- [After I create a new repository from this template and setup the repo, I get a deployment error. Isn't the website supposed to correctly deploy automatically?](#after-i-create-a-new-repository-from-this-template-and-setup-the-repo-i-get-a-deployment-error-isnt-the-website-supposed-to-correctly-deploy-automatically)
|
- [After I create a new repository from this template and setup the repo, I get a deployment error. Isn't the website supposed to correctly deploy automatically?](#after-i-create-a-new-repository-from-this-template-and-setup-the-repo-i-get-a-deployment-error-isnt-the-website-supposed-to-correctly-deploy-automatically)
|
||||||
- [I am using a custom domain (e.g., foo.com). My custom domain becomes blank in the repository settings after each deployment. How do I fix that?](#i-am-using-a-custom-domain-eg-foocom-my-custom-domain-becomes-blank-in-the-repository-settings-after-each-deployment-how-do-i-fix-that)
|
- [I am using a custom domain (e.g., `foo.com`). My custom domain becomes blank in the repository settings after each deployment. How do I fix that?](#i-am-using-a-custom-domain-eg-foocom-my-custom-domain-becomes-blank-in-the-repository-settings-after-each-deployment-how-do-i-fix-that)
|
||||||
- [My webpage works locally. But after deploying, it fails to build and throws Unknown tag 'toc'. How do I fix that?](#my-webpage-works-locally-but-after-deploying-it-fails-to-build-and-throws-unknown-tag-toc-how-do-i-fix-that)
|
- [My webpage works locally. But after deploying, it fails to build and throws `Unknown tag 'toc'`. How do I fix that?](#my-webpage-works-locally-but-after-deploying-it-fails-to-build-and-throws-unknown-tag-toc-how-do-i-fix-that)
|
||||||
- [My webpage works locally. But after deploying, it is not displayed correctly (CSS and JS are not loaded properly). How do I fix that?](#my-webpage-works-locally-but-after-deploying-it-is-not-displayed-correctly-css-and-js-are-not-loaded-properly-how-do-i-fix-that)
|
- [My webpage works locally. But after deploying, it is not displayed correctly (CSS and JS are not loaded properly). How do I fix that?](#my-webpage-works-locally-but-after-deploying-it-is-not-displayed-correctly-css-and-js-are-not-loaded-properly-how-do-i-fix-that)
|
||||||
- [Atom feed doesn't work. Why?](#atom-feed-doesnt-work-why)
|
- [Atom feed doesn't work. Why?](#atom-feed-doesnt-work-why)
|
||||||
- [My site doesn't work when I enable related_blog_posts. Why?](#my-site-doesnt-work-when-i-enable-related_blog_posts-why)
|
- [My site doesn't work when I enable `related_blog_posts`. Why?](#my-site-doesnt-work-when-i-enable-related_blog_posts-why)
|
||||||
- [When trying to deploy, it's asking for github login credentials, which github disabled password authentication and it exits with an error. How to fix?](#when-trying-to-deploy-its-asking-for-github-login-credentials-which-github-disabled-password-authentication-and-it-exits-with-an-error-how-to-fix)
|
- [When trying to deploy, it's asking for github login credentials, which github disabled password authentication and it exits with an error. How to fix?](#when-trying-to-deploy-its-asking-for-github-login-credentials-which-github-disabled-password-authentication-and-it-exits-with-an-error-how-to-fix)
|
||||||
- [When I manually run the Lighthouse Badger workflow, it fails with Error: Input required and not supplied: token. How do I fix that?](#when-i-manually-run-the-lighthouse-badger-workflow-it-fails-with-error-input-required-and-not-supplied-token-how-do-i-fix-that)
|
- [When I manually run the Lighthouse Badger workflow, it fails with `Error: Input required and not supplied: token`. How do I fix that?](#when-i-manually-run-the-lighthouse-badger-workflow-it-fails-with-error-input-required-and-not-supplied-token-how-do-i-fix-that)
|
||||||
- [My code runs fine locally, but when I create a commit and submit it, it fails with prettier code formatter workflow run failed for main branch. How do I fix that?](#my-code-runs-fine-locally-but-when-i-create-a-commit-and-submit-it-it-fails-with-prettier-code-formatter-workflow-run-failed-for-main-branch-how-do-i-fix-that)
|
- [My code runs fine locally, but when I create a commit and submit it, it fails with `prettier code formatter workflow run failed for main branch`. How do I fix that?](#my-code-runs-fine-locally-but-when-i-create-a-commit-and-submit-it-it-fails-with-prettier-code-formatter-workflow-run-failed-for-main-branch-how-do-i-fix-that)
|
||||||
- [After I update my site with some new content, even a small change, the GitHub action throws an error or displays a warning. What happened?](#after-i-update-my-site-with-some-new-content-even-a-small-change-the-github-action-throws-an-error-or-displays-a-warning-what-happened)
|
- [After I update my site with some new content, even a small change, the GitHub action throws an error or displays a warning. What happened?](#after-i-update-my-site-with-some-new-content-even-a-small-change-the-github-action-throws-an-error-or-displays-a-warning-what-happened)
|
||||||
- [I am trying to deploy my site, but it fails with Could not find gem 'jekyll-diagrams' in locally installed gems. How do I fix that?](#i-am-trying-to-deploy-my-site-but-it-fails-with-could-not-find-gem-jekyll-diagrams-in-locally-installed-gems-how-do-i-fix-that)
|
- [I am trying to deploy my site, but it fails with `Could not find gem 'jekyll-diagrams' in locally installed gems`. How do I fix that?](#i-am-trying-to-deploy-my-site-but-it-fails-with-could-not-find-gem-jekyll-diagrams-in-locally-installed-gems-how-do-i-fix-that)
|
||||||
- [How can I update Academicons version on the template](#how-can-i-update-academicons-version-on-the-template)
|
- [How can I update Academicons version on the template](#how-can-i-update-academicons-version-on-the-template)
|
||||||
- [How can I update Font Awesome version on the template](#how-can-i-update-font-awesome-version-on-the-template)
|
- [How can I update Font Awesome version on the template](#how-can-i-update-font-awesome-version-on-the-template)
|
||||||
- [What do all these GitHub actions/workflows mean?](#what-do-all-these-github-actionsworkflows-mean)
|
- [What do all these GitHub actions/workflows mean?](#what-do-all-these-github-actionsworkflows-mean)
|
||||||
|
|||||||
48
INSTALL.md
48
INSTALL.md
@ -18,7 +18,7 @@
|
|||||||
- [For project pages](#for-project-pages)
|
- [For project pages](#for-project-pages)
|
||||||
- [Enabling automatic deployment](#enabling-automatic-deployment)
|
- [Enabling automatic deployment](#enabling-automatic-deployment)
|
||||||
- [Manual deployment to GitHub Pages](#manual-deployment-to-github-pages)
|
- [Manual deployment to GitHub Pages](#manual-deployment-to-github-pages)
|
||||||
- [Deploy on <a href="https://www.netlify.com/" rel="nofollow">Netlify</a>](https://www.netlify.com/)
|
- [Deploy on Netlify](#deploy-on-netlify)
|
||||||
- [Deployment to another hosting server (non GitHub Pages)](#deployment-to-another-hosting-server-non-github-pages)
|
- [Deployment to another hosting server (non GitHub Pages)](#deployment-to-another-hosting-server-non-github-pages)
|
||||||
- [Deployment to a separate repository (advanced users only)](#deployment-to-a-separate-repository-advanced-users-only)
|
- [Deployment to a separate repository (advanced users only)](#deployment-to-a-separate-repository-advanced-users-only)
|
||||||
- [Maintaining Dependencies](#maintaining-dependencies)
|
- [Maintaining Dependencies](#maintaining-dependencies)
|
||||||
@ -47,7 +47,7 @@ Starting version [v0.3.5](https://github.com/alshedivat/al-folio/releases/tag/v0
|
|||||||
Once everything is deployed, you can download the repository to your machine and start customizing it locally:
|
Once everything is deployed, you can download the repository to your machine and start customizing it locally:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ git clone git@github.com:<your-username>/<your-repo-name>.git
|
git clone git@github.com:<your-username>/<your-repo-name>.git
|
||||||
```
|
```
|
||||||
|
|
||||||
See [Local setup using Docker](#local-setup-using-docker-recommended) or other sections below for local development options.
|
See [Local setup using Docker](#local-setup-using-docker-recommended) or other sections below for local development options.
|
||||||
@ -66,8 +66,8 @@ You need to take the following steps to get `al-folio` up and running on your lo
|
|||||||
- Finally, run the following command that will pull the latest pre-built image from DockerHub and will run your website.
|
- Finally, run the following command that will pull the latest pre-built image from DockerHub and will run your website.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ docker compose pull
|
docker compose pull
|
||||||
$ docker compose up
|
docker compose up
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that when you run it for the first time, it will download a docker image of size 400MB or so. To see the template running, open your browser and go to `http://localhost:8080`. You should see a copy of the theme's demo website.
|
Note that when you run it for the first time, it will download a docker image of size 400MB or so. To see the template running, open your browser and go to `http://localhost:8080`. You should see a copy of the theme's demo website.
|
||||||
@ -83,12 +83,12 @@ Now, feel free to customize the theme however you like (don't forget to change t
|
|||||||
Build and run a new docker image using:
|
Build and run a new docker image using:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ docker compose up --build
|
docker compose up --build
|
||||||
```
|
```
|
||||||
|
|
||||||
> If you want to update jekyll, install new ruby packages, etc., all you have to do is build the image again using `--force-recreate` argument at the end of the previous command! It will download Ruby and Jekyll and install all Ruby packages again from scratch.
|
> If you want to update jekyll, install new ruby packages, etc., all you have to do is build the image again using `--force-recreate` argument at the end of the previous command! It will download Ruby and Jekyll and install all Ruby packages again from scratch.
|
||||||
|
|
||||||
If you want to use a specific docker version, you can do so by changing `latest` tag to `your_version` in `docker-compose.yaml`. For example, you might have created your website on `v0.10.0` and you want to stick with that.
|
If you want to use a specific docker version, you can do so by changing the version tag to `your_version` in `docker-compose.yaml` (the `v0.16.3` in `image: amirpourmand/al-folio:v0.16.3`). For example, you might have created your website on `v0.10.0` and you want to stick with that.
|
||||||
|
|
||||||
### Have Bugs on Docker Image?
|
### Have Bugs on Docker Image?
|
||||||
|
|
||||||
@ -132,10 +132,10 @@ For a hands-on walkthrough of running al-folio locally without using Docker, che
|
|||||||
Assuming you have [Ruby](https://www.ruby-lang.org/en/downloads/) and [Bundler](https://bundler.io/) installed on your system (_hint: for ease of managing ruby gems, consider using [rbenv](https://github.com/rbenv/rbenv)_), and also [Python](https://www.python.org/) and [pip](https://pypi.org/project/pip/) (_hint: for ease of managing python packages, consider using a virtual environment, like [venv](https://docs.python.org/pt-br/3/library/venv.html) or [conda](https://docs.conda.io/en/latest/)_).
|
Assuming you have [Ruby](https://www.ruby-lang.org/en/downloads/) and [Bundler](https://bundler.io/) installed on your system (_hint: for ease of managing ruby gems, consider using [rbenv](https://github.com/rbenv/rbenv)_), and also [Python](https://www.python.org/) and [pip](https://pypi.org/project/pip/) (_hint: for ease of managing python packages, consider using a virtual environment, like [venv](https://docs.python.org/pt-br/3/library/venv.html) or [conda](https://docs.conda.io/en/latest/)_).
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ bundle install
|
bundle install
|
||||||
# assuming pip is your Python package manager
|
# assuming pip is your Python package manager
|
||||||
$ pip install jupyter
|
pip install jupyter
|
||||||
$ bundle exec jekyll serve
|
bundle exec jekyll serve
|
||||||
```
|
```
|
||||||
|
|
||||||
To see the template running, open your browser and go to `http://localhost:4000`. You should see a copy of the theme's [demo website](https://alshedivat.github.io/al-folio/). Now, feel free to customize the theme however you like. After you are done, remember to **commit** your final changes.
|
To see the template running, open your browser and go to `http://localhost:4000`. You should see a copy of the theme's [demo website](https://alshedivat.github.io/al-folio/). Now, feel free to customize the theme however you like. After you are done, remember to **commit** your final changes.
|
||||||
@ -197,7 +197,7 @@ If you need to manually re-deploy your website to GitHub pages, go to Actions, c
|
|||||||
If you decide to not use GitHub Pages and host your page elsewhere, simply run:
|
If you decide to not use GitHub Pages and host your page elsewhere, simply run:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ bundle exec jekyll build
|
bundle exec jekyll build
|
||||||
```
|
```
|
||||||
|
|
||||||
which will (re-)generate the static webpage in the `_site/` folder.
|
which will (re-)generate the static webpage in the `_site/` folder.
|
||||||
@ -206,7 +206,7 @@ Then simply copy the contents of the `_site/` directory to your hosting server.
|
|||||||
If you also want to remove unused css classes from your file, run:
|
If you also want to remove unused css classes from your file, run:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ purgecss -c purgecss.config.js
|
purgecss -c purgecss.config.js
|
||||||
```
|
```
|
||||||
|
|
||||||
which will replace the css files in the `_site/assets/css/` folder with the purged css files.
|
which will replace the css files in the `_site/assets/css/` folder with the purged css files.
|
||||||
@ -225,7 +225,7 @@ Firstly, from the deployment repo dir, checkout the git branch hosting your publ
|
|||||||
Then from the website sources dir (commonly your al-folio fork's clone):
|
Then from the website sources dir (commonly your al-folio fork's clone):
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ bundle exec jekyll build --destination $HOME/repo/publishing-source
|
bundle exec jekyll build --destination $HOME/repo/publishing-source
|
||||||
```
|
```
|
||||||
|
|
||||||
This will instruct jekyll to deploy the website under `$HOME/repo/publishing-source`.
|
This will instruct jekyll to deploy the website under `$HOME/repo/publishing-source`.
|
||||||
@ -247,15 +247,25 @@ In its default configuration, al-folio will copy the top-level `README.md` to th
|
|||||||
|
|
||||||
## Maintaining Dependencies
|
## Maintaining Dependencies
|
||||||
|
|
||||||
**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).
|
**al-folio** uses **Bundler** (a Ruby dependency manager) to keep track of Ruby packages (called "gems") needed to run Jekyll and its plugins.
|
||||||
|
|
||||||
**Quick reference:**
|
**To update all dependencies:**
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$ bundle update --all
|
bundle update --all
|
||||||
```
|
```
|
||||||
|
|
||||||
After updating, test locally to ensure everything still works. If your site fails after updating, check the [FAQ](FAQ.md) for troubleshooting.
|
**After updating:**
|
||||||
|
|
||||||
|
1. Rebuild the Docker image to apply changes: `docker compose up --build`
|
||||||
|
2. Test locally to ensure everything still works: `docker compose up`
|
||||||
|
3. Visit `http://localhost:8080` and verify the site renders correctly
|
||||||
|
4. If your site fails after updating, check the [FAQ](FAQ.md) for troubleshooting
|
||||||
|
|
||||||
|
**For Ruby/Python environment issues:**
|
||||||
|
|
||||||
|
- Always use Docker for consistency with CI/CD (see [Local setup using Docker](#local-setup-using-docker-recommended))
|
||||||
|
- Avoid manual Ruby/Python installation when possible
|
||||||
|
|
||||||
## Upgrading from a previous version
|
## Upgrading from a previous version
|
||||||
|
|
||||||
@ -263,9 +273,9 @@ If you installed **al-folio** as described above, you can manually update your c
|
|||||||
|
|
||||||
```bash
|
```bash
|
||||||
# Assuming the current directory is <your-repo-name>
|
# Assuming the current directory is <your-repo-name>
|
||||||
$ git remote add upstream https://github.com/alshedivat/al-folio.git
|
git remote add upstream https://github.com/alshedivat/al-folio.git
|
||||||
$ git fetch upstream
|
git fetch upstream
|
||||||
$ git rebase v0.16.3
|
git rebase v0.16.3
|
||||||
```
|
```
|
||||||
|
|
||||||
If you have extensively customized a previous version, it might be trickier to upgrade.
|
If you have extensively customized a previous version, it might be trickier to upgrade.
|
||||||
|
|||||||
837
MAINTENANCE.md
837
MAINTENANCE.md
@ -1,837 +0,0 @@
|
|||||||
# 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!
|
|
||||||
@ -2,6 +2,8 @@
|
|||||||
|
|
||||||
**Get your al-folio site running in 5 minutes.** This guide is for users who just want a working website quickly without deep customization.
|
**Get your al-folio site running in 5 minutes.** This guide is for users who just want a working website quickly without deep customization.
|
||||||
|
|
||||||
|
> **Video Tutorial:** Watch a walkthrough of these steps [here](assets/video/tutorial_al_folio.mp4)
|
||||||
|
|
||||||
<!--ts-->
|
<!--ts-->
|
||||||
|
|
||||||
- [Quick Start Guide](#quick-start-guide)
|
- [Quick Start Guide](#quick-start-guide)
|
||||||
@ -10,7 +12,12 @@
|
|||||||
- [Step 3: Personalize (2 min)](#step-3-personalize-2-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)
|
- [Step 4: View Your Site (1 min)](#step-4-view-your-site-1-min)
|
||||||
- [What's Next?](#whats-next)
|
- [What's Next?](#whats-next)
|
||||||
<!--te-->
|
- [Add Your Content](#add-your-content)
|
||||||
|
- [Customize Appearance](#customize-appearance)
|
||||||
|
- [Learn More](#learn-more)
|
||||||
|
- [Get Help from AI](#get-help-from-ai)
|
||||||
|
|
||||||
|
<!--te-->
|
||||||
|
|
||||||
## Step 1: Create Your Repository (1 min)
|
## Step 1: Create Your Repository (1 min)
|
||||||
|
|
||||||
@ -20,8 +27,6 @@
|
|||||||
- **Project site:** Any name (e.g., `my-research-website`)
|
- **Project site:** Any name (e.g., `my-research-website`)
|
||||||
3. Click **Create repository from template**
|
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)
|
## Step 2: Configure Deployment (1 min)
|
||||||
|
|
||||||
1. Go to your new repository → **Settings** → **Actions** → **General** → **Workflow permissions**
|
1. Go to your new repository → **Settings** → **Actions** → **General** → **Workflow permissions**
|
||||||
@ -38,15 +43,19 @@
|
|||||||
last_name: Name
|
last_name: Name
|
||||||
email: your.email@example.com
|
email: your.email@example.com
|
||||||
url: https://your-username.github.io # or your custom domain
|
url: https://your-username.github.io # or your custom domain
|
||||||
|
baseurl: # Leave this empty (do NOT delete it)
|
||||||
```
|
```
|
||||||
3. Click **Commit changes** (at the bottom of the page)
|
3. Click **Commit changes** (at the bottom of the page)
|
||||||
|
|
||||||
## Step 4: View Your Site (1 min)
|
## Step 4: View Your Site (1 min)
|
||||||
|
|
||||||
1. Go to your repository → **Actions** tab
|
1. Go to your repository → **Actions** tab
|
||||||
2. Wait for the "Deploy site" workflow to complete (~4 minutes, look for a green checkmark)
|
2. Wait for the "Deploy site" workflow to complete (look for a green checkmark, ~4 minutes)
|
||||||
3. Go to **Settings** → **Pages** → set Source to `gh-pages` branch
|
3. Go to **Settings** → **Pages** → **Build and deployment**
|
||||||
4. Visit `https://your-username.github.io` in your browser
|
4. Make sure **Source** is set to **Deploy from a branch**
|
||||||
|
5. Set the branch to **gh-pages** (NOT main)
|
||||||
|
6. Wait for the "pages-build-deployment" workflow to complete (~45 seconds)
|
||||||
|
7. Visit `https://your-username.github.io` in your browser
|
||||||
|
|
||||||
**That's it!** Your site is live. You now have a working al-folio website.
|
**That's it!** Your site is live. You now have a working al-folio website.
|
||||||
|
|
||||||
@ -71,10 +80,10 @@ Once your site is running, explore these customization options:
|
|||||||
|
|
||||||
### Learn More
|
### Learn More
|
||||||
|
|
||||||
|
- Installation and local setup options: [INSTALL.md](INSTALL.md)
|
||||||
- Full customization guide: [CUSTOMIZE.md](CUSTOMIZE.md)
|
- 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)
|
- Frequently asked questions: [FAQ.md](FAQ.md)
|
||||||
|
- Troubleshooting: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
||||||
|
|
||||||
### Get Help from AI
|
### Get Help from AI
|
||||||
|
|
||||||
|
|||||||
@ -266,7 +266,7 @@ Run the test yourself: [Google Lighthouse PageSpeed Insights](https://pagespeed.
|
|||||||
- [Collections](#collections)
|
- [Collections](#collections)
|
||||||
- [Layouts](#layouts)
|
- [Layouts](#layouts)
|
||||||
- [The iconic style of Distill](#the-iconic-style-of-distill)
|
- [The iconic style of Distill](#the-iconic-style-of-distill)
|
||||||
- [Full support for math & code](#full-support-for-math--code)
|
- [Full support for math \& code](#full-support-for-math--code)
|
||||||
- [Photos, Audio, Video and more](#photos-audio-video-and-more)
|
- [Photos, Audio, Video and more](#photos-audio-video-and-more)
|
||||||
- [Other features](#other-features)
|
- [Other features](#other-features)
|
||||||
- [GitHub's repositories and user stats](#githubs-repositories-and-user-stats)
|
- [GitHub's repositories and user stats](#githubs-repositories-and-user-stats)
|
||||||
@ -334,9 +334,7 @@ Comprehensive guides for all aspects of your al-folio website:
|
|||||||
- **[Troubleshooting](TROUBLESHOOTING.md)** – Fix common issues (deployment, build, styling, content)
|
- **[Troubleshooting](TROUBLESHOOTING.md)** – Fix common issues (deployment, build, styling, content)
|
||||||
- **[FAQ](FAQ.md)** – Frequently asked questions and solutions
|
- **[FAQ](FAQ.md)** – Frequently asked questions and solutions
|
||||||
- **[Analytics](ANALYTICS.md)** – Add website analytics and visitor tracking
|
- **[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
|
- **[SEO Guide](SEO.md)** – Optimize for search engines and improve discoverability
|
||||||
- **[Maintenance Guide](MAINTENANCE.md)** – Keep your site updated and secure
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
|
|||||||
6
SEO.md
6
SEO.md
@ -12,7 +12,6 @@ This guide helps you optimize your al-folio website for search engines so your r
|
|||||||
- [Enabling Open Graph (Social Media Previews)](#enabling-open-graph-social-media-previews)
|
- [Enabling Open Graph (Social Media Previews)](#enabling-open-graph-social-media-previews)
|
||||||
- [What is Open Graph?](#what-is-open-graph)
|
- [What is Open Graph?](#what-is-open-graph)
|
||||||
- [Enable in al-folio](#enable-in-al-folio)
|
- [Enable in al-folio](#enable-in-al-folio)
|
||||||
- [Test Your Setup](#test-your-setup)
|
|
||||||
- [Schema.org Markup](#schemaorg-markup)
|
- [Schema.org Markup](#schemaorg-markup)
|
||||||
- [What is Schema.org?](#what-is-schemaorg)
|
- [What is Schema.org?](#what-is-schemaorg)
|
||||||
- [Enable in al-folio](#enable-in-al-folio-1)
|
- [Enable in al-folio](#enable-in-al-folio-1)
|
||||||
@ -30,10 +29,11 @@ This guide helps you optimize your al-folio website for search engines so your r
|
|||||||
- [Image Optimization](#image-optimization)
|
- [Image Optimization](#image-optimization)
|
||||||
- [Internal Linking](#internal-linking)
|
- [Internal Linking](#internal-linking)
|
||||||
- [RSS Feed for Discovery](#rss-feed-for-discovery)
|
- [RSS Feed for Discovery](#rss-feed-for-discovery)
|
||||||
- [Performance & Mobile](#performance--mobile)
|
- [Performance \& Mobile](#performance--mobile)
|
||||||
- [SEO Checklist](#seo-checklist)
|
- [SEO Checklist](#seo-checklist)
|
||||||
- [Resources](#resources)
|
- [Resources](#resources)
|
||||||
<!--te-->
|
|
||||||
|
<!--te-->
|
||||||
|
|
||||||
## Overview
|
## Overview
|
||||||
|
|
||||||
|
|||||||
@ -13,7 +13,7 @@ This guide covers common issues and their solutions. For more information, see [
|
|||||||
- [Docker build fails](#docker-build-fails)
|
- [Docker build fails](#docker-build-fails)
|
||||||
- [Ruby dependency issues](#ruby-dependency-issues)
|
- [Ruby dependency issues](#ruby-dependency-issues)
|
||||||
- [Port already in use](#port-already-in-use)
|
- [Port already in use](#port-already-in-use)
|
||||||
- [Styling & Layout Problems](#styling--layout-problems)
|
- [Styling \& Layout Problems](#styling--layout-problems)
|
||||||
- [CSS and JS not loading properly](#css-and-js-not-loading-properly)
|
- [CSS and JS not loading properly](#css-and-js-not-loading-properly)
|
||||||
- [Site looks broken after deployment](#site-looks-broken-after-deployment)
|
- [Site looks broken after deployment](#site-looks-broken-after-deployment)
|
||||||
- [Theme colors not applying](#theme-colors-not-applying)
|
- [Theme colors not applying](#theme-colors-not-applying)
|
||||||
@ -30,7 +30,8 @@ This guide covers common issues and their solutions. For more information, see [
|
|||||||
- [Related posts broken](#related-posts-broken)
|
- [Related posts broken](#related-posts-broken)
|
||||||
- [Code formatting issues](#code-formatting-issues)
|
- [Code formatting issues](#code-formatting-issues)
|
||||||
- [Getting Help](#getting-help)
|
- [Getting Help](#getting-help)
|
||||||
<!--te-->
|
|
||||||
|
<!--te-->
|
||||||
|
|
||||||
## Deployment Issues
|
## Deployment Issues
|
||||||
|
|
||||||
|
|||||||
@ -27,7 +27,7 @@ latest_posts:
|
|||||||
limit: 3 # leave blank to include all the blog posts
|
limit: 3 # leave blank to include all the blog posts
|
||||||
---
|
---
|
||||||
|
|
||||||
Write your biography here. Tell the world about yourself. Link to your favorite [subreddit](http://reddit.com). You can put a picture in, too. The code is already in, just name your picture `prof_pic.jpg` and put it in the `img/` folder.
|
Write your biography here. Tell the world about yourself. Link to your favorite [subreddit](https://www.reddit.com). You can put a picture in, too. The code is already in, just name your picture `prof_pic.jpg` and put it in the `img/` folder.
|
||||||
|
|
||||||
Put your address / P.O. box / other info right below your picture. You can also disable any of these elements by editing `profile` property of the YAML header of your `_pages/about.md`. Edit `_bibliography/papers.bib` and Jekyll will render your [publications page](/al-folio/publications/) automatically.
|
Put your address / P.O. box / other info right below your picture. You can also disable any of these elements by editing `profile` property of the YAML header of your `_pages/about.md`. Edit `_bibliography/papers.bib` and Jekyll will render your [publications page](/al-folio/publications/) automatically.
|
||||||
|
|
||||||
|
|||||||
@ -1,4 +1,4 @@
|
|||||||
Write your biography here. Tell the world about yourself. Link to your favorite [subreddit](http://reddit.com). You can put a picture in, too. The code is already in, just name your picture `prof_pic.jpg` and put it in the `img/` folder.
|
Write your biography here. Tell the world about yourself. Link to your favorite [subreddit](https://www.reddit.com). You can put a picture in, too. The code is already in, just name your picture `prof_pic.jpg` and put it in the `img/` folder.
|
||||||
|
|
||||||
Put your address / P.O. box / other info right below your picture. You can also disable any these elements by editing `profile` property of the YAML header of your `_pages/about.md`. Edit `_bibliography/papers.bib` and Jekyll will render your [publications page](/al-folio/publications/) automatically.
|
Put your address / P.O. box / other info right below your picture. You can also disable any these elements by editing `profile` property of the YAML header of your `_pages/about.md`. Edit `_bibliography/papers.bib` and Jekyll will render your [publications page](/al-folio/publications/) automatically.
|
||||||
|
|
||||||
|
|||||||
Loading…
Reference in New Issue
Block a user