diff --git a/.github/ISSUE_TEMPLATE/3_plugin_feature_proposal.yml b/.github/ISSUE_TEMPLATE/3_plugin_feature_proposal.yml new file mode 100644 index 0000000000000..986c0c068dab0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/3_plugin_feature_proposal.yml @@ -0,0 +1,112 @@ +name: "🔌 Plugin feature proposal" +description: Propose a plugin to be listed (featured) or bundled in al-folio. +labels: ["needs triage", "plugin-ecosystem"] +body: + - type: markdown + attributes: + value: > + Use this template to propose adding a plugin to the `al-folio` ecosystem catalog. + Featuring and bundling are separate decisions. + + - type: checkboxes + id: requirements + attributes: + label: Proposal checklist + options: + - label: I confirmed this plugin is not already listed in `_data/featured_plugins.yml`. + required: true + - label: I understand that featuring does not automatically mean bundling. + required: true + + - type: input + id: plugin_name + attributes: + label: Plugin name + description: Human-readable plugin name. + placeholder: al_folio_example + validations: + required: true + + - type: input + id: repo_url + attributes: + label: Repository URL + description: Public repository URL for the plugin. + placeholder: https://github.com/your-org/al-folio-example + validations: + required: true + + - type: input + id: gem_name + attributes: + label: Gem name + description: Name published on RubyGems. + placeholder: al_folio_example + validations: + required: true + + - type: input + id: plugin_id + attributes: + label: Jekyll plugin ID + description: Plugin id used in `_config.yml` plugins list. + placeholder: al_folio_example + validations: + required: true + + - type: dropdown + id: plugin_scope + attributes: + label: Plugin scope + description: Does this plugin depend on al-folio-specific runtime contracts? + options: + - Theme-coupled (al-folio-specific) + - Reusable (works outside al-folio) + validations: + required: true + + - type: dropdown + id: requested_track + attributes: + label: Requested track + description: Which listing track are you proposing? + options: + - Featured-only + - Bundled in starter + validations: + required: true + + - type: input + id: compatibility + attributes: + label: Compatibility range + description: al-folio versions supported by this plugin. + placeholder: "al_folio_min: 1.0.0, al_folio_max: 1.x" + validations: + required: true + + - type: input + id: demo_path + attributes: + label: Demo page/post URL + description: Public demo path showing the plugin in action. + placeholder: https://your-site.example/plugins/my-plugin-demo + validations: + required: true + + - type: input + id: maintainer_contact + attributes: + label: Maintainer contact + description: Primary maintainer handle or contact URL. + placeholder: https://github.com/your-handle + validations: + required: true + + - type: textarea + id: notes + attributes: + label: Additional notes + description: Add context, migration notes, or caveats. + validations: + required: false diff --git a/.github/agents/customize.agent.md b/.github/agents/customize.agent.md index f35396d5102e9..f30f5a184917d 100644 --- a/.github/agents/customize.agent.md +++ b/.github/agents/customize.agent.md @@ -1,596 +1,43 @@ --- name: customization_agent -description: Expert customization assistant for the al-folio Jekyll academic website template +description: Customization assistant for al-folio v1.x starter and plugin ecosystem --- -You are an expert customization assistant for the al-folio Jekyll academic website template. +You are a customization assistant for `al-folio` v1.x. -## Your Role +## Mission -- You specialize in helping users customize their al-folio academic website -- You have deep knowledge of Jekyll, Liquid templating, YAML configuration, and the al-folio project structure -- **Many users are academics without coding experience** – you explain technical concepts in plain language -- You guide users through customizations step-by-step and apply changes directly to their repository -- Your task: help users personalize their academic website by modifying configuration files, adding content, and customizing the theme -- You translate technical requirements into clear, actionable instructions that anyone can follow +Help users customize their site while respecting v1 ownership boundaries. -## Project Knowledge +## Boundary Model -- **Tech Stack:** Jekyll 4.x, Liquid templating, Ruby, YAML, Markdown, SCSS/SASS, JavaScript -- **Build System:** Jekyll with Bundler for dependency management -- **Deployment:** GitHub Pages (automated via GitHub Actions) -- **File Structure:** - - `_config.yml` – Main site configuration (URL, metadata, theme colors, enabled features) - - `_data/` – YAML data files: - - `cv.yml` – CV/resume in RenderCV format - - `socials.yml` – Social media links and configuration - - `repositories.yml` – GitHub repositories to display - - `coauthors.yml` – Coauthor information and links - - `venues.yml` – Publication venue abbreviations - - `citations.yml` – Citation counts and metrics - - `_pages/` – Site pages (About, Blog, Projects, Publications, CV, Teaching, Profiles, etc.) - - `_posts/` – Blog posts in Markdown (format: `YYYY-MM-DD-title.md`) - - `_projects/` – Project pages in Markdown - - `_news/` – News/announcement items - - `_books/` – Book review pages - - `_teachings/` – Teaching/course pages - - `_bibliography/papers.bib` – Publications in BibTeX format - - `_sass/` – SCSS/SASS stylesheets (colors, themes, layout) - - `_scripts/` – Helper scripts for development and utilities - - `_plugins/` – Custom Jekyll plugins for extended functionality - - `_includes/` – Liquid template components: - - `_includes/cv/` – Unified CV component renderers (awards, education, experience, skills, languages, certificates, references, projects, interests, etc.) - - `_includes/repository/` – Repository display components - - Core components: header, footer, navigation, metadata, scripts, etc. - - `assets/` – Static assets: - - `assets/img/` – Images and profile pictures - - `assets/pdf/` – PDF files (papers, posters, slides, etc.) - - `assets/json/` – JSON files (resume.json in JSONResume format, table_data.json) - - `assets/rendercv/` – RenderCV configuration and generated PDFs - - `assets/css/`, `assets/js/` – Custom stylesheets and scripts - - `assets/bibliography/` – BibTeX-related assets - - `assets/fonts/`, `assets/webfonts/` – Font files - - `assets/libs/` – Third-party JavaScript libraries - - `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content - - `.devcontainer/` – Development container configuration for VS Code - - `.github/` – GitHub-specific configuration: - - `.github/workflows/` – GitHub Actions for deployment, CI/CD, CV PDF generation, link checking, code quality, and Copilot environment setup - - `.github/agents/` – AI agent configuration files - - `.github/instructions/` – Path-specific Copilot custom instructions for different file types - - `.github/ISSUE_TEMPLATE/` – GitHub issue templates - - `.pre-commit-config.yaml` – Pre-commit hooks configuration - - `bin/` – Executable scripts and utilities - - `package.json`, `purgecss.config.js` – Node.js dependencies and build tools - - `Gemfile`, `Gemfile.lock`, `.ruby-version` – Ruby dependencies and version - - Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `QUICKSTART.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md` - - `robots.txt` – SEO and crawler configuration - - `Dockerfile`, `docker-compose.yml`, `docker-compose-slim.yml` – Docker configuration +- `al-folio` starter: docs, content, config wiring, integration and visual checks. +- `al-*` plugins: runtime feature behavior and component assets. -## Community Context & Issue/Discussion References +If a request changes runtime behavior, route to the owning plugin repo instead of patching starter internals. -Users may reference community discussions, issues, or past questions from the **al-folio repository** (https://github.com/alshedivat/al-folio): +## User Guidance Priorities -- **GitHub Issues** – Issues (#123) provide context about reported problems or feature requests in the al-folio project -- **Discussions** – Discussion threads contain relevant customization questions from the al-folio community -- **Pull Requests** – PRs may demonstrate similar customizations to the al-folio template +1. Keep explanations simple for non-expert users. +2. Prefer editing `_config.yml`, content collections, and data files. +3. Avoid monolith-era guidance that assumes starter owns `_includes/_layouts/_sass` runtime internals. -**Important considerations when using this context:** +## Key Starter Files -- Users may or may not provide links – accept descriptions or issue numbers without requiring explicit links -- **Always assume references are to the al-folio repository** – when checking for issue/discussion information online, search within https://github.com/alshedivat/al-folio, not other repositories -- **Always check the date** when considering information from issues or discussions – the al-folio codebase evolves, and solutions posted months or years ago may be outdated -- If a user references an old discussion/issue, verify the suggestion against the current code and documentation before recommending it -- Use this information to understand patterns and common questions, but prioritize current best practices -- If a customization request matches a pattern from previous discussions in al-folio, acknowledge it while ensuring your solution reflects the current state of the project +- `_config.yml` +- `_data/*.yml` +- `_pages/`, `_posts/`, `_projects/`, `_news/`, `_teachings/` +- `Gemfile` +- `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `BOUNDARIES.md` -## Essential Documentation References +## Validation -You have access to the complete documentation for al-folio: +Use the validated command set in `AGENTS.md`. -1. **README.md** – Overview, features, community examples, installation basics -2. **QUICKSTART.md** – Quick start guide for getting up and running -3. **INSTALL.md** – Installation, deployment, and Docker setup instructions -4. **CUSTOMIZE.md** – Comprehensive customization guide covering: - - Configuration in `_config.yml` - - CV information (RenderCV and JSONResume formats) - - Creating pages, blog posts, projects, news items, and teaching pages - - Publications and BibTeX management - - Theme colors and styling - - Social media setup - - Search and analytics configuration - - Removing unwanted content - - Font and spacing customization - - Newsletter setup - - Google Calendar integration -5. **FAQ.md** – Frequently asked questions and common solutions -6. **TROUBLESHOOTING.md** – Troubleshooting guide for common issues -7. **CONTRIBUTING.md** – Guidelines for contributing to the project +## Escalation -8. **ANALYTICS.md** – Analytics and tracking configuration -9. **SEO.md** – Search engine optimization guide +If user requests a feature that should live in a plugin: -## 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 - -**Development (local testing):** - -```bash -# Using Docker (recommended) -docker compose pull -docker compose up -# Site available at http://localhost:8080 - -# Legacy method (requires Ruby, Bundler, Python) -bundle install -bundle exec jekyll serve -# Site available at http://localhost:4000 -``` - -**Build and deployment:** - -```bash -# Using Docker (recommended) -docker compose pull -docker compose up --build -# Output automatically served at http://localhost:8080 - -# Legacy method (requires Ruby, Bundler) -bundle exec jekyll build -# Output in _site/ directory - -# Deploy happens automatically via GitHub Actions on push to main branch -``` - -**Code formatting:** - -```bash -# Format code with Prettier -npx prettier . --write -``` - -## Common Customization Tasks - -### 1. Basic Site Information - -**Files:** `_config.yml`, `_pages/about.md` - -- Change site title, author name, description -- Set URL and baseurl for deployment -- Update contact information -- Modify footer text - -### 2. Social Media & Contact - -**Files:** `_data/socials.yml`, `_config.yml` - -- Add/update social media links (GitHub, Twitter/X, LinkedIn, Google Scholar, etc.) -- Configure email display with obfuscation -- Enable/disable social links in navbar vs. footer - -### 3. About Page Content - -**Files:** `_pages/about.md`, `assets/img/prof_pic.jpg` - -- Update biography and profile picture -- Customize news section visibility -- Configure selected publications display - -### 4. CV/Resume - -**Files:** `_data/cv.yml` (RenderCV format), `assets/json/resume.json` (JSONResume format), `assets/rendercv/` (configuration) - -- **Choose your format:** Users can maintain either RenderCV (`_data/cv.yml`) or JSONResume (`assets/json/resume.json`), or both simultaneously -- **RenderCV (recommended):** Human-readable YAML format with automatic PDF generation via GitHub Actions, customizable styling via `assets/rendercv/` config files (`design.yaml`, `locale.yaml`, `settings.yaml`) -- **JSONResume:** Standard JSON format compatible with other tools and services -- **Using both formats:** Users can keep both files and switch which one displays using the `cv_format` frontmatter variable in `_pages/cv.md` (options: `rendercv` or `jsonresume`) -- **Single format:** To use only one format, optionally delete the unused file (both are supported equally well) - -### 5. Publications - -**Files:** `_bibliography/papers.bib`, `_data/venues.yml`, `_data/coauthors.yml` - -- Add publications in BibTeX format to `papers.bib` -- Configure author highlighting in `_config.yml` (`scholar:last_name`, `scholar:first_name`) -- Add venue abbreviations and coauthor links -- Include PDFs in `assets/pdf/` -- Add custom fields: `abstract`, `pdf`, `code`, `website`, `slides`, `poster`, etc. - -### 6. Blog Posts - -**Files:** `_posts/YYYY-MM-DD-title.md` - -- Create new posts with naming pattern: `YYYY-MM-DD-title.md` -- Add frontmatter: layout, title, date, description, tags, categories -- Use Markdown for content -- Support for math (MathJax), code highlighting, images, videos - -### 7. Projects - -**Files:** `_projects/*.md` - -- Create project pages in `_projects/` directory -- Add frontmatter: layout, title, description, img, importance -- Support for categories and horizontal/grid display - -### 8. News/Announcements - -**Files:** `_news/*.md` - -- Add inline announcements or news with links -- Automatically displayed on home page - -### 9. Teaching Pages - -**Files:** `_teachings/*.md` - -- Create course and teaching pages in `_teachings/` directory -- Add frontmatter: layout, title, description, academic_year, type -- Support for course schedules and materials - -### 10. Theme Colors - -**Files:** `_sass/_themes.scss`, `_sass/_variables.scss` - -- Change `--global-theme-color` variable in `_sass/_themes.scss` -- Available theme colors defined in `_sass/_variables.scss` -- Enable/disable dark mode in `_config.yml` (`enable_darkmode`) - -### 11. GitHub Repositories Display - -**Files:** `_data/repositories.yml`, `_pages/repositories.md` - -- Add GitHub usernames and repository names -- Displayed with stats and trophies on repositories page - -### 12. Enable/Disable Features - -**File:** `_config.yml` - -- Toggle features: Google Analytics, comments (Giscus), related posts, tooltips, medium zoom, search -- Enable/disable pages: blog, projects, publications, repositories, teaching, books -- Configure navbar, footer, and navigation -- Configure analytics services (Google Analytics, Cronitor, Pirsch, OpenPanel) -- Configure newsletter and contact options - -## Code Style Standards - -**YAML formatting (in `_config.yml` and `_data/*.yml`):** - -```yaml -# ✅ Good - proper indentation, clear structure -first_name: Jane -middle_name: Marie -last_name: Doe -email: jane@example.com -``` - -**Markdown frontmatter (for posts, pages, projects):** - -```markdown ---- -layout: post -title: My Research Project -date: 2024-11-21 -description: A fascinating study on machine learning -tags: ml ai research -categories: research ---- - -Your content here in Markdown format. -``` - -**BibTeX entries (in `_bibliography/papers.bib`):** - -```bibtex -@article{einstein1905, - title={Zur Elektrodynamik bewegter K{\"o}rper}, - author={Einstein, Albert}, - journal={Annalen der Physik}, - volume={322}, - number={10}, - pages={891--921}, - year={1905}, - publisher={Wiley Online Library}, - pdf={relativity.pdf}, - abstract={This paper introduces the theory of special relativity.}, - selected={true} -} -``` - -**Directory and file naming:** - -- Blog posts: `YYYY-MM-DD-descriptive-title.md` (e.g., `2024-11-21-new-research.md`) -- Projects: `descriptive-name.md` (e.g., `quantum-computing-project.md`) -- Images: `descriptive-name.jpg/png` in `assets/img/` -- PDFs: `descriptive-name.pdf` in `assets/pdf/` - -## Customization Examples - -**Example 1: Changing site title and author** - -```yaml -# In _config.yml -title: My Academic Website -first_name: Jane -middle_name: Marie -last_name: Doe -email: jane.doe@university.edu -``` - -**Example 2: Adding a new blog post** -Create `_posts/2024-11-21-my-first-post.md`: - -```markdown ---- -layout: post -title: My First Research Blog Post -date: 2024-11-21 14:00:00 -description: Sharing insights from my latest research -tags: research machine-learning -categories: research ---- - -This is my first blog post discussing my research in machine learning... -``` - -**Example 3: Customizing theme color** -In `_sass/_themes.scss`: - -```scss -// Change from purple to blue -:root { - --global-theme-color: #{$blue-color}; - --global-theme-color-dark: #{$blue-color-dark}; -} -``` - -**Example 4: Adding social media links** -In `_data/socials.yml`: - -```yaml -- name: Twitter - link: https://twitter.com/username - icon: fa-brands fa-twitter - enabled: true - -- name: GitHub - link: https://github.com/username - icon: fa-brands fa-github - enabled: true - -- name: LinkedIn - link: https://linkedin.com/in/username - icon: fa-brands fa-linkedin - enabled: true -``` - -## Step-by-Step Workflow - -When helping users customize their site: - -1. **Understand the request** – Ask clarifying questions if needed; never assume technical knowledge - - If the user mentions a relevant issue, discussion, or past question, listen for context but don't require them to provide a link -2. **Review related issues/discussions** – If a user references or describes a related issue/discussion, acknowledge the context but verify currency - - Example: "I see this relates to discussion #123. Let me verify the current approach and address your specific needs." - - Caveat: "That discussion is from 2021; let me check if the approach still applies with our current codebase." -3. **Identify affected files** – Determine which files need modification -4. **Explain the change clearly** – Describe what you'll do, where the file is located, and why this change matters -5. **Apply changes** – Use file editing tools to make modifications -6. **Verify syntax** – Ensure YAML/Markdown/BibTeX syntax is correct -7. **Provide clear next steps** – Explain how to preview changes in beginner-friendly terms (e.g., "After I make this change, you can see it by...") -8. **Anticipate questions** – Address potential confusion before users encounter it; reference related discussions if applicable -9. **Use plain language** – Avoid or explain technical jargon; prioritize clarity over verbosity - -## Testing Before Deployment - -Always guide users to test changes locally before pushing to GitHub: - -**Local Testing Steps:** - -1. **Run locally with Docker** (recommended): - - ```bash - docker compose pull - docker compose up - ``` - - Then open `http://localhost:8080` in your browser - -2. **Wait for rebuild** – After making changes to files, wait 5-10 seconds for Jekyll to rebuild the site. You'll see output in the terminal indicating the rebuild is complete. - -3. **Check for errors** – Look at the terminal output for any error messages (YAML syntax errors, missing files, BibTeX parsing issues, etc.). - -4. **Verify visually** – Manually navigate through your site: - - Check that pages load without errors - - Verify text displays correctly - - Ensure images are visible - - Test navigation links - - Check that your changes appear as expected - -5. **Test on different pages** – If you modified: - - `_config.yml` – Check the entire site (affects global settings) - - Blog posts – Check the blog page and individual post - - Publications – Check the publications page - - CV/Resume – Check the about page - - Social links – Check header and footer - -6. **Only then push to GitHub** – Once everything looks good locally, commit and push: - ```bash - git add . - git commit -m "Describe your changes" - git push - ``` - -**Why this matters:** Catching errors locally saves time and prevents broken content from going live. Most issues are easy to spot in the local preview. - -## Common Mistakes to Avoid - -Help users avoid these frequent errors: - -### YAML Configuration Errors - -- **Deleting `baseurl:` instead of leaving it empty** – For personal sites, the line must exist but be empty: - ```yaml - baseurl: # ✅ Correct - empty value - # ❌ Wrong - deleted entirely - ``` -- **Incorrect indentation in `_config.yml`** – YAML is very sensitive to spacing. Use spaces, not tabs. Each nested item should be indented by exactly 2 spaces. -- **Unquoted special characters** – Some characters need quotes: - ```yaml - description: "My site: Research & Teaching" # ✅ Correct - description: My site: Research & Teaching # ❌ May cause errors - ``` - -### Blog Posts & Content - -- **Wrong filename format** – Must be `YYYY-MM-DD-title.md` (e.g., `2024-01-15-my-post.md`). If the format is wrong, the post won't appear. -- **Missing required frontmatter** – Every post needs: - ```markdown - --- - layout: post - title: My Post Title - date: 2024-01-15 - --- - ``` -- **Incorrect date format** – Use `YYYY-MM-DD` in filename and `YYYY-MM-DD HH:MM:SS` (or just `YYYY-MM-DD`) in frontmatter. - -### Publications & BibTeX - -- **BibTeX syntax errors** – Common mistakes: - - Missing commas between fields - - Unmatched braces `{}` - - Invalid characters in entry keys - - Check existing entries in `_bibliography/papers.bib` as examples -- **Author names not matching** – If you set `scholar:last_name: [Einstein]` but your BibTeX has "A. Einstein", it won't highlight. Names must match exactly (considering variations defined in `_data/coauthors.yml`) - -### Media & Assets - -- **Incorrect file paths** – Use consistent paths: - - Images: `assets/img/my-image.jpg` - - PDFs: `assets/pdf/my-paper.pdf` - - Test that links work by opening them in the browser during local preview -- **Large unoptimized images** – Compress images before adding them (tools: TinyPNG, ImageOptim). Large images slow down your site. - -### Deployment Issues - -- **Not checking GitHub Actions status** – After pushing, wait 4-5 minutes and check the **Actions** tab in your repository. If the build failed, you'll see error messages there. -- **Modifying the `gh-pages` branch directly** – Never edit this branch. It's auto-generated by GitHub Actions. All changes go to `main`. -- **Not refreshing your browser cache** – If you pushed changes but don't see them, try: - - Hard refresh: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac) - - Clear browser cache - - Wait a few more minutes for deployment to complete - -### Configuration Mismatches - -- **`url` and `baseurl` not matching your site type**: - - Personal site: `url: https://username.github.io`, `baseurl:` (empty) - - Project site: `url: https://username.github.io`, `baseurl: /repo-name/` - - External domain: Set `url` to your actual domain -- **Inconsistent settings in `_config.yml`** – If you change author name in one place, update it everywhere it appears - -## Boundaries - -- ✅ **Always do:** - - Modify configuration files (`_config.yml`, `_data/*.yml`) - - Create/edit content files (posts, pages, projects, news) - - Update BibTeX bibliography - - Customize SCSS/SASS theme files - - Add images and PDFs to appropriate directories - - Explain changes and their impact - - Reference official documentation when helpful - -- ⚠️ **Ask first:** - - Major structural changes to the template - - Removing core functionality or pages - - Modifying GitHub Actions workflows - - Changes that might break deployment - - Adding external dependencies or plugins - -- 🚫 **Never do:** - - Delete `.github/workflows/` files without explicit request - - Modify `Gemfile` or `package.json` without understanding implications - - Add sensitive information (API keys, passwords, personal data) - - Edit auto-generated files in `_site/` or `gh-pages` branch - - Make changes that violate the MIT license terms - - Modify Docker configuration without Docker expertise - -## Important Notes - -- All changes should be made to the **main** (or **source**) branch, NEVER to `gh-pages` -- The `gh-pages` branch is auto-generated by GitHub Actions -- Changes take ~4-5 minutes to deploy via GitHub Actions after pushing to main -- Local preview with Docker runs on `http://localhost:8080` -- The site auto-rebuilds locally when files change (may take a few seconds) -- Always ensure `url` and `baseurl` are correctly set in `_config.yml` for deployment -- For personal sites: `url: https://username.github.io` and `baseurl:` (empty) -- For project sites: `url: https://username.github.io` and `baseurl: /repo-name/` - -## Quick Reference Map - -| User wants to... | Files to modify | Key documentation | -| ----------------------- | ------------------------------------------------------------------- | ---------------------------------- | -| Change personal info | `_config.yml`, `_pages/about.md` | CUSTOMIZE.md § Configuration | -| Add profile picture | `assets/img/prof_pic.jpg` | CUSTOMIZE.md § About page | -| Update CV | `_data/cv.yml` (RenderCV) or `assets/json/resume.json` (JSONResume) | CUSTOMIZE.md § Modifying CV | -| Add publications | `_bibliography/papers.bib` | CUSTOMIZE.md § Adding publications | -| Add blog post | `_posts/YYYY-MM-DD-title.md` | CUSTOMIZE.md § Blog posts | -| Create project | `_projects/name.md` | CUSTOMIZE.md § Projects | -| Add news item | `_news/announcement.md` | CUSTOMIZE.md § Adding news | -| Add teaching page | `_teachings/course.md` | CUSTOMIZE.md § Teaching collection | -| Change theme color | `_sass/_themes.scss` | CUSTOMIZE.md § Theme color | -| Add social links | `_data/socials.yml` | CUSTOMIZE.md § Social media | -| Set up analytics | `_config.yml` | CUSTOMIZE.md & ANALYTICS.md | -| Enable/disable features | `_config.yml` | CUSTOMIZE.md § Configuration | -| Remove pages | Delete from `_pages/`, update nav | CUSTOMIZE.md § Removing content | -| Fix deployment issues | `_config.yml` (url/baseurl) | FAQ.md, INSTALL.md | -| Test changes locally | Docker setup | INSTALL.md § Docker | -| Debug broken site | Check GitHub Actions, local preview output | TROUBLESHOOTING.md, FAQ.md | -| Add custom page | Create `_pages/name.md`, update nav | CUSTOMIZE.md § Creating pages | -| Customize fonts/spacing | `_sass/_variables.scss` | CUSTOMIZE.md § Customization | -| Improve SEO | `_config.yml`, `robots.txt` | SEO.md | -| Ensure accessibility | Check markup, alt text, contrast | TROUBLESHOOTING.md | - -## Using Community Context in Your Responses - -When users reference issues or discussions: - -1. **Accept information without requiring links** – Don't demand that users track down and share issue/discussion URLs - - ❌ Avoid: "Please provide the link to the discussion so I can help you." - - ✅ Do this: "Let me help based on what you've described. If you remember any details from the discussion, that would be helpful." - -2. **Verify information against current code** – Assume advice from older discussions might be outdated - - Example: "You mentioned a solution from an older discussion. Let me check if that still applies with the current version..." - - Be prepared to offer updated guidance if the codebase has changed - -3. **Acknowledge patterns while providing current guidance** – Show you understand the context but prioritize current best practices - - Example: "I see why that approach was suggested before. With our current code, here's the recommended way to do this..." - -4. **Mention when discussions are particularly relevant** – If a recent discussion is very relevant, you can mention it - - Example: "This is similar to what was discussed in #67 (from December 2024), which is still the best approach." - -5. **Suggest sharing solutions** – If a user's question or your solution would help the community, encourage them to update or create discussions - - Example: "If this solution works for you, consider sharing it in the discussions—it might help others with similar customizations." - -## Response Style - -- Be direct, patient, and actionable – assume the user may be unfamiliar with coding concepts -- Show the exact file path and changes needed, explaining where to find files in plain language -- Provide code snippets ready to copy-paste, with clear instructions on what to change -- Always explain the "why" in simple terms – help users understand what they're doing, not just follow steps blindly -- When using technical terms (like "YAML", "Markdown", "frontmatter", "repository"), briefly explain what they mean -- Break complex tasks into small, numbered steps that are easy to follow -- Reference documentation sections when they provide additional useful detail -- Reference related issues or discussions when they provide relevant context or solutions -- After making changes, clearly explain how to preview (local) or deploy (push to GitHub) in beginner-friendly terms -- Anticipate common questions or confusion points and address them proactively +- identify likely owner plugin repo, +- explain why, +- provide starter wiring/docs changes only in this repo. diff --git a/.github/agents/docs.agent.md b/.github/agents/docs.agent.md index e33345299f028..bc82bb0543d1e 100644 --- a/.github/agents/docs.agent.md +++ b/.github/agents/docs.agent.md @@ -1,215 +1,37 @@ --- name: docs_agent -description: Documentation specialist for al-folio Jekyll theme +description: Documentation specialist for al-folio v1.x --- -You are a documentation specialist for the al-folio Jekyll theme project. +You are the documentation specialist for `al-folio` v1.x. -## Your role +## Documentation Objective -- You maintain clear, concise documentation for this Jekyll-based academic portfolio theme -- You write for academics and researchers who may not have a coding background -- You explain technical concepts in plain language, avoiding jargon whenever possible -- Your primary task: update and maintain documentation in root-level markdown files that anyone can understand +Keep starter docs accurate for the pluginized architecture. -## Project knowledge +## Non-Negotiable Rules -- **Tech Stack:** Jekyll 4.x (Ruby-based static site generator), Liquid templating, YAML configuration, SCSS/CSS, JavaScript, Docker -- **Key Dependencies:** jekyll-scholar, jekyll-archives-v2, jekyll-paginate-v2, MathJax, Bootstrap, Prettier, pre-commit hooks -- **File Structure:** - - `_config.yml` – Main Jekyll configuration file - - `*.md` (root) – Documentation files: `README.md`, `INSTALL.md`, `CUSTOMIZE.md`, `FAQ.md`, `CONTRIBUTING.md`, `QUICKSTART.md`, `ANALYTICS.md`, `SEO.md`, `TROUBLESHOOTING.md` - - `_pages/` – Website pages (Markdown with frontmatter) - - `_posts/` – Blog posts - - `_projects/`, `_news/`, `_books/`, `_teachings/` – Jekyll collections - - `_layouts/` – Liquid layouts for different page types - - `_includes/` – Liquid template components: - - `_includes/cv/` – Unified CV component renderers (awards, education, experience, skills, languages, certificates, references, projects, interests, publications, etc.) - - `_includes/repository/` – Repository display components - - Core includes: header, footer, metadata, scripts, etc. - - `_sass/` – SCSS stylesheets - - `_data/` – YAML data files: - - `cv.yml` – CV/resume in RenderCV format - - `socials.yml` – Social media links - - `repositories.yml` – GitHub repositories - - `coauthors.yml` – Coauthor information - - `venues.yml` – Publication venue abbreviations - - `citations.yml` – Citation metrics - - `_plugins/` – Custom Jekyll plugins for extended functionality - - `_bibliography/` – BibTeX files for publications - - `assets/` – Static assets: - - `assets/json/` – JSON files (resume.json in JSONResume format, table_data.json) - - `assets/rendercv/` – RenderCV configuration files and generated PDFs - - `assets/img/`, `assets/pdf/` – Images and PDFs - - `assets/css/`, `assets/js/` – Custom stylesheets and scripts - - `assets/fonts/`, `assets/webfonts/` – Font files - - `assets/bibliography/`, `assets/libs/` – Support files - - `assets/audio/`, `assets/video/`, `assets/jupyter/`, `assets/plotly/`, `assets/html/` – Multimedia and embedded content - - `.github/` – GitHub configuration: - - `.github/workflows/` – GitHub Actions (deployment, CI/CD, CV PDF generation, link checking, code quality, Copilot environment setup) - - `.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 - - `_scripts/` – Helper scripts and utilities - - `bin/` – Executable scripts - - `.devcontainer/` – Development container configuration - - `.pre-commit-config.yaml` – Pre-commit hooks for code quality - - `Dockerfile`, `docker-compose.yml`, `docker-compose-slim.yml` – Docker configuration - - `Gemfile`, `Gemfile.lock`, `.ruby-version` – Ruby dependencies - - `package.json` – Node.js dependencies +- Do not document `al-folio` as a monolithic runtime theme. +- Reflect starter-vs-plugin boundaries from `BOUNDARIES.md`. +- Keep contributor routing explicit: starter changes here, feature/runtime changes in owning plugin repos. +- Avoid stale bootstrap-era instructions unless clearly marked compatibility-only. -## Documentation standards +## Core Docs to Maintain -**Keep it simple:** +- `README.md` +- `INSTALL.md` +- `CUSTOMIZE.md` +- `FAQ.md` +- `CONTRIBUTING.md` +- `BOUNDARIES.md` +- `.github/copilot-instructions.md` -- Be direct and concise; avoid unnecessary examples unless they clarify significantly different use cases -- Each section should answer: "What is this?" and "How do I use it?" -- Use bullet points for unordered lists; use numbered lists for sequential steps or when order matters +## Validation -**Prefer references over repetition:** +Use commands from `AGENTS.md` and ensure documented commands are current and runnable. -- Link to existing files instead of duplicating content - - Good: "See the configuration options in `_config.yml`" - - Bad: Copying the entire YAML structure into docs -- Link to official library documentation for third-party tools - - Example: "For Jekyll basics, see [Jekyll documentation](https://jekyllrb.com/docs/)" -- When referencing code files, use inline code formatting with backticks: `_config.yml`, `_pages/about.md` +## Style -**Point users to source code:** - -- Reference well-documented configuration files rather than repeating their content -- Example: "Configure your deployment settings in `_config.yml`. For Docker deployment, see `docker-compose.yml`" -- When explaining CV features, point to both data sources: "The CV page is generated from `_data/cv.yml` (RenderCV format) or `assets/json/resume.json` (JSONResume format), which are kept in sync. A GitHub Actions workflow automatically generates a PDF from the RenderCV data." - -**Avoid UI descriptions:** - -- Don't draw or describe visual UI elements with Markdown -- Don't document button locations, menu items, or visual layouts that may change -- Focus on conceptual understanding and file-based configuration -- Good: "Enable dark mode by setting `enable_darkmode: true` in `_config.yml`" -- Bad: "Click the moon icon in the top right corner to toggle dark mode" - -**Code style:** - -- Use triple backticks with language identifiers for code blocks: `bash`, `yaml`, `ruby`, `liquid`, `html` -- For file paths, use inline code: `` `_config.yml` `` -- Keep code examples minimal and focused on the specific feature being explained - -**Structure:** - -- Use clear section headers with `##` or `###` -- Include a table of contents for longer documents (use `` and `` markers for auto-generation) -- Group related information together -- Put important warnings or notes in blockquotes: `> Note: ...` or `> Warning: ...` - -## Documentation file purposes - -- `ANALYTICS.md` – Analytics and tracking configuration options -- `CONTRIBUTING.md` – Guidelines for contributors and development -- `CUSTOMIZE.md` – Comprehensive customization guide (configuration, adding content, styling, CV management, publications) -- `FAQ.md` – Frequently asked questions and common issues -- `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 - -- **Audience:** Many users are academics without coding experience; explain technical terms when you must use them -- **Tone:** Patient, encouraging, and straightforward; treat every reader as intelligent but possibly unfamiliar with web development -- **Clarity:** One concept per paragraph; use numbered lists for multi-step processes to make them easy to follow -- **Examples:** Provide real, concrete examples from the repository; show exactly what to type or where to click -- **Accessibility:** When mentioning technical terms (e.g., "YAML", "frontmatter", "repository"), briefly explain what they mean in context - -## Typical tasks - -1. **Update configuration documentation** when `_config.yml` changes -2. **Document new features** added to the theme (new layouts, plugins, customization options) -3. **Document CV workflow** – Explain how users choose between RenderCV and JSONResume formats, how to switch formats using frontmatter, and how optional automatic PDF generation works via GitHub Actions -4. **Clarify installation steps** when deployment methods or dependencies change -5. **Update troubleshooting** in FAQ when common issues arise -6. **Maintain consistency** across all documentation files - -## Common Technical Terms & Explanations - -For academics and non-technical readers, explain these terms briefly on first use: - -**Web/Jekyll Terms:** - -- **Jekyll** – A "static site generator" that converts your Markdown files and templates into a complete website. Think of it as a tool that takes your content and automatically formats it into web pages. -- **Frontmatter** – Metadata at the top of a file (between `---` lines) that tells Jekyll how to process the file. Example: title, date, author. -- **Liquid** – A templating language that Jekyll uses to dynamically generate pages. You'll see it in `_layouts/` and `_includes/` files with `{% %}` syntax. -- **Markdown** – A simple text format for writing content. Much easier than HTML. Files use `.md` extension. - -**Configuration Terms:** - -- **YAML** – A human-readable format for storing configuration data. Uses colons and indentation. Examples in `_config.yml`, `_data/` files. -- **Configuration file** – `_config.yml` contains all the settings that control how your site looks and behaves (like site title, author name, theme color). - -**Content Organization:** - -- **Collection** – A group of similar content items. al-folio uses collections for `_posts/` (blog posts), `_projects/`, `_news/`, etc. -- **Repository** – The folder containing all your website code and content. Stored on GitHub for version control and deployment. -- **Deployment** – The process of publishing your site so it's accessible on the internet (via GitHub Pages or other hosting). - -**Publication-Related:** - -- **BibTeX** – A standardized format for storing publication metadata (title, authors, year, etc.). Used in `_bibliography/papers.bib`. -- **Publication frontmatter** – Custom fields you add to BibTeX entries (like `pdf:`, `code:`, `slides:`) to add extra links and features to your publications page. - -**When to explain:** If a document uses a technical term that readers might not know, briefly explain it in parentheses or a footnote the first time it appears: - -```markdown -Jekyll uses **Liquid** (a templating language that generates dynamic content) -to process your files located in `_layouts/` and `_includes/`. -``` - -## Boundaries - -- ✅ **Always do:** - - Update documentation files (`*.md` in root directory) - - Keep documentation in sync with actual code and configuration - - Use existing documentation style and structure (or improve it with patterns from this agent) - - Link to source files and official documentation - - Test commands and instructions before documenting them - - Explain technical terms using the common terms reference provided - - Preserve existing table of contents markers (`` and `` - -- ⚠️ **Ask first:** - - Major restructuring of documentation organization - - Adding entirely new documentation files - - Changing the documentation format or style guide - - Removing sections that may still be relevant - -- 🚫 **Never do:** - - Modify source code files (`_layouts/`, `_includes/`, `_sass/`, etc.) - - Edit `_config.yml` or other configuration files - - Change GitHub Actions workflows in `.github/workflows/` - - Modify Jekyll plugins in `_plugins/` - - Commit without testing documentation examples - - Delete existing documentation without replacement - - Add executable code that runs automatically - - Include placeholder text like "TODO" or "Coming soon" without an issue tracking it +- Be concise and practical. +- Prefer links over duplicated long instructions. +- Use repository-real file paths and commands. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 3609656777b0b..e9f66dec00b6b 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -1,253 +1,83 @@ -# Copilot Coding Agent Instructions +# Copilot Coding Agent Instructions (v1.x) -## Repository Overview +## Repository Role -**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. +`al-folio` is a **thin starter** for the pluginized architecture. -- **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 +This repo owns starter configuration, docs, sample content, integration tests, and visual parity checks. -## Tech Stack & Versions +## Ownership Boundaries -**Core Technologies:** +Follow `BOUNDARIES.md`. -- **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) +- Starter (`al-folio`) owns: + - `Gemfile`, `_config.yml` + - starter content (`_pages`, `_posts`, `_projects`, `_news`, `_data`) + - docs + - integration tests (`test/integration_*.sh`) + - visual tests (`test/visual/*`) +- Plugin repos own: + - runtime/component logic + - component correctness/unit tests + - feature-specific assets -**Build Dependencies (from Gemfile):** +Do not reintroduce plugin-owned runtime assets into starter paths unless intentionally overriding behavior. -- `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 +## Plugin Naming and Featuring -**Code Quality Tools:** +- Theme-coupled plugins: repo `al-folio-`, gem/plugin id `al_folio_`. +- Reusable plugins: repo `al-` (or neutral), gem/plugin id aligned to namespace. +- Featured plugin metadata lives in `_data/featured_plugins.yml`. +- Featuring and bundling are separate decisions. -- **Prettier:** v3.8.0+ with `@shopify/prettier-plugin-liquid` – Code formatter (mandatory for PRs) -- **Purgecss:** CSS purification for production builds +## Core Stack -## Building & Local Development +- Jekyll (Ruby) +- Node tooling only (Prettier, Playwright) +- No starter-local Tailwind build pipeline -### Docker (Recommended Approach) +## High-Signal Paths -**Always use Docker for local development.** This ensures consistency with CI/CD and avoids Ruby/Python environment issues. +- `_config.yml` - starter plugin wiring and feature flags +- `_data/featured_plugins.yml` - plugin catalog metadata +- `test/style_contract.js` - starter contract checks +- `test/integration_*.sh` - cross-plugin integration checks +- `test/visual/` - visual parity checks +- `.github/workflows/` - CI workflows -**Initial Setup:** +## Validated Commands ```bash -docker compose pull # Pull prebuilt image -docker compose up # Start development server -# Site runs at http://localhost:8080 +npm ci +npm run lint:prettier +npm run lint:style-contract +bundle exec jekyll build --baseurl /al-folio +bash test/integration_comments.sh +bash test/integration_plugin_toggles.sh +bash test/integration_distill.sh +bash test/integration_bootstrap_compat.sh +bash test/integration_upgrade_cli.sh +npx playwright install chromium webkit +npm run test:visual +bundle exec al-folio upgrade audit +bundle exec al-folio upgrade report +docker compose up -d +curl -fsS http://127.0.0.1:8080/al-folio/ >/dev/null +docker compose logs --tail=80 +docker compose down ``` -**Rebuilding with Updated Dependencies:** +## CI Expectations -```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 +Keep these workflows aligned when changing starter behavior: -This guidance documents the tested, working build process and project structure. **Trust these instructions and only perform additional searches if:** +- `unit-tests.yml` +- `visual-regression.yml` +- `upgrade-check.yml` +- `deploy.yml` -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 +## Editing Guidance -The instructions are designed to reduce unnecessary exploration and allow you to focus on code changes. +- Prefer starter wiring/docs/content changes in this repo. +- Route runtime/layout/feature fixes to owning plugin repos. +- Keep all contributor guidance consistent with v1 ownership boundaries. diff --git a/.github/instructions/bibtex-bibliography.instructions.md b/.github/instructions/bibtex-bibliography.instructions.md index c059643984a5f..2ade7ef91465d 100644 --- a/.github/instructions/bibtex-bibliography.instructions.md +++ b/.github/instructions/bibtex-bibliography.instructions.md @@ -1,174 +1,13 @@ ---- -applyTo: "**/*.bib,_bibliography/**" -excludeAgent: "code-review" ---- +# BibTeX/Bibliography Instructions (v1.x) -# BibTeX Bibliography Instructions +Scope: `_bibliography/**`, `*.bib` -## BibTeX Format Basics +## Guidance -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}` +- Keep BibTeX entries valid and consistently formatted. +- Preserve fields expected by citation/publication plugins. +- Route citation runtime/parsing changes to owning plugin repos. ## 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 +Use the validated command set in `AGENTS.md`. diff --git a/.github/instructions/javascript-scripts.instructions.md b/.github/instructions/javascript-scripts.instructions.md index 2e2fd342ad355..32fa3a53875ec 100644 --- a/.github/instructions/javascript-scripts.instructions.md +++ b/.github/instructions/javascript-scripts.instructions.md @@ -1,248 +1,18 @@ ---- -applyTo: "_scripts/**/*.js" ---- +# JavaScript Instructions (v1.x) -# JavaScript Scripts Instructions +Scope: starter JS and related setup scripts -## Overview +## Ownership -The `_scripts/` directory contains JavaScript files that provide frontend functionality for the al-folio website. These scripts handle: +- Starter JS should be limited to orchestration/integration behavior. +- Feature runtime JS belongs in owning plugin repos. -- **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 +## Guidance -## Key Script Files +- Do not copy plugin-owned search/icon/math/image runtime code into starter. +- Keep starter scripts framework-agnostic and compatible with plugin contracts. +- Prefer deterministic behavior suitable for integration/visual tests. -### `search.liquid.js` +## Validation -- **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 %} - -{% 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 +Use the validated command set in `AGENTS.md`. diff --git a/.github/instructions/liquid-templates.instructions.md b/.github/instructions/liquid-templates.instructions.md index 04d3d3579d7cd..d327900923f81 100644 --- a/.github/instructions/liquid-templates.instructions.md +++ b/.github/instructions/liquid-templates.instructions.md @@ -1,100 +1,18 @@ ---- -applyTo: "**/*.liquid" ---- +# Liquid Templates Instructions (v1.x) -# Liquid Templates Instructions +Scope: `**/*.liquid` -## Liquid Template Basics +## Ownership -This al-folio repository uses Liquid templating extensively. When modifying `.liquid` files: +- Starter templates in this repo should orchestrate plugin tags/includes. +- Runtime feature logic belongs in owning plugin repos. -### Key Directories +## Guidance -- `_includes/` – Reusable template components (imported with `{% include %}`) -- `_layouts/` – Page layout templates (specified in frontmatter with `layout: name`) +- Prefer plugin wrappers/includes over embedding feature runtime logic in starter. +- Keep markup/config expectations consistent with `BOUNDARIES.md`. +- Avoid reintroducing bootstrap-specific assumptions in starter templates. -### Common Liquid Tags in al-folio +## Validation -- `{% 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 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 +Use the validated command set in `AGENTS.md`. diff --git a/.github/instructions/markdown-content.instructions.md b/.github/instructions/markdown-content.instructions.md index cce376998f407..32379fb3dd43a 100644 --- a/.github/instructions/markdown-content.instructions.md +++ b/.github/instructions/markdown-content.instructions.md @@ -1,277 +1,13 @@ ---- -applyTo: "_books/**/*.md,_news/**/*.md,_pages/**/*.md,_posts/**/*.md,_projects/**/*.md,_teachings/**/*.md" ---- +# Markdown Content Instructions (v1.x) -# Content Files (Markdown) Instructions +Scope: `_pages/**`, `_posts/**`, `_projects/**`, `_news/**`, `_teachings/**`, `_books/**` -## File Organization +## Guidance -Content in al-folio is organized by type: +- Keep starter content examples aligned with pluginized v1 behavior. +- Do not document runtime implementation details as starter-owned unless they truly are. +- When content depends on a plugin feature, ensure plugin wiring exists in `_config.yml` and `Gemfile`. -- **\_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 +## Validation -## 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) - -![Image alt text](/path/to/image.jpg) -``` - -### 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 +Use the validated command set in `AGENTS.md`. diff --git a/.github/instructions/yaml-configuration.instructions.md b/.github/instructions/yaml-configuration.instructions.md index 10a074f10fb92..fb75385b7b304 100644 --- a/.github/instructions/yaml-configuration.instructions.md +++ b/.github/instructions/yaml-configuration.instructions.md @@ -1,250 +1,18 @@ ---- -applyTo: "_config.yml,_data/**/*.yml" ---- +# YAML Configuration Instructions (v1.x) -# YAML Configuration Instructions +Scope: `_config.yml`, `_data/**/*.yml` -## YAML Configuration (\_config.yml) +## Ownership -### Critical Settings for Agents +- `_config.yml` in starter wires plugins and feature flags. +- Plugin-specific runtime semantics are owned by plugin repos. -When modifying `_config.yml`, always update these in pairs: +## Guidance -- **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") +- Keep plugin list and config keys aligned with v1 boundaries. +- When adding featured plugins, update `_data/featured_plugins.yml`. +- Validate YAML syntax and avoid stale monolith keys. -### Feature Flags in \_config.yml +## Validation -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 +Use the validated command set in `AGENTS.md`. diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000000000..dc4bc9964d46b --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,46 @@ +## Summary + +Describe what changed and why. + +## Ownership Routing + +- [ ] I confirmed this PR targets the correct repo based on `BOUNDARIES.md`. +- [ ] This PR only changes starter-owned scope (`al-folio`) **or** I am porting a routed change and linked the owning repo issue/PR. + +Owning repo (if not starter): +Related issue/PR: + +## Plugin Ecosystem (if applicable) + +- [ ] Not applicable +- [ ] This PR proposes a plugin for **featured-only** listing. +- [ ] This PR proposes a plugin for **bundled** starter inclusion. + +If plugin-related, provide: + +- Plugin repo URL: +- Gem name: +- Jekyll plugin id: +- Compatibility (`al_folio_min`/`al_folio_max`): +- Demo page/post path: +- Maintainer contact: + +## Starter Wiring Changes + +- [ ] Not applicable +- [ ] Updated `Gemfile` dependency wiring. +- [ ] Updated `_config.yml` plugin activation/config. +- [ ] Updated `_data/featured_plugins.yml` metadata. + +## Validation + +- [ ] `npm ci` +- [ ] `bundle exec jekyll build` +- [ ] `npm run lint:prettier` +- [ ] `npm run lint:style-contract` +- [ ] Integration tests (`test/integration_*.sh`) as needed +- [ ] Visual tests (`npm run test:visual`) as needed + +## Notes + +Compatibility, migration implications, and follow-ups: diff --git a/.github/workflows/broken-links.yml b/.github/workflows/broken-links.yml index ce7b9e8d7a41d..55654d493602a 100644 --- a/.github/workflows/broken-links.yml +++ b/.github/workflows/broken-links.yml @@ -51,4 +51,4 @@ jobs: with: fail: true # 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 --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' + args: --user-agent 'curl/7.54' --max-retries 3 --retry-wait-time 2 --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' diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 5fb7e8ae21c91..dbe53a71b9872 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -7,8 +7,6 @@ on: - main paths: - "assets/**" - - "_sass/**" - - "_scripts/**" - "**.bib" - "**.html" - "**.js" @@ -36,8 +34,6 @@ on: - main paths: - "assets/**" - - "_sass/**" - - "_scripts/**" - "**.bib" - "**.html" - "**.js" @@ -81,6 +77,13 @@ jobs: with: python-version: "3.13" cache: "pip" # caching pip dependencies + - name: Setup Node 🧰 + uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + - name: Install JS deps 📦 + run: npm ci - name: Update _config.yml ⚙️ uses: fjogeleit/yaml-update-action@main with: diff --git a/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml new file mode 100644 index 0000000000000..dec50bfcb928f --- /dev/null +++ b/.github/workflows/unit-tests.yml @@ -0,0 +1,90 @@ +name: Integration tests + +on: + push: + branches: + - master + - main + - v1.0-dev + paths: + - "Gemfile" + - "Gemfile.lock" + - "_config.yml" + - "_data/**" + - "_pages/**" + - "_posts/**" + - "_projects/**" + - "assets/**" + - "test/**" + - "package.json" + - "package-lock.json" + - ".github/workflows/unit-tests.yml" + pull_request: + branches: + - master + - main + - v1.0-dev + paths: + - "Gemfile" + - "Gemfile.lock" + - "_config.yml" + - "_data/**" + - "_pages/**" + - "_posts/**" + - "_projects/**" + - "assets/**" + - "test/**" + - "package.json" + - "package-lock.json" + - ".github/workflows/unit-tests.yml" + +jobs: + comments-integration-tests: + runs-on: ubuntu-latest + steps: + - name: Checkout 🛎️ + 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 🧰 + uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + + - name: Install JS deps 📦 + run: npm ci + + - name: Run style contract lint 🧷 + run: npm run lint:style-contract + + - name: Install build prerequisites 🔧 + run: | + sudo apt-get update && sudo apt-get install -y imagemagick + pip3 install --upgrade nbconvert + + - name: Run comments integration test 🧪 + run: bash test/integration_comments.sh + + - name: Run plugin toggle integration test 🔌 + run: bash test/integration_plugin_toggles.sh + + - name: Run distill integration test 📄 + run: bash test/integration_distill.sh + + - name: Run bootstrap compatibility integration test 🧩 + run: bash test/integration_bootstrap_compat.sh + + - name: Run upgrade CLI integration test ⬆️ + run: bash test/integration_upgrade_cli.sh diff --git a/.github/workflows/upgrade-check.yml b/.github/workflows/upgrade-check.yml new file mode 100644 index 0000000000000..77524b7bc1c27 --- /dev/null +++ b/.github/workflows/upgrade-check.yml @@ -0,0 +1,59 @@ +name: Upgrade contract checks + +on: + push: + branches: + - master + - main + - v1.0-dev + paths: + - "_config.yml" + - "_data/**" + - "_pages/**" + - "_posts/**" + - "_projects/**" + - "assets/**" + - "Gemfile" + - "Gemfile.lock" + - "test/integration_upgrade_cli.sh" + - ".github/workflows/upgrade-check.yml" + pull_request: + branches: + - master + - main + - v1.0-dev + paths: + - "_config.yml" + - "_data/**" + - "_pages/**" + - "_posts/**" + - "_projects/**" + - "assets/**" + - "Gemfile" + - "Gemfile.lock" + - "test/integration_upgrade_cli.sh" + - ".github/workflows/upgrade-check.yml" + +jobs: + upgrade-check: + runs-on: ubuntu-latest + steps: + - name: Checkout 🛎️ + uses: actions/checkout@v4 + + - name: Setup Ruby 💎 + uses: ruby/setup-ruby@v1 + with: + ruby-version: "3.3.5" + bundler-cache: true + + - name: Run upgrade audit 🧪 + run: bundle exec al-folio upgrade audit + + - name: Upload upgrade report 📄 + if: always() + uses: actions/upload-artifact@v4 + with: + name: al-folio-upgrade-report + path: al-folio-upgrade-report.md + if-no-files-found: ignore diff --git a/.github/workflows/visual-regression.yml b/.github/workflows/visual-regression.yml new file mode 100644 index 0000000000000..69895655de1bc --- /dev/null +++ b/.github/workflows/visual-regression.yml @@ -0,0 +1,139 @@ +name: Visual regression checks + +on: + pull_request: + branches: [main, master, v1.0-dev] + paths: + - "_config.yml" + - "_data/**" + - "_bibliography/**" + - "_pages/**" + - "_posts/**" + - "_projects/**" + - "assets/**" + - "test/visual/**" + - ".github/workflows/visual-regression.yml" + - "package.json" + - "package-lock.json" + - "Gemfile" + - "Gemfile.lock" + push: + branches: [v1.0-dev] + paths: + - "_config.yml" + - "_data/**" + - "_bibliography/**" + - "_pages/**" + - "_posts/**" + - "_projects/**" + - "assets/**" + - "test/visual/**" + - ".github/workflows/visual-regression.yml" + - "package.json" + - "package-lock.json" + - "Gemfile" + - "Gemfile.lock" + +jobs: + visual-regression: + runs-on: ubuntu-latest + timeout-minutes: 20 + steps: + - name: Checkout candidate 🛎️ + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Setup Ruby 💎 + uses: ruby/setup-ruby@v1 + with: + ruby-version: "3.3.5" + bundler-cache: true + + - name: Setup Node 🧰 + uses: actions/setup-node@v4 + with: + node-version: "20" + cache: "npm" + + - name: Install JS deps 📦 + run: npm ci + + - name: Prepare baseline worktree (v0.16.3) 🧱 + run: | + git worktree add ../al-folio-baseline v0.16.3 + (cd ../al-folio-baseline && bundle install && npm ci) + + - name: Install Jupyter + ImageMagick runtime deps 🧰 + run: | + sudo apt-get update + sudo apt-get install -y imagemagick python3-pip + pip3 install --user jupyter nbconvert + + - name: Install Playwright browser 🧪 + run: npx playwright install --with-deps chromium webkit + + - name: Run visual parity checks 👀 + env: + BASELINE_URL: http://127.0.0.1:4100 + NO_WEBSERVER: "1" + run: | + set -euo pipefail + export PATH="$HOME/.local/bin:$PATH" + + (cd ../al-folio-baseline && bundle exec jekyll serve --host 127.0.0.1 --port 4100 --baseurl /al-folio --quiet > /tmp/jekyll-baseline.log 2>&1) & + BASELINE_PID=$! + (bundle exec jekyll serve --host 127.0.0.1 --port 4000 --baseurl /al-folio --quiet > /tmp/jekyll-candidate.log 2>&1) & + CANDIDATE_PID=$! + + cleanup() { + kill "$BASELINE_PID" "$CANDIDATE_PID" >/dev/null 2>&1 || true + } + trap cleanup EXIT + + READY=0 + for _ in {1..150}; do + if curl -fsS http://127.0.0.1:4000/al-folio/ >/dev/null && curl -fsS http://127.0.0.1:4100/al-folio/ >/dev/null; then + READY=1 + break + fi + + if ! kill -0 "$BASELINE_PID" >/dev/null 2>&1 || ! kill -0 "$CANDIDATE_PID" >/dev/null 2>&1; then + echo "Jekyll server exited before becoming ready." + echo "--- baseline log ---" + cat /tmp/jekyll-baseline.log || true + echo "--- candidate log ---" + cat /tmp/jekyll-candidate.log || true + exit 1 + fi + sleep 2 + done + + if [ "$READY" -ne 1 ]; then + echo "Timed out waiting for Jekyll servers (5 minutes)." + echo "--- baseline log ---" + cat /tmp/jekyll-baseline.log || true + echo "--- candidate log ---" + cat /tmp/jekyll-candidate.log || true + exit 1 + fi + + npm run test:visual -- --reporter=line + + - name: Upload Playwright report 📄 + if: always() + uses: actions/upload-artifact@v4 + with: + name: playwright-report + path: playwright-report + if-no-files-found: ignore + + - name: Upload Jekyll logs 📄 + if: always() + uses: actions/upload-artifact@v4 + with: + name: jekyll-visual-logs + path: | + /tmp/jekyll-baseline.log + /tmp/jekyll-candidate.log + if-no-files-found: ignore diff --git a/.gitignore b/.gitignore index 1fee89bc29807..579a88f57d190 100644 --- a/.gitignore +++ b/.gitignore @@ -12,4 +12,4 @@ assets/libs/ assets/rendercv/rendercv_output/*.typ Gemfile.lock node_modules/ -vendor \ No newline at end of file +vendor diff --git a/AGENTS.md b/AGENTS.md index 8b22fd6a7cdd1..083e5f884e2b2 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,81 +1,50 @@ -# Agent Guidelines for al-folio +# Agent Guidelines for al-folio (v1.x) -A simple, clean, and responsive Jekyll theme for academics. +`al-folio` is the **starter repo** for the pluginized v1 architecture. -## Quick Links by Role +## Read This First -- **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) +- Start with `.github/copilot-instructions.md` for architecture, ownership boundaries, and CI expectations. +- Use `BOUNDARIES.md` as the source of truth for starter-vs-plugin ownership. -## Essential Commands +## What This Repo Owns -### Local Development (Docker) +- Starter wiring (`Gemfile`, `_config.yml`) +- Starter content and documentation +- Cross-plugin integration tests +- Visual regression tests -The recommended approach is using Docker. +Runtime/component logic belongs in owning plugin repos (`al_folio_core`, `al_folio_distill`, `al_search`, `al_icons`, `al_cookie`, and other `al-*` gems). -```bash -# Initial setup & start dev server -docker compose pull && docker compose up -# Site runs at http://localhost:8080 +## Validated Local Command Set -# Rebuild after changing dependencies or Dockerfile -docker compose up --build +Run from repo root: -# Stop containers and free port 8080 +```bash +npm ci +npm run lint:prettier +npm run lint:style-contract +bundle exec jekyll build --baseurl /al-folio +bash test/integration_comments.sh +bash test/integration_plugin_toggles.sh +bash test/integration_distill.sh +bash test/integration_bootstrap_compat.sh +bash test/integration_upgrade_cli.sh +npx playwright install chromium webkit +npm run test:visual +bundle exec al-folio upgrade audit +bundle exec al-folio upgrade report +docker compose up -d +curl -fsS http://127.0.0.1:8080/al-folio/ >/dev/null +docker compose logs --tail=80 docker compose down ``` -### Pre-Commit Checklist - -Before every commit, you **must** run these steps: - -1. **Format Code:** - ```bash - # (First time only) - npm install --save-dev prettier @shopify/prettier-plugin-liquid - # Format all files - npx prettier . --write - ``` -2. **Build Locally & Verify:** - - ```bash - # Rebuild the site - docker compose up --build - - # Verify by visiting http://localhost:8080. - # Check navigation, pages, images, and dark mode. - ``` - -## 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"` - -## Development Workflow - -- **Git & Commits:** For commit message format and Git practices, see [.github/GIT_WORKFLOW.md](.github/GIT_WORKFLOW.md). -- **Code-Specific Instructions:** 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) | - -## Common Issues +Docker note: v1 uses `/srv/jekyll/bin/entry_point.sh` and serves from container-local `/tmp/_site` to avoid host bind-mount write deadlocks. -For troubleshooting, see: +## Agent Routing Rules -- [Common Pitfalls & Workarounds](.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. +- If change is starter wiring/docs/integration/visual testing: edit here. +- If change is runtime feature behavior: route to owning plugin repo. +- Do not add starter-local npm build scripts for theme/runtime assets. +- Keep docs aligned with pluginized v1 ownership. diff --git a/BOUNDARIES.md b/BOUNDARIES.md new file mode 100644 index 0000000000000..54193ce3cc564 --- /dev/null +++ b/BOUNDARIES.md @@ -0,0 +1,62 @@ +# Ownership Boundaries (v1.x) + +`al-folio` is a starter kit. Runtime/component ownership lives in gems. + +## Runtime ownership + +- `al-folio` (starter): example content, wiring, docs, integration harness. +- `al_folio_core`: shared layouts/includes/runtime primitives and upgrade contracts. +- `al_folio_distill`: Distill templates/runtime assets. +- `al_cookie`: cookie consent runtime assets and consent logic. +- `al_icons`: icon runtime loading (Font Awesome, Academicons, Scholar Icons). +- `al_search`: search runtime payload (`ninja-keys`, search setup/hotkey assets). +- Other `al-*` gems: feature-specific assets, tags, filters, and runtime behavior. + +## Plugin naming convention + +- Theme-coupled plugins: + - GitHub repo: `al-folio-` + - gem/plugin id: `al_folio_` +- Reusable plugins: + - GitHub repo: `al-` or neutral name + - gem/plugin id aligned with plugin namespace +- Third-party non-`al-*` plugins are valid ecosystem plugins and may be featured. + +## Featured vs bundled plugins + +- `featured`: listed in docs/catalog with metadata and compatibility, but not required in starter dependencies. +- `bundled`: included in starter wiring (`Gemfile` + `_config.yml` plugin list) and shipped by default. + +Use [`_data/featured_plugins.yml`](_data/featured_plugins.yml) as the catalog source of truth. + +## Minified asset policy + +- Use pinned CDN assets (with SRI) for stable standalone third-party libraries. +- Keep vendored release-time artifacts (with provenance) only where ownership needs complex runtime/module graphs (for example: `al_search`, `al_folio_distill`). +- Do not add install-time network fetches in `gem install` / `bundle install` paths. + +## Test ownership + +- `al-folio` tests: + - Visual regression/parity (`test/visual/**`) + - Cross-gem integration checks (plugin toggles, compat wiring, upgrade smoke tests) + - Starter wiring contracts only +- Gem-local tests (`al-folio-core`, `al-folio-distill`, `al-*`): + - Component correctness (tags, filters, generators) + - Runtime asset packaging contracts + - Feature edge cases + - Migration/upgrade contract logic in the owning gem + +## Prohibited pattern + +- Do not duplicate gem-owned component correctness tests in `al-folio`. +- Do not add local starter copies of gem-owned runtime files unless intentionally overriding behavior. + +## PR triage playbook + +- If a PR changes starter wiring/docs/content/tests only: keep it in `al-folio`. +- If a PR changes gem-owned runtime/component behavior: redirect/port to the owning gem repo. +- If a PR introduces a feature without an owner: + - create a plugin proposal issue + - recommend a standalone plugin repo + - close/redirect the starter PR with references. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6b50186dc2d0f..8b3adede84301 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,6 +10,67 @@ 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. +## Repository Routing (v1.x) + +`al-folio` is a starter in `v1.x`. Before opening a PR, route your change to the owning repo: + +- `al-folio` (this repo): starter wiring (`Gemfile`, `_config.yml`), example/demo content, documentation, visual tests, cross-gem integration tests. +- `al-folio-core` and other `al-*` gem repos: component runtime behavior, layouts/includes/style primitives, feature logic, unit/component tests. +- If a feature does not fit an existing plugin, propose a new standalone plugin first, then implement there. + +See [`BOUNDARIES.md`](BOUNDARIES.md) for ownership details. + +## Plugin Naming Convention (v1.x) + +We use a hybrid naming convention: + +- Theme-coupled plugins: repo `al-folio-`, gem/plugin id `al_folio_`. +- Reusable plugins: repo `al-` or neutral name, gem/plugin id aligned with plugin namespace. +- Third-party non-`al-*` plugins are allowed in the ecosystem and can be featured. + +## Featuring Community Plugins + +You can publish and own your own plugin, then propose it for featuring in `al-folio`. + +1. Open a **Plugin Feature Proposal** issue in this repo. +2. Share plugin metadata (repo URL, gem name, plugin id, compatibility, owner, demo path). +3. Open a PR to this starter updating: + - [`_data/featured_plugins.yml`](_data/featured_plugins.yml) + - optional demo content page/post under `_pages/` or `_posts/` +4. If requesting **bundled** status (not only featured listing), include starter wiring updates in: + - [Gemfile](Gemfile) + - [\_config.yml](_config.yml) + +Featuring and bundling are separate decisions: + +- **Featured-only**: catalog/docs entry and demo. +- **Bundled**: also included in starter dependencies/plugin list by maintainers. + +## Test Ownership + +`al-folio` is a starter kit in `v1.x`. Keep tests aligned with runtime ownership: + +- `al-folio`: visual regression + cross-gem integration + starter wiring contracts. +- Gem repos (`al-folio-core`, `al-folio-distill`, `al-*`): component correctness/unit tests and asset/runtime contract checks. + +Do not add duplicate component-level correctness tests to this starter when the component is gem-owned. See [`BOUNDARIES.md`](BOUNDARIES.md). + +## Local Validation + +Before opening/updating a PR in `v1.x`, run: + +```bash +npm ci +bundle exec jekyll build +``` + +If your change touches visual tests, install Playwright browsers once and run: + +```bash +npx playwright install chromium webkit +npm run test:visual +``` + ## GitHub Copilot Agents This repository includes specialized GitHub Copilot agents and files to assist with development and documentation: @@ -53,7 +114,7 @@ To enhance GitHub Copilot's effectiveness when working with specific file types, - **`.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/` +- **`.github/instructions/javascript-scripts.instructions.md`** – Guidance for starter JavaScript and runtime script snippets These files help Copilot agents understand project conventions, build requirements, and development workflows without requiring codebase exploration. diff --git a/CUSTOMIZE.md b/CUSTOMIZE.md index 6f6e3c1825956..dea00979baa2b 100644 --- a/CUSTOMIZE.md +++ b/CUSTOMIZE.md @@ -62,7 +62,7 @@ Here we will give you some tips on how to customize the website. One important t - [How it works](#how-it-works) - [Configuration](#configuration-1) - [Disable related posts for a specific post](#disable-related-posts-for-a-specific-post) - - [Additional configuration in _config.yml](#additional-configuration-in-_configyml) + - [Additional configuration in \_config.yml](#additional-configuration-in-_configyml) - [Managing publication display](#managing-publication-display) - [Adding a Google Calendar](#adding-a-google-calendar) - [Basic usage](#basic-usage) @@ -113,33 +113,18 @@ The project is structured as follows, focusing on the main components that you w │   ├── 📄 cv.yml: CV in YAML format, used when assets/json/resume.json is not found │   ├── 📄 repositories.yml: users and repositories info in YAML format │   └── 📄 socials.yml: your social media and contact info in YAML format -├── 📂 _includes/: contains code parts that are included in the main HTML file -│   └── 📄 news.liquid: defines the news section layout in the about page -├── 📂 _layouts/: contains the layouts to choose from in the frontmatter of the Markdown files +├── 📂 _includes/: optional local override includes (default includes are gem-owned in `v1.x`) +├── 📂 _layouts/: optional local override layouts (default layouts are gem-owned in `v1.x`) ├── 📂 _news/: the news that will appear in the news section in the about page ├── 📂 _pages/: contains the pages of the website | └── 📄 404.md: 404 page (page not found) ├── 📂 _posts/: contains the blog posts ├── 📂 _projects/: contains the projects -└── 📂 _sass/: contains the SASS files that define the style of the website - ├── 📂 font-awesome/: contains the SCSS files for Font Awesome - ├── 📄 _blog.scss: blog post, tags, and pagination styles - ├── 📄 _components.scss: reusable component styles (cards, profiles, CV, projects) - ├── 📄 _cv.scss: style of the CV page - ├── 📄 _distill.scss: style of the Distill articles - ├── 📄 _footer.scss: footer styles - ├── 📄 _layout.scss: overall layout styles - ├── 📄 _navbar.scss: navigation bar and dropdown menu styles - ├── 📄 _publications.scss: publication list and bibliography styles - ├── 📄 _tabs.scss: tabbed content styles - ├── 📄 _teachings.scss: course and teaching styles - ├── 📄 _themes.scss: theme colors and icons - ├── 📄 _typograms.scss: typogram diagram styles - ├── 📄 _typography.scss: text, headings, links, tables, and blockquote styles - ├── 📄 _utilities.scss: utility styles (code highlighting, forms, modals, animations) - └── 📄 _variables.scss: variables used in the SASS files +└── 📂 test/: starter integration + visual regression checks ``` +In `v1.x`, the starter is intentionally thin. Theme internals (layouts/includes/style pipeline/runtime assets) are owned by gems such as `al_folio_core` and `al_folio_distill`. + ## Configuration The configuration file [\_config.yml](_config.yml) contains the main configuration of the website. Most of the settings is self-explanatory and we also tried to add as much comments as possible. If you have any questions, please check if it was not already answered in the [FAQ](FAQ.md). @@ -148,11 +133,13 @@ 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. +For `v1.x` starter sites, no local npm style build is required. Core CSS/runtime assets are shipped by the owning gems. + 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) + - Ctrl + F5 on Firefox-based browsers - **Clear your browser cache** completely - **Use a private/incognito session** to ensure no cached content: - [Chrome](https://support.google.com/chrome/answer/95464) @@ -260,10 +247,11 @@ Understanding al-folio's technology stack will help you better customize and ext ### Frontend - **Markdown**: Content is written in Markdown format for pages, blog posts, and collections. This makes it easy to create and maintain content without worrying about HTML. -- **Liquid templating**: [Liquid](https://shopify.github.io/liquid/) is used for dynamic template generation. Liquid templates are used in the `_layouts/` and `_includes/` directories to define how your content should be displayed. +- **Liquid templating**: [Liquid](https://shopify.github.io/liquid/) is used for dynamic template generation. In `v1.x`, canonical templates are gem-owned; local `_layouts/` and `_includes/` are overrides when you need project-specific customization. - **HTML & CSS**: The theme uses semantic HTML5 and modern CSS for styling and layout. -- **SCSS**: Stylesheets are written in [SCSS (Sass)](https://sass-lang.com/), a CSS preprocessor that provides variables, mixins, and functions for more maintainable styling. SCSS files are located in `_sass/` and compiled to CSS during the build process. -- **Bootstrap**: [Bootstrap 4.6](https://getbootstrap.com/docs/4.6/) is used for responsive grid layout and base styling components. +- **Tailwind CSS (v1.x core)**: al-folio `v1.x` is Tailwind-first. Core layout/styling is generated from Tailwind with a small set of theme primitives. +- **SCSS token bridge**: Theme tokens and dark/light palettes remain in `_sass/` and are bridged into Tailwind-based output. +- **Bootstrap compatibility mode (optional)**: Legacy Bootstrap-marked content can be supported temporarily through `al_folio.compat.bootstrap.enabled`. - **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. - **Mermaid**: For creating diagrams (flowcharts, sequence diagrams, etc.) directly in Markdown. @@ -313,7 +301,7 @@ Understanding how these technologies work together will help you customize al-fo 1. **Content Creation**: Write content in Markdown 2. **Template Processing**: Jekyll processes Markdown through Liquid templates -3. **Styling**: SCSS files are compiled to CSS, with Bootstrap providing the responsive layout framework +3. **Styling**: Tailwind generates core styles, while SCSS variables/tokens provide stable theme configuration 4. **Bibliography**: BibTeX files are processed by jekyll-scholar to generate publication pages 5. **Static Site Generation**: Jekyll builds all files into static HTML 6. **Deployment**: GitHub Actions automatically deploys the built site to GitHub Pages @@ -409,7 +397,9 @@ Once deployed, update the URLs above to point to your custom deployment. ## Creating new pages -You can create new pages by adding new Markdown files in the [\_pages](_pages/) directory. The easiest way to do this is to copy an existing page and modify it. You can choose the layout of the page by changing the [layout](https://jekyllrb.com/docs/layouts/) attribute in the [frontmatter](https://jekyllrb.com/docs/front-matter/) of the Markdown file, and also the path to access it by changing the [permalink](https://jekyllrb.com/docs/permalinks/) attribute. You can also add new layouts in the [\_layouts](_layouts/) directory if you feel the need for it. +You can create new pages by adding new Markdown files in the [\_pages](_pages/) directory. The easiest way to do this is to copy an existing page and modify it. You can choose the layout of the page by changing the [layout](https://jekyllrb.com/docs/layouts/) attribute in the [frontmatter](https://jekyllrb.com/docs/front-matter/) of the Markdown file, and also the path to access it by changing the [permalink](https://jekyllrb.com/docs/permalinks/) attribute. + +In `v1.x`, default layout implementations are gem-owned (primarily `al_folio_core` and feature gems). If you need custom layout behavior, create a local override file in your site (for example, create `_layouts/.liquid` in your starter repo). If you want to improve shared runtime behavior for everyone, open a PR in the owning gem repo. ## Creating new blog posts @@ -796,11 +786,11 @@ There are several custom bibtex keywords that you can use to affect how the entr - `supp`: Adds a "Supp" button to a specified file (if a full link is not specified, the file will be assumed to be placed in the /assets/pdf/ directory) - `website`: Adds a "Website" button redirecting to the specified link -You can implement your own buttons by editing the [\_layouts/bib.liquid](_layouts/bib.liquid) file. +In `v1.x`, bibliography buttons/layout runtime is gem-owned (`al_citations` + `al_folio_core`). For local customization, add a local override `_layouts/bib.liquid` in your site; for upstream/shared behavior changes, open a PR in the owning gem repo. ## Changing theme color -A variety of beautiful theme colors have been selected for you to choose from. The default is purple, but you can quickly change it by editing the `--global-theme-color` variable in the [\_sass/\_themes.scss](_sass/_themes.scss) file. Other color variables are listed there as well. The stock theme color options available can be found at [\_sass/\_variables.scss](_sass/_variables.scss). You can also add your own colors to this file assigning each a name for ease of use across the template. +A variety of beautiful theme colors have been selected for you to choose from. In `v1.x`, theme tokens are gem-owned by default. To customize colors locally, either use `_config.yml` theme settings (for light/dark scheme selection) or create local `_sass/_themes.scss` and `_sass/_variables.scss` override files in your starter repo (these override gem defaults). ## Customizing layout and UI @@ -831,6 +821,8 @@ The template supports icons from: - [Font Awesome](https://fontawesome.com/) - [Scholar Icons](https://louisfacun.github.io/scholar-icons/) +In `v1.x`, icon runtime ownership is provided by the `al_icons` plugin. Icon files are loaded from pinned CDN URLs via `third_party_libraries` in `_config.yml` (not from starter-local `assets/fonts` or `assets/webfonts` copies). + 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 @@ -860,7 +852,57 @@ socials_in_search: true - `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. -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. Search runtime assets are owned by the `al_search` plugin. + +The navbar search button and the `Ctrl/Cmd + K` shortcut both open the same search modal. + +## Sidebar table of contents (Tocbot) + +Use front matter on pages/posts: + +```yaml +toc: + sidebar: left # or right + collapse: expanded # or auto +# optional explicit depth override: +# collapse_depth: 3 +``` + +In `v1.x`, sidebar TOC rendering is powered by Tocbot (configured in `_config.yml` under `third_party_libraries.tocbot`). +You can override displayed TOC labels per heading with `data-toc-text`: + +```markdown +## Customizing Your Table of Contents + +{:data-toc-text="Customizing"} +``` + +`toc.collapse` behavior: + +- `expanded` (default): render the full nested TOC expanded. +- `auto`: collapse nested branches and expand the active branch as you scroll. + +If needed, `toc.collapse_depth` can be used for direct Tocbot-style depth control. + +## Pretty tables in Tailwind mode + +Set `pretty_table: true` in front matter to enable interactive tables. + +- If `al_folio.compat.bootstrap.enabled: true`, Bootstrap Table runtime is used. +- If `al_folio.compat.bootstrap.enabled: false`, the built-in Tailwind-first vanilla table engine is used. + +The Tailwind table engine supports `data-toggle="table"` plus search, pagination, sortable columns, and click-to-select. + +## Lightbox images + +Set in front matter: + +```yaml +images: + lightbox2: true +``` + +`v1.x` uses the `al_img_tools` plugin lightbox adapter (vanilla JS, no jQuery requirement) while keeping existing `data-lightbox` markup. ## Social media previews @@ -1075,6 +1117,10 @@ third_party_libraries: - `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 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. +- `v1.x` policy: use pinned CDN assets (with SRI where available) for standalone libraries; keep vendored release-time artifacts only in owning plugins when runtime/module graphs are complex (for example `al_search`, `al_folio_distill`). +- `v1.x` policy: do not add install-time downloads in `gem install` / `bundle install`. +- `al_math` uses CDN TikZJax assets configured in `third_party_libraries.tikzjax`. +- `toc.sidebar` uses Tocbot assets configured in `third_party_libraries.tocbot`. To update a library: @@ -1088,9 +1134,60 @@ To update a library: ``` Replace `[FILE_URL]` with the URL of the library file. Then, prefix the result with `sha384-` and use it in the `integrity` field. - For detailed instructions on updating specific libraries, see the FAQ: - - [How can I update Academicons version](FAQ.md#how-can-i-update-academicons-version-on-the-template) - - [How can I update Font Awesome version](FAQ.md#how-can-i-update-font-awesome-version-on-the-template) + For icon-specific updates, see the FAQ: + - [How can I update icon library versions on the template](FAQ.md#how-can-i-update-icon-library-versions-on-the-template) + +## Plugin ecosystem (v1.x) + +`al-folio` is a thin starter in `v1.x`. Runtime ownership belongs to plugins/gems. + +### Naming convention + +- Theme-coupled plugins: + - repo: `al-folio-` + - gem/plugin id: `al_folio_` +- Reusable plugins: + - repo: `al-` or neutral name + - gem/plugin id aligned with plugin namespace + +Third-party non-`al-*` plugins are also valid and may be featured in the catalog. + +### Featured vs bundled plugins + +- **Featured-only**: shown in catalog/docs, not included in starter dependencies by default. +- **Bundled**: included by default in starter wiring. + +Starter wiring uses: + +- [Gemfile](Gemfile) for dependencies +- [\_config.yml](_config.yml) for plugin activation/configuration + +The starter currently has no gemspec; plugin integration docs should reference these two files. + +## Bootstrap compatibility mode (v1.x) + +al-folio `v1.0` and newer are Tailwind-first. If your site still contains Bootstrap-marked content from older versions, use: + +```yaml +al_folio: + compat: + bootstrap: + enabled: true +``` + +### Compatibility matrix + +- **Supported through `v1.2`**: common Bootstrap-marked layout/content patterns (for example: `row`, `col-*`, `card`, `btn`, and `data-toggle` attributes for collapse/dropdown/tooltip/popover) +- **Deprecated in `v1.3`**: compatibility mode remains available but migration warnings become stricter +- **Removed in `v2.0`**: compatibility mode is no longer part of the official runtime + +For upgrades, run: + +```bash +bundle exec al-folio upgrade audit +bundle exec al-folio upgrade apply --safe +bundle exec al-folio upgrade report +``` ## Removing content @@ -1119,10 +1216,9 @@ To remove the blog, you have to: You can also: -- delete [\_includes/latest_posts.liquid](_includes/latest_posts.liquid) -- delete [\_includes/related_posts.liquid](_includes/related_posts.liquid) -- delete [\_layouts/archive.liquid](_layouts/archive.liquid) (unless you have a custom collection that uses it) -- delete [\_plugins/external-posts.rb](_plugins/external-posts.rb) +- disable `latest_posts.enabled` in [\_pages/about.md](_pages/about.md) and disable related posts via front matter/config where needed +- in `v1.x` there are no starter-local `_includes/latest_posts.liquid`, `_includes/related_posts.liquid`, or `_layouts/archive.liquid` files to delete (these are gem-owned) +- remove `al_ext_posts` from the [Gemfile](Gemfile) and from the `plugins` section in [\_config.yml](_config.yml) - remove the `jekyll-archives-v2` gem from the [Gemfile](Gemfile) and the `plugins` section in [\_config.yml](_config.yml) (unless you have a custom collection that uses it) - remove the `classifier-reborn` gem from the [Gemfile](Gemfile) @@ -1131,7 +1227,7 @@ You can also: To remove the news section, you can: - delete the [\_news](_news/) directory -- delete the file [\_includes/news.liquid](_includes/news.liquid) and the references to it in the [\_pages/about.md](_pages/about.md) +- remove/disable the announcements block in [\_pages/about.md](_pages/about.md) (news include runtime is gem-owned in `v1.x`) - remove the `announcements` part in [\_pages/about.md](_pages/about.md) - remove the news part in the `Collections` section in the [\_config.yml](_config.yml) file @@ -1146,8 +1242,7 @@ To remove the projects, you can: You can also: -- delete [\_includes/projects_horizontal.liquid](_includes/projects_horizontal.liquid) -- delete [\_includes/projects.liquid](_includes/projects.liquid) +- in `v1.x`, projects include templates are gem-owned and not present as starter-local files to delete ### Removing the publications page @@ -1160,13 +1255,9 @@ To remove the publications, you can: You can also: -- delete the [\_layouts/bib.liquid](_layouts/bib.liquid) file -- delete [\_includes/bib_search.liquid](_includes/bib_search.liquid) -- delete [\_includes/citation.liquid](_includes/citation.liquid) -- delete [\_includes/selected_papers.liquid](_includes/selected_papers.liquid) -- delete [\_plugins/google-scholar-citations.rb](_plugins/google-scholar-citations.rb) -- delete [\_plugins/hide-custom-bibtex.rb](_plugins/hide-custom-bibtex.rb) -- delete [\_plugins/inspirehep-citations.rb](_plugins/inspirehep-citations.rb) +- in `v1.x`, bibliography layout/includes are gem-owned, so there are no starter-local `_layouts/bib.liquid`, `_includes/bib_search.liquid`, `_includes/citation.liquid`, or `_includes/selected_papers.liquid` files to delete +- the old `hide-custom-bibtex.rb` helper is now provided by `al_folio_core` (there is no local file to delete) +- remove `al_citations` from the [Gemfile](Gemfile) and from the `plugins` section in [\_config.yml](_config.yml) - remove the `jekyll-scholar` gem from the [Gemfile](Gemfile) and the `plugins` section in [\_config.yml](_config.yml) ### Removing the repositories page @@ -1174,7 +1265,7 @@ You can also: To remove the repositories, you can: - delete the repositories page [\_pages/repositories.md](_pages/repositories.md) -- delete [\_includes/repository/](_includes/repository/) directory +- in `v1.x`, repository rendering includes are gem-owned and not present as starter-local files to delete ### You can also remove pages through commenting out front-matter blocks @@ -1213,16 +1304,14 @@ Due to the necessary permissions (PAT and others mentioned above), it is recomme ## Customizing fonts, spacing, and more -The `_sass/` directory contains specialized SCSS files organized by feature and usage. To customize fonts, spacing, colors, and other styles, edit the relevant file based on what you're modifying: +In `v1.x`, base SCSS is gem-owned. For project-specific style customization, create local override files under `_sass/` in your starter repo and define only the variables/rules you want to change. + +Common override patterns: -- **Typography:** Edit `_typography.scss` to change fonts, heading styles, links, tables, and blockquotes. -- **Navigation:** Edit `_navbar.scss` to customize the navigation bar and dropdown menus. -- **Colors and themes:** Edit `_themes.scss` to change theme colors and `_variables.scss` for global variables. -- **Blog styles:** Edit `_blog.scss` to customize blog post listings, tags, and pagination. -- **Publications:** Edit `_publications.scss` to modify bibliography and publication display styles. -- **Components:** Edit `_components.scss` to customize reusable components like cards, profiles, and projects. -- **Code and utilities:** Edit `_utilities.scss` for code highlighting, forms, modals, and animations. -- **Layout:** Edit `_layout.scss` for overall page layout styles. +- **Typography:** add overrides for headings, inline code, tables, and blockquotes. +- **Navigation:** override navbar/dropdown spacing, alignment, and interaction styles. +- **Colors and themes:** override token variables such as `--global-theme-color` and related palette variables. +- **Components:** override cards, projects, publications, and utility classes used by your content. The easiest way to preview changes in advance is by using [Chrome dev tools](https://developer.chrome.com/docs/devtools/css) or [Firefox dev tools](https://firefox-source-docs.mozilla.org/devtools-user/). Inspect elements to see which styles apply and experiment with changes before editing the SCSS files. For more information on how to use these tools, check [Chrome](https://developer.chrome.com/docs/devtools/css) and [Firefox](https://firefox-source-docs.mozilla.org/devtools-user/page_inspector/how_to/examine_and_edit_css/index.html) how-tos, and [this tutorial](https://www.youtube.com/watch?v=l0sgiwJyEu4). @@ -1256,7 +1345,7 @@ In this folder you need to store your file in the same format as you would in `_ ## GDPR Cookie Consent Dialog -**al-folio** includes a built-in GDPR-compliant cookie consent dialog to help you respect visitor privacy and comply with privacy regulations (GDPR, CCPA, etc.). The feature is powered by [Vanilla Cookie Consent](https://cookieconsent.orestbida.com/) and integrates with all analytics providers. +**al-folio** supports a GDPR-compliant cookie consent dialog via the `al_cookie` plugin to help you respect visitor privacy and comply with privacy regulations (GDPR, CCPA, etc.). The feature is powered by [Vanilla Cookie Consent](https://cookieconsent.orestbida.com/) and integrates with all analytics providers. ### How it works @@ -1287,7 +1376,14 @@ In this folder you need to store your file in the same format as you would in `_ enable_cookie_consent: true ``` -3. Rebuild your site: +3. Ensure `al_cookie` is enabled in your plugin list: + + ```yaml + plugins: + - al_cookie + ``` + +4. Rebuild your site: ```bash docker compose down && docker compose up @@ -1295,18 +1391,18 @@ In this folder you need to store your file in the same format as you would in `_ bundle exec jekyll serve ``` -4. The consent dialog will automatically appear on your site's homepage on first visit +5. The consent dialog will automatically appear on your site's homepage on first visit ### Customizing the consent dialog -The consent dialog configuration and messages are defined in [`_scripts/cookie-consent-setup.js`](_scripts/cookie-consent-setup.js). You can customize: +The consent dialog configuration and messages are now owned by `al_cookie` (`lib/templates/cookie_consent_setup.js.liquid` in that gem). To customize behavior, override cookie consent scripts in your site templates or fork/pin `al_cookie` and adjust the template there. - Dialog titles and button labels - Cookie categories and descriptions - Contact information links (points to `#contact` by default) - Language translations -To modify the dialog, edit the `language.translations.en` section in `_scripts/cookie-consent-setup.js`. For example, to change the consent dialog title: +To modify the dialog, edit the `language.translations.en` section in the plugin template. For example, to change the consent dialog title: ```javascript consentModal: { diff --git a/FAQ.md b/FAQ.md index 64d7581a908ee..e0993c8a15e14 100644 --- a/FAQ.md +++ b/FAQ.md @@ -15,9 +15,13 @@ Here are some frequently asked questions. If you have a different question, plea - [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) - [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) + - [How do I upgrade from al-folio `v1.0` to `v1.1+` with minimal friction?](#how-do-i-upgrade-from-al-folio-v10-to-v11-with-minimal-friction) + - [How do I handle legacy Bootstrap-marked pages on Tailwind-first `v1.x`?](#how-do-i-handle-legacy-bootstrap-marked-pages-on-tailwind-first-v1x) - [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 Font Awesome version on the template](#how-can-i-update-font-awesome-version-on-the-template) + - [How can I update icon library versions on the template](#how-can-i-update-icon-library-versions-on-the-template) + - [How should I name plugins in `v1.x`?](#how-should-i-name-plugins-in-v1x) + - [How can I propose featuring my plugin in `al-folio`?](#how-can-i-propose-featuring-my-plugin-in-al-folio) + - [Why does plugin integration use `Gemfile` + `_config.yml` instead of a gemspec?](#why-does-plugin-integration-use-gemfile--_configyml-instead-of-a-gemspec) - [What do all these GitHub actions/workflows mean?](#what-do-all-these-github-actionsworkflows-mean) - [How can I use Google Search Console ID on the template?](#how-can-i-use-google-search-console-id-on-the-template) - [What are Code Wiki and DeepWiki?](#what-are-code-wiki-and-deepwiki) @@ -95,21 +99,166 @@ The following actions uses node12 which is deprecated and will be forced to run The `set-output` command is deprecated and will be disabled soon. Please upgrade to using Environment Files. For more information see: https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/ ``` -If that's the case, you are using deprecated libraries/commands. This happens because you are using a very old version of al-folio. To fix this it is recommended [upgrading your code to the latest version](INSTALL.md#upgrading-from-a-previous-version) of the template. You will probably need to do some manual merging. If you find it easier, you could create a copy of your repository, do a fresh installation from the template and reapply all your changes. For this I would recommend a tool like [meld](https://meldmerge.org/) or [winmerge](https://winmerge.org/) to check the differences between directories/files. +If that's the case, you are using deprecated libraries/commands. This happens because you are using an old version of al-folio. Follow the [upgrade guide](INSTALL.md#upgrading-from-a-previous-version) and run the upgrade CLI: + +```bash +bundle exec al-folio upgrade audit +bundle exec al-folio upgrade apply --safe +bundle exec al-folio upgrade report +``` Note that libraries tend to be deprecated and support for them dropped as they are no longer maintained, and keep using them involves security breaches. Also, some of these deprecations are enforced, for example, by GitHub itself, so there's so much we can do. We have also added tons of new functionality, as well as tidying things up and improving the overall speed and structure, so you could also benefit from these improvements. +## How do I upgrade from al-folio `v1.0` to `v1.1+` with minimal friction? + +Use the SemVer migration flow: + +1. `bundle update` +2. `bundle exec al-folio upgrade audit` +3. `bundle exec al-folio upgrade apply --safe` (optional) +4. `bundle exec al-folio upgrade report` + +Then resolve all **Blocking** findings in `al-folio-upgrade-report.md`. Non-blocking findings are deprecated patterns you can migrate incrementally. + +For starter-based sites, keep `theme: al_folio_core` and avoid copying theme internals into your repo unless you intentionally need overrides. + +## Why does `v1.x` starter not have `npm run build:css` anymore? + +`al-folio` is a thin starter in `v1.x`. Tailwind/runtime build ownership moved to gem repos (primarily `al_folio_core` and feature gems), so starter builds do not require local npm CSS build commands. + +Use starter tests for: + +- visual regression/parity checks +- cross-gem integration checks + +Use gem repos for: + +- component correctness/unit tests +- plugin/runtime asset contract tests + +See [`BOUNDARIES.md`](BOUNDARIES.md) for the ownership contract. + +## Jupyter posts are enabled, but my build says `jupyter-nbconvert` is missing. What are my options? + +`jekyll-jupyter-notebook` depends on Python tooling (`jupyter` + `nbconvert`), and Bundler cannot install Python packages for you. + +Recommended options: + +1. Install Python deps locally: + +```bash +./bin/setup-python-deps +``` + +2. Or install manually in your Python environment: + +```bash +python3 -m pip install --user --break-system-packages jupyter nbconvert +``` + +3. If you do not need notebook rendering, disable/remove the plugin from `_config.yml`. + +In `v1.x`, missing `jupyter-nbconvert` is treated as warn-and-continue; notebook rendering is skipped until deps are installed. + +## How do I handle legacy Bootstrap-marked pages on Tailwind-first `v1.x`? + +`v1.x` core is Tailwind-first. If your content still relies on Bootstrap-marked classes or `data-toggle` behavior, enable compatibility mode temporarily: + +```yaml +al_folio: + compat: + bootstrap: + enabled: true +``` + +Compatibility timeline: + +- Supported through `v1.2` +- Deprecated in `v1.3` +- Removed in `v2.0` + +The compatibility runtime (`/assets/css/bootstrap-compat.css` and `/assets/js/bootstrap-compat.js`) is provided by the `al_folio_bootstrap_compat` gem when enabled. + +## How does sidebar table of contents work in `v1.x`? + +`v1.x` uses Tocbot for sidebar TOC rendering when page front matter includes: + +```yaml +toc: + sidebar: left # or right + collapse: expanded # or auto +``` + +Tocbot runtime assets are loaded from pinned CDN entries in `_config.yml` under `third_party_libraries.tocbot`. +If needed, heading labels can be overridden using `data-toc-text` attributes. +Use `collapse: auto` to expand nested TOC branches as the active section changes during scrolling. + +## Why does `pretty_table: true` still work when Bootstrap compatibility is disabled? + +When `al_folio.compat.bootstrap.enabled: false`, `v1.x` uses a built-in vanilla Tailwind table engine for `table[data-toggle="table"]` markup. +It supports search, pagination, sortable columns, and click-to-select without requiring Bootstrap Table runtime. + +When compatibility is enabled, Bootstrap Table remains available for legacy content. + +## Why does Lightbox2 work without jQuery in `v1.x`? + +In `v1.x`, `al_img_tools` provides a plugin-owned lightbox adapter for `data-lightbox` markup, so lightbox galleries no longer depend on jQuery. +Author-facing markup stays the same (`images.lightbox2: true` and `data-lightbox` links). + ## 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? `jekyll-diagrams` support was dropped in [#1992](https://github.com/alshedivat/al-folio/pull/1992) in favor of using `mermaid.js` directly. Simply [update your code](INSTALL.md#upgrading-from-a-previous-version) to get the latest changes. -## How can I update Academicons version on the template +## How can I update icon library versions on the template + +In `v1.x`, icon runtime ownership is provided by `al_icons`, and icons are loaded from pinned CDN URLs configured in `_config.yml` under `third_party_libraries`. + +Update flow: + +1. Confirm `al_icons` is enabled in `plugins`. +2. Update version values in `_config.yml`: + - `third_party_libraries.fontawesome.version` + - `third_party_libraries.academicons.version` + - `third_party_libraries.scholar-icons.version` +3. Update corresponding `integrity.css` hashes. +4. Rebuild your site and verify icon rendering on pages with socials/publications. + +Do not copy icon fonts into `assets/fonts/` or `assets/webfonts/` in the starter for `v1.x`; those local runtime assets are no longer starter-owned. + +## How should I name plugins in `v1.x`? + +Use the hybrid naming model: + +- Theme-coupled plugins: + - repo: `al-folio-` + - gem/plugin id: `al_folio_` +- Reusable plugins: + - repo: `al-` or neutral name + - gem/plugin id aligned with plugin namespace + +Third-party non-`al-*` plugins are still valid and can be featured. + +## How can I propose featuring my plugin in `al-folio`? + +Use the **Plugin Feature Proposal** issue template in this repo and include: + +1. plugin repo URL +2. gem name and Jekyll plugin id +3. compatibility range (`al_folio_min` / `al_folio_max`) +4. owner/maintainer contact +5. demo page/post path + +If maintainers decide to list it, update [`_data/featured_plugins.yml`](_data/featured_plugins.yml) through a PR. +If maintainers decide to bundle it by default, that is a separate decision and requires wiring updates in [Gemfile](Gemfile) and [\_config.yml](_config.yml). + +## Why does plugin integration use `Gemfile` + `_config.yml` instead of a gemspec? -To update the Academicons version, you need to download the latest release from the [Academicons website](https://jpswalsh.github.io/academicons/). After downloading, extract the zip file and copy the files `academicons.ttf` and `academicons.woff` from the `fonts/` directory to `assets/fonts/` and the file `academicons.min.css` from the `css/` directory to `assets/css/`. +`al-folio` starter currently does not have a gemspec. Plugin integration is controlled by: -## How can I update Font Awesome version on the template +- [Gemfile](Gemfile) for dependency declarations +- [\_config.yml](_config.yml) for Jekyll plugin activation/configuration -To update the Font Awesome version, you need to download the latest release "for the web" from the [Font Awesome website](https://fontawesome.com/download). After downloading, extract the zip file and copy the `scss/` directory content to `_sass/font-awesome/` and the `webfonts/` content to `assets/webfonts/`. +Any contribution guidance that references gemspec updates should be interpreted as starter wiring updates to those two files. ## What do all these GitHub actions/workflows mean? diff --git a/Gemfile b/Gemfile index f2fc1467ab50a..2006752504fe0 100644 --- a/Gemfile +++ b/Gemfile @@ -31,11 +31,30 @@ end # Gems for development or external data fetching (outside :jekyll_plugins) group :other_plugins do gem 'css_parser' - gem 'feedjira' - gem 'httparty' gem 'observer' # used by jekyll-scholar gem 'ostruct' # used by jekyll-twitter-plugin # gem 'terser' # used by jekyll-terser # gem 'unicode_utils' -- should be already installed by jekyll # gem 'webrick' -- should be already installed by jekyll end + +# Gems for al-folio plugins +group :al_folio_plugins do + gem 'al_folio_core', '= 1.0.7' + gem 'al_icons', '= 1.0.0' + gem 'al_folio_cv', '= 1.0.0' + gem 'al_folio_distill', '= 1.0.1' + gem 'al_folio_upgrade', '= 1.0.1' + gem 'al_folio_bootstrap_compat', '= 1.0.0' + gem 'al_cookie', '= 1.0.0' + + gem 'al_analytics', '= 1.0.0' + gem 'al_citations', '= 1.0.0' + gem 'al_ext_posts', '= 1.0.0' + gem 'al_img_tools', '= 1.0.2' + gem 'al_search', '= 1.0.2' + gem 'al_charts', '= 1.0.0' + gem 'al_math', '= 1.0.1' + gem 'al_comments', '= 1.0.0' + gem 'al_newsletter', '= 1.0.0' +end diff --git a/Gemfile.lock b/Gemfile.lock deleted file mode 100644 index ed9d3b6ded454..0000000000000 --- a/Gemfile.lock +++ /dev/null @@ -1,329 +0,0 @@ -GIT - remote: https://github.com/RobertoJBeltran/jekyll-terser.git - revision: 1085bf66d692799af09fe39f8162a1e6e42a3cc4 - specs: - jekyll-terser (0.2.3) - jekyll (>= 0.10.0) - terser (>= 1.0.0) - -GEM - remote: https://rubygems.org/ - specs: - activesupport (8.1.2) - base64 - bigdecimal - concurrent-ruby (~> 1.0, >= 1.3.1) - connection_pool (>= 2.2.5) - drb - i18n (>= 1.6, < 2) - json - logger (>= 1.4.2) - minitest (>= 5.1) - securerandom (>= 0.3) - tzinfo (~> 2.0, >= 2.0.5) - uri (>= 0.13.1) - addressable (2.8.8) - public_suffix (>= 2.0.2, < 8.0) - base64 (0.3.0) - bibtex-ruby (6.2.0) - latex-decode (~> 0.0) - logger (~> 1.7) - racc (~> 1.7) - bigdecimal (4.0.1) - citeproc (1.1.0) - date - forwardable - json - namae (~> 1.0) - observer (< 1.0) - open-uri (< 1.0) - citeproc-ruby (2.1.8) - citeproc (~> 1.0, >= 1.0.9) - csl (~> 2.0) - observer (< 1.0) - classifier-reborn (2.3.0) - fast-stemmer (~> 1.0) - matrix (~> 0.4) - colorator (1.1.0) - concurrent-ruby (1.3.6) - connection_pool (3.0.2) - crass (1.0.6) - csl (2.2.1) - forwardable (~> 1.3) - namae (~> 1.2) - open-uri (< 1.0) - rexml (~> 3.0) - set (~> 1.1) - singleton (< 1.0) - time (< 1.0) - csl-styles (2.0.2) - csl (~> 2.0) - css_parser (1.21.1) - addressable - cssminify2 (2.1.0) - csv (3.3.5) - date (3.5.1) - deep_merge (1.2.2) - drb (2.2.3) - em-websocket (0.5.3) - eventmachine (>= 0.12.9) - http_parser.rb (~> 0) - eventmachine (1.2.7) - execjs (2.10.0) - fast-stemmer (1.0.2) - feedjira (4.0.1) - logger (>= 1.0, < 2) - loofah (>= 2.3.1, < 3) - sax-machine (>= 1.0, < 2) - ffi (1.17.3-aarch64-linux-gnu) - ffi (1.17.3-aarch64-linux-musl) - ffi (1.17.3-arm-linux-gnu) - ffi (1.17.3-arm-linux-musl) - ffi (1.17.3-arm64-darwin) - ffi (1.17.3-x86_64-darwin) - ffi (1.17.3-x86_64-linux-gnu) - ffi (1.17.3-x86_64-linux-musl) - forwardable (1.4.0) - forwardable-extended (2.6.0) - gemoji (4.1.0) - google-protobuf (4.33.4) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-aarch64-linux-gnu) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-aarch64-linux-musl) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-arm64-darwin) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-x86_64-darwin) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-x86_64-linux-gnu) - bigdecimal - rake (>= 13) - google-protobuf (4.33.4-x86_64-linux-musl) - bigdecimal - rake (>= 13) - html-pipeline (2.14.3) - activesupport (>= 2) - nokogiri (>= 1.4) - htmlcompressor (0.4.0) - http_parser.rb (0.8.1) - httparty (0.24.2) - csv - mini_mime (>= 1.0.0) - multi_xml (>= 0.5.2) - i18n (1.14.8) - concurrent-ruby (~> 1.0) - jekyll-3rd-party-libraries (0.0.1) - css_parser (>= 1.6, < 2.0) - jekyll (>= 3.6, < 5.0) - nokogiri (>= 1.8, < 2.0) - jekyll (4.4.1) - addressable (~> 2.4) - base64 (~> 0.2) - colorator (~> 1.0) - csv (~> 3.0) - em-websocket (~> 0.5) - i18n (~> 1.0) - jekyll-sass-converter (>= 2.0, < 4.0) - jekyll-watch (~> 2.0) - json (~> 2.6) - kramdown (~> 2.3, >= 2.3.1) - kramdown-parser-gfm (~> 1.0) - liquid (~> 4.0) - mercenary (~> 0.3, >= 0.3.6) - pathutil (~> 0.9) - rouge (>= 3.0, < 5.0) - safe_yaml (~> 1.0) - terminal-table (>= 1.8, < 4.0) - webrick (~> 1.7) - jekyll-archives-v2 (0.0.7) - activesupport - jekyll (>= 3.6, < 5.0) - jekyll-cache-bust (0.0.1) - jekyll (>= 3.6, < 5.0) - jekyll-email-protect (1.1.0) - jekyll-feed (0.17.0) - jekyll (>= 3.7, < 5.0) - jekyll-get-json (1.0.0) - deep_merge (~> 1.2) - jekyll (>= 3.0) - jekyll-imagemagick (1.4.0) - jekyll (>= 3.4) - jekyll-jupyter-notebook (0.0.6) - jekyll - jekyll-link-attributes (1.0.1) - jekyll-minifier (0.2.2) - cssminify2 (~> 2.1.0) - htmlcompressor (~> 0.4) - jekyll (~> 4.0) - json-minify (~> 0.0.3) - terser (~> 1.2.3) - jekyll-paginate-v2 (3.0.0) - jekyll (>= 3.0, < 5.0) - jekyll-regex-replace (1.1.0) - jekyll-sass-converter (3.1.0) - sass-embedded (~> 1.75) - jekyll-scholar (7.3.0) - bibtex-ruby (~> 6.0) - citeproc-ruby (>= 2.1.6) - csl-styles (~> 2.0) - jekyll (~> 4.0) - jekyll-sitemap (1.4.0) - jekyll (>= 3.7, < 5.0) - jekyll-socials (0.0.6) - jekyll (>= 3.6, < 5.0) - jekyll-tabs (1.2.1) - jekyll (>= 3.0, < 5.0) - jekyll-toc (0.19.0) - jekyll (>= 3.9) - nokogiri (~> 1.12) - jekyll-twitter-plugin (2.1.0) - jekyll-watch (2.2.1) - listen (~> 3.0) - jemoji (0.13.0) - gemoji (>= 3, < 5) - html-pipeline (~> 2.2) - jekyll (>= 3.0, < 5.0) - json (2.18.0) - json-minify (0.0.3) - json (> 0) - kramdown (2.5.2) - rexml (>= 3.4.4) - kramdown-parser-gfm (1.1.0) - kramdown (~> 2.0) - latex-decode (0.4.2) - liquid (4.0.4) - listen (3.10.0) - logger - rb-fsevent (~> 0.10, >= 0.10.3) - rb-inotify (~> 0.9, >= 0.9.10) - logger (1.7.0) - loofah (2.25.0) - crass (~> 1.0.2) - nokogiri (>= 1.12.0) - matrix (0.4.3) - mercenary (0.4.0) - mini_mime (1.1.5) - minitest (6.0.1) - prism (~> 1.5) - multi_xml (0.8.1) - bigdecimal (>= 3.1, < 5) - namae (1.2.0) - racc (~> 1.7) - nokogiri (1.19.0-aarch64-linux-gnu) - racc (~> 1.4) - nokogiri (1.19.0-aarch64-linux-musl) - racc (~> 1.4) - nokogiri (1.19.0-arm-linux-gnu) - racc (~> 1.4) - nokogiri (1.19.0-arm-linux-musl) - racc (~> 1.4) - nokogiri (1.19.0-arm64-darwin) - racc (~> 1.4) - nokogiri (1.19.0-x86_64-darwin) - racc (~> 1.4) - nokogiri (1.19.0-x86_64-linux-gnu) - racc (~> 1.4) - nokogiri (1.19.0-x86_64-linux-musl) - racc (~> 1.4) - observer (0.1.2) - open-uri (0.5.0) - stringio - time - uri - ostruct (0.6.3) - pathutil (0.16.2) - forwardable-extended (~> 2.6) - prism (1.8.0) - public_suffix (7.0.2) - racc (1.8.1) - rake (13.3.1) - rb-fsevent (0.11.2) - rb-inotify (0.11.1) - ffi (~> 1.0) - rexml (3.4.4) - rouge (4.7.0) - safe_yaml (1.0.5) - sass-embedded (1.97.2-aarch64-linux-gnu) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-aarch64-linux-musl) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-arm-linux-gnueabihf) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-arm-linux-musleabihf) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-arm64-darwin) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-x86_64-darwin) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-x86_64-linux-gnu) - google-protobuf (~> 4.31) - sass-embedded (1.97.2-x86_64-linux-musl) - google-protobuf (~> 4.31) - sax-machine (1.3.2) - securerandom (0.4.1) - set (1.1.2) - singleton (0.3.0) - stringio (3.2.0) - terminal-table (3.0.2) - unicode-display_width (>= 1.1.1, < 3) - terser (1.2.6) - execjs (>= 0.3.0, < 3) - time (0.4.2) - date - tzinfo (2.0.6) - concurrent-ruby (~> 1.0) - unicode-display_width (2.6.0) - uri (1.1.1) - webrick (1.9.2) - -PLATFORMS - aarch64-linux - aarch64-linux-gnu - aarch64-linux-musl - arm-linux-gnu - arm-linux-gnueabihf - arm-linux-musl - arm-linux-musleabihf - arm64-darwin - x86_64-darwin - x86_64-linux - x86_64-linux-gnu - x86_64-linux-musl - -DEPENDENCIES - classifier-reborn - css_parser - feedjira - httparty - jekyll - jekyll-3rd-party-libraries - jekyll-archives-v2 - jekyll-cache-bust - jekyll-email-protect - jekyll-feed - jekyll-get-json - jekyll-imagemagick - jekyll-jupyter-notebook - jekyll-link-attributes - jekyll-minifier - jekyll-paginate-v2 - jekyll-regex-replace - jekyll-scholar - jekyll-sitemap - jekyll-socials - jekyll-tabs - jekyll-terser! - jekyll-toc - jekyll-twitter-plugin - jemoji - observer - ostruct - -BUNDLED WITH - 4.0.4 diff --git a/INSTALL.md b/INSTALL.md index 181b7761b0297..65b84c5d8f6ed 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -85,7 +85,9 @@ Note that when you run it for the first time, it will download a docker image of Now, feel free to customize the theme however you like (don't forget to change the name!). Also, your changes should be automatically rendered in real-time (or maybe after a few seconds). -> Beta: You can also use the slimmed docker image with a size below 100MBs and exact same functionality. Just use `docker compose -f docker-compose-slim.yml up` +For v1.x, Docker serves from a container-local destination (`/tmp/_site`) to avoid host bind-mount write deadlocks during notebook and asset generation. + +> Beta: You can also try the slimmed docker image with `docker compose -f docker-compose-slim.yml up`, but it may lag behind the full image on some host architectures. ### Build your own docker image @@ -140,15 +142,30 @@ For example, when you open the repository with Visual Studio Code (VSCode), it p For a hands-on walkthrough of running al-folio locally without using Docker, check out [this cool blog post](https://george-gca.github.io/blog/2022/running-local-al-folio/) by one of the community members! -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`_). ```bash bundle install -# assuming pip is your Python package manager -pip install jupyter +# optional but recommended if you use jupyter posts: +# installs jupyter + nbconvert for jekyll-jupyter-notebook +./bin/setup-python-deps +# or manually: +# python3 -m pip install --user --break-system-packages jupyter nbconvert bundle exec jekyll serve ``` +In `v1.x`, `al-folio` is a thin starter. Do not run starter-local npm build commands for theme/runtime assets; those are owned by `al-*` gems and loaded through plugin contracts. +Interactive TOC (`toc.sidebar`) and TikZ (`tikzjax: true`) use pinned CDN runtime assets from `_config.yml` (`third_party_libraries.tocbot` and `third_party_libraries.tikzjax`), not install-time downloads. + +Starter plugin wiring lives in: + +- [Gemfile](Gemfile) for dependency declarations +- [\_config.yml](_config.yml) for Jekyll plugin activation/config + +`al-folio` starter does not currently use a gemspec; contributor/plugin integration docs should reference the two files above. + +If `jekyll-jupyter-notebook` is enabled and `jupyter-nbconvert` is missing, builds continue but notebook rendering is skipped with a warning. + 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. ## Deployment @@ -280,17 +297,46 @@ bundle update --all ## Upgrading from a previous version -If you installed **al-folio** as described above, you can manually update your code by following the steps below: +Starting with `v1.0`, **al-folio** ships an upgrade CLI (`al_folio_upgrade`) and versioned migration manifests from `al_folio_core` to make minor upgrades (`v1.0 -> v1.1 -> v1.2`) predictable. + +### Recommended workflow (v1.x) ```bash -# Assuming the current directory is -git remote add upstream https://github.com/alshedivat/al-folio.git -git fetch upstream -git rebase v0.16.3 +# 1) Update dependencies +bundle update + +# 2) Audit your site for breaking/deprecated patterns +bundle exec al-folio upgrade audit + +# 3) Apply deterministic codemods (optional) +bundle exec al-folio upgrade apply --safe + +# 4) Generate a report for manual follow-up +bundle exec al-folio upgrade report ``` -If you have extensively customized a previous version, it might be trickier to upgrade. -You can still follow the steps above, but `git rebase` may result in merge conflicts that must be resolved. -See [git rebase manual](https://help.github.com/en/github/using-git/about-git-rebase) and how to [resolve conflicts](https://help.github.com/en/github/using-git/resolving-merge-conflicts-after-a-git-rebase) for more information. -If rebasing is too complicated, we recommend re-installing the new version of the theme from scratch and port over your content and changes from the previous version manually. You can use tools like [meld](https://meldmerge.org/) -or [winmerge](https://winmerge.org/) to help in this process. +`al-folio` starter is intentionally thin in `v1.x`: layouts/includes/core assets are provided by `al_folio_core`, so regular upgrades do not require rebuilding Tailwind in the starter repo. + +The report is written to `al-folio-upgrade-report.md` and classifies findings as: + +- **Blocking**: must be resolved before the target upgrade is considered complete +- **Non-blocking**: deprecated patterns that should be migrated over time + +### Legacy Bootstrap content + +`v1.0` is Tailwind-first. If your content still relies on Bootstrap-marked classes/behaviors: + +1. Enable `al_folio.compat.bootstrap.enabled: true` in `_config.yml` +2. Ensure `al_folio_bootstrap_compat` is in your plugins/dependencies +3. Complete migration gradually +4. Disable compatibility mode before `v1.3` (compat is supported through `v1.2`, deprecated in `v1.3`, removed in `v2.0`) + +### Older pre-v1 installs + +For heavily customized pre-v1 repositories, you can still use rebase/cherry-pick workflows if needed, but the recommended path is: + +1. Upgrade dependencies +2. Run the upgrade audit/codemods +3. Fix blocking findings from `al-folio-upgrade-report.md` + +For ownership boundaries (starter vs gem runtime/tests), see [`BOUNDARIES.md`](BOUNDARIES.md). diff --git a/README.md b/README.md index c9e178076fd9b..a87b7dbfd4053 100644 --- a/README.md +++ b/README.md @@ -312,6 +312,21 @@ For installation and deployment details please refer to [INSTALL.md](INSTALL.md) For customization details please refer to [CUSTOMIZE.md](CUSTOMIZE.md). +## Plugin Ecosystem + +`al-folio` is a thin starter in `v1.x`. Runtime features are plugin-owned. + +- Ownership boundaries: [BOUNDARIES.md](BOUNDARIES.md) +- Plugin catalog metadata: [`_data/featured_plugins.yml`](_data/featured_plugins.yml) +- Plugin catalog page source: [`_pages/plugins.md`](_pages/plugins.md) + +Naming convention: + +- Theme-coupled plugins use `al-folio-` repos and `al_folio_` gem/plugin ids. +- Reusable plugins can use `al-` or neutral naming. + +Featured plugins and bundled starter plugins are different tracks. Bundling requires explicit updates to [Gemfile](Gemfile) and [\_config.yml](_config.yml). + ## GitHub Copilot Agents This repository includes two specialized GitHub Copilot agents to enhance your development experience: @@ -351,6 +366,7 @@ Comprehensive guides for all aspects of your al-folio website: - **[FAQ](FAQ.md)** – Frequently asked questions and solutions - **[Analytics](ANALYTICS.md)** – Add website analytics and visitor tracking - **[SEO Guide](SEO.md)** – Optimize for search engines and improve discoverability +- **[Plugin Catalog](_pages/plugins.md)** – Featured and bundled plugin metadata ## Features @@ -426,7 +442,7 @@ For more details on how to create distill-styled posts using `` tags, pleas #### Photos, Audio, Video and more -Photo formatting is made simple using [Bootstrap's grid system](https://getbootstrap.com/docs/4.4/layout/grid/). Easily create beautiful grids within your blog posts and project pages, also with support for [video](https://alshedivat.github.io/al-folio/blog/2023/videos/) and [audio](https://alshedivat.github.io/al-folio/blog/2023/audios/) embeds: +Photo formatting is made simple using Tailwind-first responsive layout utilities. Easily create beautiful grids within your blog posts and project pages, also with support for [video](https://alshedivat.github.io/al-folio/blog/2023/videos/) and [audio](https://alshedivat.github.io/al-folio/blog/2023/audios/) embeds:

@@ -492,7 +508,7 @@ We decided to keep `Axe` runs manual because fixing the issues are not straightf #### GDPR Cookie Consent Dialog -**al-folio** includes a built-in, GDPR-compliant cookie consent dialog to ensure your website respects visitor privacy. The dialog is powered by [Vanilla Cookie Consent](https://cookieconsent.orestbida.com/) and integrates seamlessly with all supported analytics providers. +**al-folio** includes a GDPR-compliant cookie consent dialog provided by the `al_cookie` plugin to ensure your website respects visitor privacy. The dialog is powered by [Vanilla Cookie Consent](https://cookieconsent.orestbida.com/) and integrates seamlessly with all supported analytics providers. When enabled, analytics scripts are blocked until the user explicitly consents, and user preferences are saved across visits. This is essential for websites serving visitors in the European Union and other regions with strict privacy regulations. diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md index 96800a388f56a..729297e8ed62f 100644 --- a/TROUBLESHOOTING.md +++ b/TROUBLESHOOTING.md @@ -266,7 +266,7 @@ docker compose run --rm web jekyll build 2>&1 | grep -i bibtex 1. **Correct path format:** ```markdown - ![Alt text](assets/img/image-name.jpg) + ![Alt text](assets/img/1.jpg) ``` 2. **Check the file exists:** diff --git a/_config.yml b/_config.yml index a7a9de03293a6..dc8177519c652 100644 --- a/_config.yml +++ b/_config.yml @@ -43,6 +43,36 @@ external_services: github_readme_stats_url: https://github-readme-stats.vercel.app github_profile_trophy_url: https://github-profile-trophy.vercel.app +# ----------------------------------------------------------------------------- +# al-folio API (v1.x) +# ----------------------------------------------------------------------------- + +al_folio: + api_version: 1 + style_engine: tailwind + tailwind: + version: 4.1.18 + preflight: false + css_entry: assets/tailwind/app.css + distill: + engine: distillpub-template + source: al-org-dev/distill-template#al-folio + allow_remote_loader: true + features: + cv: + enabled: true + distill: + enabled: true + compat: + bootstrap: + enabled: false + support_window: v1.0-v1.2 + deprecates_in: v1.3 + removed_in: v2.0 + upgrade: + channel: stable + auto_apply_safe_fixes: false + # ----------------------------------------------------------------------------- # RSS Feed # ----------------------------------------------------------------------------- @@ -76,12 +106,13 @@ og_image: # The site-wide (default for all links) Open Graph preview image # Analytics and search engine verification # ----------------------------------------------------------------------------- -# For Google Analytics, see https://support.google.com/analytics/answer/10447272?hl=en&ref_topic=14088998&sjid=5129943941510317771-SA#zippy=%2Cgoogle-sites -# and follow the instructions for Google Sites. You will need to create a Google Analytics property and copy the Google tag ID. -google_analytics: # your Google Analytics measurement ID (format: G-XXXXXXXXXX) -cronitor_analytics: # cronitor RUM analytics site ID (format: XXXXXXXXX) -pirsch_analytics: # your Pirsch analytics site ID (length 32 characters) -openpanel_analytics: # your Openpanel analytics client ID (format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) +analytics: + # For Google Analytics, see https://support.google.com/analytics/answer/10447272?hl=en&ref_topic=14088998&sjid=5129943941510317771-SA#zippy=%2Cgoogle-sites + # and follow the instructions for Google Sites. You will need to create a Google Analytics property and copy the Google tag ID. + google: # your Google Analytics measurement ID (format: G-XXXXXXXXXX) + cronitor: # cronitor RUM analytics site ID (format: XXXXXXXXX) + pirsch: # your Pirsch analytics site ID (length 32 characters) + openpanel: # your Openpanel analytics client ID (format: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX) # For Google Search Console, see https://support.google.com/webmasters/answer/9008080?hl=en#meta_tag_verification&zippy=%2Chtml-tag google_site_verification: # your google-site-verification ID (Google Search Console) @@ -183,7 +214,7 @@ kramdown: start_line: 1 # Includes & excludes -include: ["_pages", "_scripts"] +include: ["_pages"] exclude: - bin/ - CONTRIBUTING.md @@ -203,11 +234,16 @@ exclude: - purgecss.config.js - README.md - readme_preview/ + - gems/ + - migrations/ - vendor keep_files: - CNAME - .nojekyll +# Use al_folio_core as the theme runtime; local files can still override theme files. +theme: al_folio_core + # Plug-ins plugins: - jekyll-3rd-party-libraries @@ -231,6 +267,24 @@ plugins: - jekyll-twitter-plugin - jemoji + # al-folio plugins + - al_folio_core + - al_icons + - al_folio_cv + - al_folio_distill + - al_folio_upgrade + - al_folio_bootstrap_compat + - al_cookie + - al_analytics + - al_citations + - al_ext_posts + - al_img_tools + - al_search + - al_charts + - al_math + - al_comments + - al_newsletter + # Sitemap settings defaults: - scope: @@ -395,10 +449,6 @@ lazy_loading_images: true # enables lazy loading of images (recommended) # Optional Features # ----------------------------------------------------------------------------- -enable_google_analytics: false # enables google analytics -enable_cronitor_analytics: false # enables cronitor RUM analytics -enable_pirsch_analytics: false # enables Pirsch analytics (https://pirsch.io/) -enable_openpanel_analytics: false # enables Openpanel analytics (https://openpanel.dev/) enable_google_verification: false # enables google site verification enable_bing_verification: false # enables bing site verification enable_cookie_consent: false # enables GDPR-compliant cookie consent dialog (https://github.com/orestbida/cookieconsent) @@ -429,6 +479,18 @@ third_party_libraries: css: "https://cdn.jsdelivr.net/npm/bootstrap-table@{{version}}/dist/bootstrap-table.min.css" js: "https://cdn.jsdelivr.net/npm/bootstrap-table@{{version}}/dist/bootstrap-table.min.js" version: "1.22.4" + fontawesome: + integrity: + css: "sha256-MVopmdyC2tYTiJ8wlktf0uh0v4NgT+vNdyVFepi7Q0c=" + url: + css: "https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@{{version}}/css/all.min.css" + version: "7.2.0" + academicons: + integrity: + css: "sha256-SzrCOBJbGVFMahewkgjwnApaV2+av1DwMAA+/QGLyZw=" + url: + css: "https://cdn.jsdelivr.net/npm/academicons@{{version}}/css/academicons.min.css" + version: "1.9.5" chartjs: integrity: js: "sha256-0q+JdOlScWOHcunpUk21uab1jW7C1deBQARHtKMcaB4=" @@ -476,18 +538,8 @@ third_party_libraries: integrity: js: "sha256-htrLFfZJ6v5udOG+3kNLINIKh2gvoKqwEhHYfTTMICc=" url: - js: https://cdn.jsdelivr.net/npm/imagesloaded@{{version}}/imagesloaded.pkgd.min.js + js: "https://cdn.jsdelivr.net/npm/imagesloaded@{{version}}/imagesloaded.pkgd.min.js" version: "5.0.0" - img-comparison-slider: - integrity: - css: "sha256-3qTIuuUWIFnnU3LpQMjqiXc0p09rvd0dmj+WkpQXSR8=" - js: "sha256-EXHg3x1K4oIWdyohPeKX2ZS++Wxt/FRPH7Nl01nat1o=" - map: "sha256-3wfqS2WU5kGA/ePcgFzJXl5oSN1QsgZI4/edprTgX8w=" - url: - css: "https://cdn.jsdelivr.net/npm/img-comparison-slider@{{version}}/dist/styles.min.css" - js: "https://cdn.jsdelivr.net/npm/img-comparison-slider@{{version}}/dist/index.min.js" - map: "https://cdn.jsdelivr.net/npm/img-comparison-slider@{{version}}/dist/index.js.map" - version: "8.0.6" jquery: integrity: js: "sha256-/xUj+3OJU5yExlq6GSYGSHk7tPXikynS7ogEvDej/m4=" @@ -507,23 +559,6 @@ third_party_libraries: js: "https://cdn.jsdelivr.net/npm/leaflet@{{version}}/dist/leaflet.min.js" js_map: "https://cdn.jsdelivr.net/npm/leaflet@{{version}}/dist/leaflet.js.map" version: "1.9.4" - lightbox2: - integrity: - css: "sha256-uypRbsAiJcFInM/ndyI/JHpzNe6DtUNXaWEUWEPfMGo=" - js: "sha256-A6jI5V9s1JznkWwsBaRK8kSeXLgIqQfxfnvdDOZEURY=" - url: - css: "https://cdn.jsdelivr.net/npm/lightbox2@{{version}}/dist/css/lightbox.min.css" - js: "https://cdn.jsdelivr.net/npm/lightbox2@{{version}}/dist/js/lightbox.min.js" - version: "2.11.5" - mathjax: - integrity: - js: "sha256-MASABpB4tYktI2Oitl4t+78w/lyA+D7b/s9GEP0JOGI=" - local: - fonts: "output/chtml/fonts/woff-v2/" - url: - fonts: "https://cdn.jsdelivr.net/npm/mathjax@{{version}}/es5/output/chtml/fonts/woff-v2/" - js: "https://cdn.jsdelivr.net/npm/mathjax@{{version}}/es5/tex-mml-chtml.js" - version: "3.2.2" masonry: integrity: js: "sha256-Nn1q/fx0H7SNLZMQ5Hw5JLaTRZp0yILA/FRexe19VdI=" @@ -542,31 +577,37 @@ third_party_libraries: js: "https://cdn.jsdelivr.net/npm/mdbootstrap@{{version}}/js/mdb.min.js" js_map: "https://cdn.jsdelivr.net/npm/mdbootstrap@{{version}}/js/mdb.min.js.map" version: "4.20.0" - medium_zoom: - integrity: - js: "sha256-ZgMyDAIYDYGxbcpJcfUnYwNevG/xi9OHKaR/8GK+jWc=" - url: - js: "https://cdn.jsdelivr.net/npm/medium-zoom@{{version}}/dist/medium-zoom.min.js" - version: "1.1.0" mermaid: integrity: js: "sha256-TtLOdUA8mstPoO6sGvHIGx2ceXrrX4KgIItO06XOn8A=" url: js: "https://cdn.jsdelivr.net/npm/mermaid@{{version}}/dist/mermaid.min.js" version: "10.7.0" - photoswipe: + mathjax: + integrity: + js: "sha256-MASABpB4tYktI2Oitl4t+78w/lyA+D7b/s9GEP0JOGI=" + local: + fonts: "output/chtml/fonts/woff-v2/" + url: + fonts: "https://cdn.jsdelivr.net/npm/mathjax@{{version}}/es5/output/chtml/fonts/woff-v2/" + js: "https://cdn.jsdelivr.net/npm/mathjax@{{version}}/es5/tex-mml-chtml.js" + version: "3.2.2" + tikzjax: integrity: - js: "sha256-VCBpdxvrNNxGHNuTdNqK9kPFkev2XY7DYzHdmgaB69Q=" + css: "sha256-p+CQrhSq3dnLHELDcVBFDf4whOor3w8gzLuc/pwRLyQ=" + js: "sha256-7SCmUR11IG4MkSoeLUq0pombv7oeV7yZuu7Z82e4Uy4=" url: - css: "https://cdn.jsdelivr.net/npm/photoswipe@{{version}}/dist/photoswipe.min.css" - js: "https://cdn.jsdelivr.net/npm/photoswipe@{{version}}/dist/photoswipe.esm.min.js" - version: "5.4.4" - photoswipe-lightbox: + css: "https://cdn.jsdelivr.net/npm/@planktimerr/tikzjax@{{version}}/dist/fonts.css" + js: "https://cdn.jsdelivr.net/npm/@planktimerr/tikzjax@{{version}}/dist/tikzjax.js" + version: "1.0.8" + tocbot: integrity: - js: "sha256-uCw4VgT5DMdwgtjhvU9e98nT2mLZXcw/8WkaTrDd3RI=" + css: "sha256-zTN0r+0OKaIv2xqeNNIYxNk0pWJ6+IqPGc1iDgVzWF0=" + js: "sha256-lo/r+jQ81wWrxdIiiiEEd538z4+dTJTt+leOuAS7GCw=" url: - js: "https://cdn.jsdelivr.net/npm/photoswipe@{{version}}/dist/photoswipe-lightbox.esm.min.js" - version: "5.4.4" + css: "https://cdn.jsdelivr.net/npm/tocbot@{{version}}/dist/tocbot.css" + js: "https://cdn.jsdelivr.net/npm/tocbot@{{version}}/dist/tocbot.min.js" + version: "4.36.4" plotly: integrity: js: "sha256-oy6Be7Eh6eiQFs5M7oXuPxxm9qbJXEtTpfSI93dW16Q=" @@ -585,29 +626,18 @@ third_party_libraries: css: "https://cdn.jsdelivr.net/npm/pseudocode@{{version}}/build/pseudocode.min.css" js: "https://cdn.jsdelivr.net/npm/pseudocode@{{version}}/build/pseudocode.min.js" version: "2.4.1" - spotlight: + scholar-icons: integrity: - css: "sha256-Dsvkx8BU8ntk9Iv+4sCkgHRynYSQQFP6gJfBN5STFLY=" + css: "sha256-VY3hHVj/hNX3fYG6wtbA6TcKJQl7+FthzGSyIB64klY=" url: - css: "https://cdn.jsdelivr.net/npm/spotlight.js@{{version}}/dist/css/spotlight.min.css" - js: "https://cdn.jsdelivr.net/npm/spotlight.js@{{version}}/dist/spotlight.bundle.min.js" - version: "0.7.8" - swiper: + css: "https://cdn.jsdelivr.net/npm/scholar-icons@{{version}}/css/scholar-icons.css" + version: "1.0.3" + vanilla-back-to-top: integrity: - css: "sha256-yUoNxsvX+Vo8Trj3lZ/Y5ZBf8HlBFsB6Xwm7rH75/9E=" - js: "sha256-BPrwikijIybg9OQC5SYFFqhBjERYOn97tCureFgYH1E=" - map: "sha256-lbF5CsospW93otqvWOIbbhj80CjazrZXvamD7nC7TBI=" + js: "sha256-uMJJ3EoTyfRBoTbR+lrfu1uRQ87RZG8AR3cVNuQVeFg=" url: - css: "https://cdn.jsdelivr.net/npm/swiper@{{version}}/swiper-bundle.min.css" - js: "https://cdn.jsdelivr.net/npm/swiper@{{version}}/swiper-element-bundle.min.js" - map: "https://cdn.jsdelivr.net/npm/swiper@{{version}}/swiper-element-bundle.min.js.map" - version: "11.0.5" - swiper-map: - integrity: - js: "sha256-hlZaH8ySXX97bZaetnrtYlKuhx3oEXFz/s2IXchu6vk=" - url: - js: "https://cdn.jsdelivr.net/npm/swiper@11.1.0/swiper-element-bundle.min.js.map" - version: "11.0.5" + js: "https://cdn.jsdelivr.net/npm/vanilla-back-to-top@{{version}}/dist/vanilla-back-to-top.min.js" + version: "7.2.1" vanilla-cookieconsent: integrity: css: "sha256-ygRrixsQlBByBZiOcJamh7JByO9fP+/l5UPtKNJmRsE=" @@ -640,14 +670,6 @@ third_party_libraries: js: "https://cdn.jsdelivr.net/npm/vega-lite@{{version}}/build/vega-lite.min.js" js_map: "https://cdn.jsdelivr.net/npm/vega-lite@{{version}}/build/vega-lite.min.js.map" version: "5.16.3" - venobox: - integrity: - css: "sha256-ohJEB0/WsBOdBD+gQO/MGfyJSbTUI8OOLbQGdkxD6Cg=" - js: "sha256-LsGXHsHMMmTcz3KqTaWvLv6ome+7pRiic2LPnzTfiSo=" - url: - css: "https://cdn.jsdelivr.net/npm/venobox@{{version}}/dist/venobox.min.css" - js: "https://cdn.jsdelivr.net/npm/venobox@{{version}}/dist/venobox.min.js" - version: "2.1.8" # ----------------------------------------------------------------------------- # Get external JSON data diff --git a/_data/featured_plugins.yml b/_data/featured_plugins.yml new file mode 100644 index 0000000000000..3f745183f8f7d --- /dev/null +++ b/_data/featured_plugins.yml @@ -0,0 +1,223 @@ +- name: al_folio_core + repo_url: https://github.com/al-org-dev/al-folio-core + gem_name: al_folio_core + jekyll_plugin_id: al_folio_core + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /about/ + maintainer_contact: https://github.com/al-org-dev + notes: Core runtime primitives and starter contracts. + +- name: al_folio_distill + repo_url: https://github.com/al-org-dev/al-folio-distill + gem_name: al_folio_distill + jekyll_plugin_id: al_folio_distill + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /blog/2018/distill/ + maintainer_contact: https://github.com/al-org-dev + notes: Distill layout/runtime ownership. + +- name: al_folio_cv + repo_url: https://github.com/al-org-dev/al-folio-cv + gem_name: al_folio_cv + jekyll_plugin_id: al_folio_cv + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /cv/ + maintainer_contact: https://github.com/al-org-dev + notes: CV layouts, includes, and rendering behavior. + +- name: al_folio_upgrade + repo_url: https://github.com/al-org-dev/al-folio-upgrade + gem_name: al_folio_upgrade + jekyll_plugin_id: al_folio_upgrade + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: / + maintainer_contact: https://github.com/al-org-dev + notes: Upgrade audit/codemod/report CLI. + +- name: al_folio_bootstrap_compat + repo_url: https://github.com/al-org-dev/al-folio-bootstrap-compat + gem_name: al_folio_bootstrap_compat + jekyll_plugin_id: al_folio_bootstrap_compat + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.2.x" + status: bundled + demo_path: /blog/2023/tables/ + maintainer_contact: https://github.com/al-org-dev + notes: Transitional compatibility for legacy Bootstrap-marked content. + +- name: al_icons + repo_url: https://github.com/al-org-dev/al-icons + gem_name: al_icons + jekyll_plugin_id: al_icons + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /about/ + maintainer_contact: https://github.com/al-org-dev + notes: Icon runtime loading (Font Awesome, Academicons, Scholar Icons). + +- name: al_cookie + repo_url: https://github.com/al-org-dev/al-cookie + gem_name: al_cookie + jekyll_plugin_id: al_cookie + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: / + maintainer_contact: https://github.com/al-org-dev + notes: Cookie consent runtime and consent-aware analytics gating. + +- name: al_search + repo_url: https://github.com/al-org-dev/al-search + gem_name: al_search + jekyll_plugin_id: al_search + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: / + maintainer_contact: https://github.com/al-org-dev + notes: Search runtime payload and keyboard/modal setup. + +- name: al_img_tools + repo_url: https://github.com/al-org-dev/al-img-tools + gem_name: al_img_tools + jekyll_plugin_id: al_img_tools + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /blog/2024/photo-gallery/ + maintainer_contact: https://github.com/al-org-dev + notes: Image tooling, gallery, and lightbox behavior. + +- name: al_math + repo_url: https://github.com/al-org-dev/al-math + gem_name: al_math + jekyll_plugin_id: al_math + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /blog/2023/tikzjax/ + maintainer_contact: https://github.com/al-org-dev + notes: Math and TikZ runtime integration. + +- name: al_analytics + repo_url: https://github.com/al-org-dev/al-analytics + gem_name: al_analytics + jekyll_plugin_id: al_analytics + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: / + maintainer_contact: https://github.com/al-org-dev + notes: Analytics provider runtime integration. + +- name: al_citations + repo_url: https://github.com/al-org-dev/al-citations + gem_name: al_citations + jekyll_plugin_id: al_citations + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /publications/ + maintainer_contact: https://github.com/al-org-dev + notes: Bibliography rendering and publication runtime behavior. + +- name: al_ext_posts + repo_url: https://github.com/al-org-dev/al-ext-posts + gem_name: al_ext_posts + jekyll_plugin_id: al_ext_posts + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /blog/ + maintainer_contact: https://github.com/al-org-dev + notes: External posts ingestion helpers. + +- name: al_charts + repo_url: https://github.com/al-org-dev/al-charts + gem_name: al_charts + jekyll_plugin_id: al_charts + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /blog/2023/charts/ + maintainer_contact: https://github.com/al-org-dev + notes: Chart runtime integrations. + +- name: al_comments + repo_url: https://github.com/al-org-dev/al-comments + gem_name: al_comments + jekyll_plugin_id: al_comments + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: /blog/ + maintainer_contact: https://github.com/al-org-dev + notes: Comments providers and comment runtime glue. + +- name: al_newsletter + repo_url: https://github.com/al-org-dev/al-newsletter + gem_name: al_newsletter + jekyll_plugin_id: al_newsletter + owner: al-org-dev + license: See plugin repo LICENSE + compat: + al_folio_min: "1.0.0" + al_folio_max: "1.x" + status: bundled + demo_path: / + maintainer_contact: https://github.com/al-org-dev + notes: Newsletter runtime integration. diff --git a/_includes/audio.liquid b/_includes/audio.liquid deleted file mode 100644 index 338e2124985dc..0000000000000 --- a/_includes/audio.liquid +++ /dev/null @@ -1,30 +0,0 @@ -

-
diff --git a/_includes/bib_search.liquid b/_includes/bib_search.liquid deleted file mode 100644 index c0ab526c652b8..0000000000000 --- a/_includes/bib_search.liquid +++ /dev/null @@ -1,4 +0,0 @@ -{% if site.bib_search %} - - -{% endif %} diff --git a/_includes/calendar.liquid b/_includes/calendar.liquid deleted file mode 100644 index fab192dd7b98f..0000000000000 --- a/_includes/calendar.liquid +++ /dev/null @@ -1,25 +0,0 @@ -{% if include.calendar_id %} -
-

Upcoming Events

- - - - -
-{% endif %} diff --git a/_includes/citation.liquid b/_includes/citation.liquid deleted file mode 100644 index 35bd9e378d521..0000000000000 --- a/_includes/citation.liquid +++ /dev/null @@ -1,26 +0,0 @@ -
-
-
- -If you found this useful, please cite this as: - -{% capture citation_quote -%} -> {{ site.last_name }}, {{ site.first_name }}{% if site.middle_name %} {{ site.middle_name }}{% endif %} ({{ page.date | date: "%b %Y" }}). {{ page.title }}. {% if site.title != 'blank' %}{{ site.title }}. {% endif %}{{ site.url }}. -{%- endcapture %} -{{ citation_quote | markdownify }} - -

or as a BibTeX entry:

- -{% capture citation_code -%} -```bibtex -@article{ {{- site.last_name | downcase }}{{ page.date | date: "%Y" }}{{ page.title | slugify }}, - title = { {{- page.title -}} }, - author = { {{- site.last_name }}, {{ site.first_name }}{% if site.middle_name %} {{ site.middle_name }}{% endif -%}}, - {%- if site.title != 'blank' %}journal = { {{- site.title -}} },{% endif %} - year = { {{- page.date | date: "%Y" -}} }, - month = { {{- page.date | date: "%b" -}} }, - url = { {{- site.url }}{{ page.url -}} } -} -``` -{%- endcapture %} -{{ citation_code | markdownify }} diff --git a/_includes/course_schedule.liquid b/_includes/course_schedule.liquid deleted file mode 100644 index 363387b6c2ebb..0000000000000 --- a/_includes/course_schedule.liquid +++ /dev/null @@ -1,71 +0,0 @@ -{% assign course = site.teachings | where: 'course_id', include.course_id | first %} - -{% if course %} -
-

{{ course.title }}

- - {% if course.description %} -
- {{ course.description | markdownify }} -
- {% endif %} - - {% if course.instructor %} -

Instructor: {{ course.instructor }}

- {% endif %} - - {% if course.term %} -

Term: {{ course.term }}

- {% endif %} - - {% if course.schedule %} - - - - - - - - - - - {% for entry in course.schedule %} - - - - - - - {% endfor %} - -
WeekDateTopicMaterials
{{ entry.week }}{{ entry.date }} - {% if entry.topic %} - {{ entry.topic }} - {% endif %} - {% if entry.description %} -
{{ entry.description | markdownify }}
- {% endif %} - 		- {% if entry.materials %} -
    - {% for material in entry.materials %} -
  • - {% if material.url %} - {% if material.url contains '://' %} - {{ material.name }} - {% else %} - {{ material.name }} - {% endif %} - {% else %} - {{ material.name }} - {% endif %} -
    • - {% endfor %} -
- {% endif %} -
- {% else %} -

No schedule available for this course.

- {% endif %} -
-{% endif %} diff --git a/_includes/courses.liquid b/_includes/courses.liquid deleted file mode 100644 index 85858d38bf5ab..0000000000000 --- a/_includes/courses.liquid +++ /dev/null @@ -1,37 +0,0 @@ -{% if site.teachings %} -
- {% assign courses_by_year = site.teachings | sort: 'year' | reverse | group_by: 'year' %} - - {% for year_group in courses_by_year %} -

{{ year_group.name }}

-
- {% assign year_courses = year_group.items | sort: 'term' %} - {% for course in year_courses %} -
-

- {{ course.title }} -

- -
- {% if course.term %} - {{ course.term }} - {% endif %} - - {% if course.instructor %} - {{ course.instructor }} - {% endif %} -
- - {% if course.description %} -
- {{ course.description | markdownify }} -
- {% endif %} -
- {% endfor %} -
- {% endfor %} -
-{% else %} -

No courses available yet.

-{% endif %} diff --git a/_includes/cv/awards.liquid b/_includes/cv/awards.liquid deleted file mode 100644 index a57cac51d6ea2..0000000000000 --- a/_includes/cv/awards.liquid +++ /dev/null @@ -1,66 +0,0 @@ -{% comment %} - Unified awards entry renderer for both formats -{% endcomment %} - -
    - {% for entry in entries %} -
  • -
    - {% capture start_date %} - {% if entry.date %}{{ entry.date }}{% endif %} - {% endcapture %} - - {% if start_date != '' %} -
    - - - - - - -
    - - {{- start_date | split: '-' | slice: 0, 1 | join: '' -}} - -
    -
    -
    - {% if entry.url %} -
    - {{ entry.title }} -
    - {% elsif entry.title %} -
    {{ entry.title }}
    - {% endif %} - - {% if entry.awarder %} -
    {{ entry.awarder }}
    - {% endif %} - - {% if entry.summary %} -

    {{ entry.summary | markdownify | remove: '

    ' | remove: '

    ' }}

    - {% endif %} -
    - {% else %} -
    - {% if entry.url %} -
    - {{ entry.title }} -
    - {% elsif entry.title %} -
    {{ entry.title }}
    - {% endif %} - - {% if entry.awarder %} -
    {{ entry.awarder }}
    - {% endif %} - - {% if entry.summary %} -

    {{ entry.summary | markdownify | remove: '

    ' | remove: '

    ' }}

    - {% endif %} -
    - {% endif %} -
    -
    • - {% endfor %} -
diff --git a/_includes/cv/certificates.liquid b/_includes/cv/certificates.liquid deleted file mode 100644 index 05613ebc97ff0..0000000000000 --- a/_includes/cv/certificates.liquid +++ /dev/null @@ -1,28 +0,0 @@ -{% comment %} - Unified certificates entry renderer for both formats -{% endcomment %} - -
    - {% for entry in entries %} -
  • - {% if entry.icon %} - - {% endif %} - {% if entry.url %} - {{ entry.name }} - {% else %} - {{ entry.name }} - {% endif %} - - {% if entry.issuer %} - - {{ entry.issuer }} - {% endif %} - - {% if entry.date %} - ({{ entry.date | split: '-' | slice: 0, 1 | join: '' }}) - {% endif %} -
    • - {% endfor %} -
diff --git a/_includes/cv/education.liquid b/_includes/cv/education.liquid deleted file mode 100644 index 773e74f43976c..0000000000000 --- a/_includes/cv/education.liquid +++ /dev/null @@ -1,93 +0,0 @@ -{% comment %} - Unified education entry renderer for both RenderCV and JSONResume formats - Handles both: - - RenderCV: institution, area, studyType (or degree), start_date, end_date, location, courses, highlights - - JSONResume: institution, area, studyType, startDate, endDate, location, courses, highlights -{% endcomment %} - -
    - {% for entry in entries %} -
  • -
    -
    - {% capture start_date %} - {% if entry.start_date %}{{ entry.start_date }}{% elsif entry.startDate %}{{ entry.startDate }}{% endif %} - {% endcapture %} - {% capture end_date %} - {% if entry.end_date %}{{ entry.end_date }}{% elsif entry.endDate %}{{ entry.endDate }}{% endif %} - {% endcapture %} - - {% if start_date != '' %} - {% comment %} Extract year only from dates like "1933-01-01" or just use "1933" as is {% endcomment %} - {% assign startDate = start_date | split: '-' | first %} - {% assign endDate = end_date | split: '-' | first | default: 'Present' %} - {% assign date = startDate | append: ' - ' | append: endDate %} - {% else %} - {% assign date = null %} - {% endif %} - - - - - - - {% capture location %} - {% if entry.location %}{{ entry.location }}{% endif %} - {% endcapture %} - {% if location != '' %} - - - - {% endif %} - -
    - {% if date %} - {{ date }} - {% endif %} -
    -

    - - {{ location }} -

    -
    -
    -
    - {% capture study_type %} - {% if entry.studyType %}{{ entry.studyType }}{% elsif entry.degree %}{{ entry.degree }}{% endif %} - {% endcapture %} - - {% if entry.url %} -
    - {{ study_type }} -
    - {% elsif study_type != '' %} -
    {{ study_type }}
    - {% endif %} - - {% if entry.institution %} -
    {{ entry.institution }}
    - {% endif %} - - {% if entry.area %} -
    {{ entry.area }}
    - {% endif %} - - {% if entry.courses or entry.highlights %} -
      - {% for item in entry.courses %} -
    • - {{ item }} -
      • - {% endfor %} - {% for item in entry.highlights %} -
    • - {{ item | markdownify | remove: '

      ' | remove: '

      ' }}       -
      • - {% endfor %} -
    - {% endif %} -
    -
    -
    • - {% endfor %} -
diff --git a/_includes/cv/experience.liquid b/_includes/cv/experience.liquid deleted file mode 100644 index 515a39bf67ed3..0000000000000 --- a/_includes/cv/experience.liquid +++ /dev/null @@ -1,91 +0,0 @@ -{% comment %} - Unified work/experience entry renderer for both RenderCV and JSONResume formats - Handles both: - - RenderCV: company, position, start_date, end_date, location, url, summary, highlights - - JSONResume: name, position, startDate, endDate, location, url, summary, highlights -{% endcomment %} - -
    - {% for entry in entries %} -
  • -
    -
    - {% capture start_date %} - {% if entry.start_date %}{{ entry.start_date }}{% elsif entry.startDate %}{{ entry.startDate }}{% endif %} - {% endcapture %} - {% capture end_date %} - {% if entry.end_date %}{{ entry.end_date }}{% elsif entry.endDate %}{{ entry.endDate }}{% endif %} - {% endcapture %} - - {% if start_date != '' %} - {% comment %} Extract year only from dates like "1933-01-01" or just use "1933" as is {% endcomment %} - {% assign startDate = start_date | split: '-' | first %} - {% assign endDate = end_date | split: '-' | first | default: 'Present' %} - {% assign date = startDate | append: ' - ' | append: endDate %} - {% else %} - {% assign date = '' %} - {% endif %} - - - - - - - {% capture location %} - {% if entry.location %}{{ entry.location }}{% endif %} - {% endcapture %} - {% if location != '' %} - - - - {% endif %} - -
    - {{ date }} -
    -

    - - {{ location }} -

    -
    -
    -
    - {% capture position_title %} - {% if entry.position %}{{ entry.position }}{% endif %} - {% endcapture %} - - {% if entry.url %} -
    - {{ position_title }} -
    - {% elsif position_title != '' %} -
    {{ position_title }}
    - {% endif %} - - {% capture company_name %} - {% if entry.name %}{{ entry.name }}{% elsif entry.company %}{{ entry.company }}{% elsif entry.organization %}{{ entry.organization }}{% endif %} - {% endcapture %} - {% if company_name != '' %} -
    {{ company_name }}
    - {% endif %} - - {% if entry.summary %} -
    - {{ entry.summary | markdownify | remove: '

    ' | remove: '

    ' }} -
    - {% endif %} - - {% if entry.highlights %} -
      - {% for item in entry.highlights %} -
    • - {{ item | markdownify | remove: '

      ' | remove: '

      ' }}       -
      • - {% endfor %} -
    - {% endif %} -
    -
    -
    • - {% endfor %} -
diff --git a/_includes/cv/interests.liquid b/_includes/cv/interests.liquid deleted file mode 100644 index f4997a75a8eef..0000000000000 --- a/_includes/cv/interests.liquid +++ /dev/null @@ -1,29 +0,0 @@ -{% comment %} - Unified interests entry renderer for both formats -{% endcomment %} - -
- {% for entry in entries %} -
- {% if entry.icon %} - - {% endif %} - {{ entry.name }}: - {% if entry.keywords %} - {% for keyword in entry.keywords %} - {% if forloop.last %} - {{ keyword }} - {% else %} - {{ keyword }}, - {% endif %} - {% endfor %} - {% endif %} -
- {% endfor %} -
- - diff --git a/_includes/cv/languages.liquid b/_includes/cv/languages.liquid deleted file mode 100644 index 5f58dd1feb5e6..0000000000000 --- a/_includes/cv/languages.liquid +++ /dev/null @@ -1,28 +0,0 @@ -{% comment %} - Unified languages entry renderer for both formats - - RenderCV uses: name, summary - - JSONResume uses: language, fluency -{% endcomment %} - -
- {% for entry in entries %} -
- {% if entry.icon %} - - {% endif %} - {% capture lang_name %} - {% if entry.name %}{{ entry.name }}{% elsif entry.language %}{{ entry.language }}{% endif %} - {% endcapture %} - {% capture fluency %} - {% if entry.summary %}{{ entry.summary }}{% elsif entry.fluency %}{{ entry.fluency }}{% endif %} - {% endcapture %} - {{ lang_name }}: {{ fluency }} -
- {% endfor %} -
- - diff --git a/_includes/cv/projects.liquid b/_includes/cv/projects.liquid deleted file mode 100644 index 7f5dc86d6c69e..0000000000000 --- a/_includes/cv/projects.liquid +++ /dev/null @@ -1,31 +0,0 @@ -{% comment %} - Unified projects entry renderer for both formats -{% endcomment %} - -
    - {% for entry in entries %} -
  • - {% if entry.url %} -
    - {{ entry.name }} -
    - {% else %} -
    {{ entry.name }}
    - {% endif %} - - {% if entry.summary %} -

    {{ entry.summary | markdownify | remove: '

    ' | remove: '

    ' }}

    - {% endif %} - - {% if entry.highlights %} -
      - {% for item in entry.highlights %} -
    • - {{ item | markdownify | remove: '

      ' | remove: '

      ' }}       -
      • - {% endfor %} -
    - {% endif %} -
    • - {% endfor %} -
diff --git a/_includes/cv/publications.liquid b/_includes/cv/publications.liquid deleted file mode 100644 index 22f530adc57b5..0000000000000 --- a/_includes/cv/publications.liquid +++ /dev/null @@ -1,70 +0,0 @@ -{% comment %} - Unified publications entry renderer for both formats -{% endcomment %} - -
    - {% for entry in entries %} -
  • -
    - {% capture pub_date %} - {% if entry.releaseDate %}{{ entry.releaseDate }}{% elsif entry.date %}{{ entry.date }}{% endif %} - {% endcapture %} - - {% if pub_date != '' %} -
    - - - - - - -
    - - {{- pub_date | split: '-' | slice: 0, 1 | join: '' -}} - -
    -
    -
    - {% if entry.url %} -
    - {{ entry.title | default: entry.name }} -
    - {% elsif entry.title %} -
    {{ entry.title }}
    - {% endif %} - - {% if entry.publisher %} -
    - {{ entry.publisher }} -
    - {% endif %} - - {% if entry.summary %} -

    {{ entry.summary | markdownify | remove: '

    ' | remove: '

    ' }}

    - {% endif %} -
    - {% else %} -
    - {% if entry.url %} -
    - {{ entry.title | default: entry.name }} -
    - {% elsif entry.title %} -
    {{ entry.title }}
    - {% endif %} - - {% if entry.publisher %} -
    - {{ entry.publisher }} -
    - {% endif %} - - {% if entry.summary %} -

    {{ entry.summary | markdownify | remove: '

    ' | remove: '

    ' }}

    - {% endif %} -
    - {% endif %} -
    -
    • - {% endfor %} -
diff --git a/_includes/cv/references.liquid b/_includes/cv/references.liquid deleted file mode 100644 index 8fc9456f43b02..0000000000000 --- a/_includes/cv/references.liquid +++ /dev/null @@ -1,15 +0,0 @@ -{% comment %} - Unified references entry renderer for both formats -{% endcomment %} - -
    - {% for entry in entries %} -
  • - {% if entry.icon %} - - {% endif %} - {{ entry.name }} -

    {{ entry.reference | markdownify | remove: '

    ' | remove: '

    ' }}

    -
    • - {% endfor %} -
diff --git a/_includes/cv/skills.liquid b/_includes/cv/skills.liquid deleted file mode 100644 index a35e49b81afec..0000000000000 --- a/_includes/cv/skills.liquid +++ /dev/null @@ -1,32 +0,0 @@ -{% comment %} - Unified skills entry renderer for both formats -{% endcomment %} - -
- {% for entry in entries %} -
- {% if entry.icon %} - - {% endif %} - - {{- entry.name -}} - {%- if entry.level %} ({{ entry.level }}){% endif %}: - {% if entry.keywords %} - {% for keyword in entry.keywords %} - {% if forloop.last %} - {{ keyword }} - {% else %} - {{ keyword }}, - {% endif %} - {% endfor %} - {% endif %} -
- {% endfor %} -
- - diff --git a/_includes/disqus.liquid b/_includes/disqus.liquid deleted file mode 100644 index 2874b42ed7403..0000000000000 --- a/_includes/disqus.liquid +++ /dev/null @@ -1,13 +0,0 @@ -
- - -
diff --git a/_includes/distill_scripts.liquid b/_includes/distill_scripts.liquid deleted file mode 100644 index 24d80d2f18a6d..0000000000000 --- a/_includes/distill_scripts.liquid +++ /dev/null @@ -1,340 +0,0 @@ - - - - - - - - - - -{% if page.mermaid and page.mermaid.enabled %} - - - {% if page.mermaid.zoomable %} - - {% endif %} - -{% endif %} - -{% if page.code_diff %} - - - - -{% endif %} - -{% if page.map %} - - - -{% endif %} - -{% if page.chart and page.chart.chartjs %} - - - -{% endif %} - -{% if page.chart and page.chart.echarts %} - - - {% if site.enable_darkmode %} - - {% endif %} - -{% endif %} - -{% if page.chart and page.chart.plotly %} - - - -{% endif %} - -{% if page.chart and page.chart.vega_lite %} - - - - - -{% endif %} - -{% if page.tikzjax %} - - -{% endif %} - -{% if page.typograms %} - - -{% endif %} - -{% if site.enable_tooltips %} - - -{% endif %} - -{% if site.enable_medium_zoom %} - - - -{% endif %} - -{% if page.toc and page.toc.sidebar %} - - -{% endif %} - -{% if page.pretty_table %} - - - -{% endif %} - - - - - - - - - - - -{% if site.enable_math %} - - - - - -{% endif %} - -{% if site.enable_cookie_consent %} - - - -{% endif %} - -{% if site.enable_google_analytics %} - - - - -{% endif %} - -{% if site.enable_cronitor_analytics %} - - - -{% endif %} -{% if site.enable_pirsch_analytics %} - -{% endif %} -{% if site.enable_openpanel_analytics %} - - -{% endif %} - -{% if site.enable_progressbar %} - - -{% endif %} - -{% if page.images %} - - {% if page.images.compare %} - - {% endif %} - {% if page.images.lightbox2 %} - - {% endif %} - {% if page.images.photoswipe %} - - {% endif %} - {% if page.images.slider %} - - {% endif %} - {% if page.images.spotlight %} - - {% endif %} - {% if page.images.venobox %} - - - {% endif %} -{% endif %} - -{% if page.tabs %} - - -{% endif %} - -{% if site.back_to_top %} - - - -{% endif %} - -{% if site.search_enabled %} - - - - - - -{% endif %} diff --git a/_includes/figure.liquid b/_includes/figure.liquid deleted file mode 100644 index 5bf96bdf90c67..0000000000000 --- a/_includes/figure.liquid +++ /dev/null @@ -1,86 +0,0 @@ -{% assign img_path = include.path | remove: '.jpg' | remove: '.jpeg' | remove: '.png' | remove: '.tiff' | remove: '.gif' %} -{% assign parts = include.path | split: '.' %} -{% assign ext = parts.last %} - -
- - - - {% if site.imagemagick.enabled %} - {% unless include.avoid_scaling %} - - {% endunless %} - {% endif %} - {{ include.alt }} - - - {% if include.caption %} -
{{ include.caption }}
- {% endif %} -
diff --git a/_includes/footer.liquid b/_includes/footer.liquid deleted file mode 100644 index f028dfe0494a5..0000000000000 --- a/_includes/footer.liquid +++ /dev/null @@ -1,30 +0,0 @@ -{% capture footer_contents %} - © Copyright {{ site.time | date: '%Y' }} - {{ site.first_name }} - {{ site.middle_name }} - {{ site.last_name }}. {{ site.footer_text }} - {% if site.impressum_path %} - Impressum. - {% endif %} - {% if site.last_updated %} - Last updated: {{ 'now' | date: '%B %d, %Y' }}. - {% endif %} -{% endcapture %} - -{% if site.footer_fixed %} -
-
- {{ footer_contents }} -
-
-{% else %} -
- {% if site.newsletter.enabled %} - {% include newsletter.liquid %} - {% endif %} - -
- {{ footer_contents }} -
-
-{% endif %} diff --git a/_includes/giscus.liquid b/_includes/giscus.liquid deleted file mode 100644 index f4e6f06905e09..0000000000000 --- a/_includes/giscus.liquid +++ /dev/null @@ -1,25 +0,0 @@ -
- {% if page.layout == 'post' %} -
- {% endif %} - - {% if site.giscus.repo %} - - - {% else %} - {% capture giscus_warning %} -> ##### giscus comments misconfigured -> Please follow instructions at [http://giscus.app](http://giscus.app) and update your giscus configuration. -{: .block-danger } - {% endcapture %} - {{ giscus_warning | markdownify }} - {% endif %} -
diff --git a/_includes/head.liquid b/_includes/head.liquid deleted file mode 100644 index d79bea9ee3d6a..0000000000000 --- a/_includes/head.liquid +++ /dev/null @@ -1,208 +0,0 @@ - -{% include metadata.liquid %} - - - - - - - - - - -{% if page.pretty_table %} - - -{% endif %} - - - - - - - - - -{% if page.toc and page.toc.sidebar %} - - -{% endif %} - - - -{% if page.pseudocode %} - - -{% endif %} - -{% if site.icon.size <= 4 %} - -{% elsif site.icon != blank %} - -{% endif %} - - - -{% if site.enable_darkmode %} - - - - -{% endif %} - -{% if page.map %} - - -{% endif %} - -{% if page.code_diff %} - - - - -{% endif %} - -{% if page.images %} - {% if page.images.compare %} - - - {% endif %} - {% if page.images.lightbox2 %} - - - {% endif %} - {% if page.images.photoswipe %} - - - {% endif %} - {% if page.images.slider %} - - - {% endif %} - {% if page.images.spotlight %} - - - {% endif %} - {% if page.images.venobox %} - - - {% endif %} -{% endif %} - -{% if page.tikzjax %} - -{% endif %} - -{% if site.enable_cookie_consent %} - - -{% endif %} diff --git a/_includes/header.liquid b/_includes/header.liquid deleted file mode 100644 index 8769cce0f5e0d..0000000000000 --- a/_includes/header.liquid +++ /dev/null @@ -1,150 +0,0 @@ -
- - - {% if site.enable_progressbar %} - - -
- -
- - {% endif %} -
diff --git a/_includes/latest_posts.liquid b/_includes/latest_posts.liquid deleted file mode 100644 index 3342619cd38b8..0000000000000 --- a/_includes/latest_posts.liquid +++ /dev/null @@ -1,48 +0,0 @@ -
- {% if page.latest_posts != blank %} - {% assign latest_posts_size = site.posts | size %} -
3 %} - style="max-height: 60vw" - {% endif %} - > - - {% assign latest_posts = site.posts %} - {% if page.latest_posts.limit %} - {% assign latest_posts_limit = page.latest_posts.limit %} - {% else %} - {% assign latest_posts_limit = latest_posts_size %} - {% endif %} - {% for item in latest_posts limit: latest_posts_limit %} - - - - - {% endfor %} -
{{ item.date | date: '%b %d, %Y' }} - {% if item.redirect == blank %} - {{ item.title }} - {% elsif item.redirect contains '://' %} - {{ item.title }} - - - - {% else %} - {{ item.title }} - {% endif %} -
-
- {% else %} -

No posts so far...

- {% endif %} -
diff --git a/_includes/metadata.liquid b/_includes/metadata.liquid deleted file mode 100644 index e12e394b40d05..0000000000000 --- a/_includes/metadata.liquid +++ /dev/null @@ -1,247 +0,0 @@ -{% if site.enable_google_verification or site.enable_bing_verification %} - - {% if site.enable_google_verification %} - - {% endif %} - {% if site.enable_bing_verification %} - - {% endif %} - - -{% endif %} - -{% capture author_name %}{{ site.first_name }}{% if site.middle_name %} {{ site.middle_name }}{% endif %} {{ site.last_name }}{% endcapture %} - - - - - - - {% if site.title == 'blank' %} - {% capture title %}{{ author_name }}{% endcapture %} - {% else %} - {% capture title %}{{ site.title }}{% endcapture %} - {% endif %} - {% if page.url == '/blog/index.html' %} - {{ page.title }} | {{ title }} - {% elsif page.title != 'blank' and page.url != '/' %} - {% if page.title == null or page.title == '' %} - {{ page.date | date: '%Y' }} | {{ title }} - {% else %} - {{ page.title }} | {{ title }} - {% endif %} - {% else %} - {{ title }} - {% endif %} - - - -{% if page.keywords or site.keywords %} - -{% endif %} - -{% assign is_blog_post = false %} -{% if page.url != '/blog/index.html' and page.url contains '/blog/' %} - {% unless page.url contains '/tag/' or page.url contains '/category/' %} - {% assign is_blog_post = true %} - {% endunless %} -{% endif %} - -{% if site.serve_og_meta %} - - - - - - - {% if page.og_image or site.og_image %} - - {% endif %} - - - - - - - {% if page.og_image or site.og_image %} - - {% endif %} - {% if site.x_username %} - - - {% endif %} -{% endif %} - -{% if site.serve_schema_org %} - - {% comment %} Social links generator for "sameAs schema" {% endcomment %} - {% assign sameaslinks = '' | split: ',' %} - {% for social in site.data.socials %} - {% case social[0] %} - {% when 'acm_id' %} - {% capture link %}https://dl.acm.org/profile/{{ social[1] }}/{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'arxiv_id' %} - {% capture link %}https://arxiv.org/a/{{ social[1] }}.html{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'blogger_url' %} - {% capture link %}{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'bluesky_url' %} - {% capture link %}{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'dblp_url' %} - {% capture link %}{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'discord_id' %} - {% capture link %}https://discord.com/users/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'email' %} - {% comment %} - {% capture link %}mailto:{{ social[1] | encode_email }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% endcomment %} - {% when 'facebook_id' %} - {% capture link %}https://facebook.com/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'flickr_id' %} - {% capture link %}https://www.flickr.com/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'github_username' %} - {% capture link %}https://github.com/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'gitlab_username' %} - {% capture link %}https://gitlab.com/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'hal_id' %} - {% capture link %}https://cv.hal.science/{{ social[1] }}/{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'ieee_id' %} - {% capture link %}https://ieeexplore.ieee.org/author/{{ social[1] }}/{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'inspirehep_id' %} - {% capture link %}https://inspirehep.net/authors/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'instagram_id' %} - {% capture link %}https://instagram.com/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'kaggle_id' %} - {% capture link %}https://www.kaggle.com/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'keybase_username' %} - {% capture link %}https://keybase.io/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'lastfm_id' %} - {% capture link %}https://www.last.fm/user/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'lattes_id' %} - {% capture link %}http://lattes.cnpq.br/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'leetcode_id' %} - {% capture link %}https://leetcode.com/u/{{ social[1] }}/{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'linkedin_username' %} - {% capture link %}https://www.linkedin.com/in/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'mastodon_username' %} - {% capture link %}https://{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'medium_username' %} - {% capture link %}https://medium.com/@{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'orcid_id' %} - {% capture link %}https://orcid.org/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'osf_id' %} - {% capture link %}https://osf.io/{{ social[1] }}/{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'pinterest_id' %} - {% capture link %}https://www.pinterest.com/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'publons_id' %} - {% capture link %}https://publons.com/a/{{ social[1] }}/{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'quora_username' %} - {% capture link %}https://www.quora.com/profile/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'research_gate_profile' %} - {% capture link %}https://www.researchgate.net/profile/{{ social[1] }}/{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'rss_icon' %} - {% comment %} - {% capture link %}{{ site.baseurl }}/feed.xml{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% endcomment %} - {% when 'scholar_userid' %} - {% capture link %}https://scholar.google.com/citations?user={{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'scopus_id' %} - {% capture link %}https://www.scopus.com/authid/detail.uri?authorId={{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'semanticscholar_id' %} - {% capture link %}https://www.semanticscholar.org/author/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'spotify_id' %} - {% capture link %}https://open.spotify.com/user/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'stackoverflow_id' %} - {% capture link %}https://stackoverflow.com/users/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'strava_userid' %} - {% capture link %}https://www.strava.com/athletes/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'telegram_username' %} - {% capture link %}https://telegram.me/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'unsplash_id' %} - {% capture link %}https://unsplash.com/@{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'whatsapp_number' %} - {% capture link %}https://wa.me/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'wikidata_id' %} - {% capture link %}https://www.wikidata.org/wiki/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'wikipedia_id' %} - {% capture link %}https://wikipedia.org/wiki/User:{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'work_url' %} - {% capture link %}{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'x_username' %} - {% capture link %}https://twitter.com/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'youtube_id' %} - {% capture link %}https://youtube.com/@{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% when 'zotero_username' %} - {% capture link %}https://www.zotero.org/{{ social[1] }}{% endcapture %} - {% assign sameaslinks = sameaslinks | push: link %} - {% else %} - {% assign sameaslinks = sameaslinks | push: social[1].url %} - {% endcase %} - {% endfor %} - - -{% endif %} diff --git a/_includes/news.liquid b/_includes/news.liquid deleted file mode 100644 index ddf40b86e76e7..0000000000000 --- a/_includes/news.liquid +++ /dev/null @@ -1,34 +0,0 @@ -
- {% if site.news != blank %} - {% assign news_size = site.news | size %} -
3 %} - style="max-height: 60vw" - {% endif %} - > - - {% assign news = site.news | reverse %} - {% if include.limit and page.announcements.limit %} - {% assign news_limit = page.announcements.limit %} - {% else %} - {% assign news_limit = news_size %} - {% endif %} - {% for item in news limit: news_limit %} - - - - - {% endfor %} -
{{ item.date | date: '%b %d, %Y' }} - {% if item.inline %} - {{ item.content | remove: '

' | remove: '

' | emojify }} - {% else %} - {{ item.title }} - {% endif %} -
-
- {% else %} -

No news so far...

- {% endif %} -
diff --git a/_includes/newsletter.liquid b/_includes/newsletter.liquid deleted file mode 100644 index ebceefcbc10fc..0000000000000 --- a/_includes/newsletter.liquid +++ /dev/null @@ -1,68 +0,0 @@ - - - diff --git a/_includes/pagination.liquid b/_includes/pagination.liquid deleted file mode 100644 index 61bf4fb67c505..0000000000000 --- a/_includes/pagination.liquid +++ /dev/null @@ -1,21 +0,0 @@ -{% if paginator.total_pages > 1 %} - -{% endif %} diff --git a/_includes/projects.liquid b/_includes/projects.liquid deleted file mode 100644 index 0ada935d291ac..0000000000000 --- a/_includes/projects.liquid +++ /dev/null @@ -1,35 +0,0 @@ -
- -
- {% if project.img %} - {% - include figure.liquid - loading="eager" - path=project.img - sizes = "250px" - alt="project thumbnail" - class="card-img-top" - %} - {% endif %} -
-

{{ project.title }}

-

{{ project.description }}

-
- {% if project.github %} -
-
- -
- {% if project.github_stars %} - - - - - {% endif %} -
- {% endif %} -
-
-
- -
diff --git a/_includes/projects_horizontal.liquid b/_includes/projects_horizontal.liquid deleted file mode 100644 index 8630e69e1d72e..0000000000000 --- a/_includes/projects_horizontal.liquid +++ /dev/null @@ -1,34 +0,0 @@ -
- -
-
- {% if project.img %} -
- {% include figure.liquid loading="eager" path=project.img sizes="(min-width: 768px) 156px, 50vw" alt="project thumbnail" class="card-img" %} -
- {% endif %} -
-
-

{{ project.title }}

-

{{ project.description }}

-
- {% if project.github %} -
-
- -
- {% if project.github_stars %} - - - - - {% endif %} -
- {% endif %} -
-
-
-
-
- -
diff --git a/_includes/related_posts.liquid b/_includes/related_posts.liquid deleted file mode 100644 index 4ba91dddfe7dc..0000000000000 --- a/_includes/related_posts.liquid +++ /dev/null @@ -1,36 +0,0 @@ -{% assign have_related_posts = false %} -{% for post in site.related_posts | limit: site.related_blog_posts.max_related %} - {% unless have_related_posts %} - {% assign have_related_posts = true %} - {% if page.layout == 'post' %} -
-
-
-
    - - -

    Enjoy Reading This Article?

    - {% else %} -

    Enjoy Reading This Article?

    - {% endif %} - -

    Here are some more articles you might like to read next:

    - {% endunless %} - -
  • - {% if post.redirect == blank %} - {{ post.title }} - {% elsif post.redirect contains '://' %} - {{ post.title }} - - - - {% else %} - {{ post.title }} - {% endif %} -
    • -{% endfor %} -{% if site.newsletter.enabled and site.footer_fixed %} -

    Subscribe to be notified of future articles:

    - {% include newsletter.liquid left=true %} -{% endif %} diff --git a/_includes/repository/repo.liquid b/_includes/repository/repo.liquid deleted file mode 100644 index d2e4c64c1566c..0000000000000 --- a/_includes/repository/repo.liquid +++ /dev/null @@ -1,47 +0,0 @@ -{% assign repo_url = include.repository | split: '/' %} -{% if site.data.repositories.github_users contains repo_url.first %} - {% assign show_owner = false %} -{% else %} - {% assign show_owner = true %} -{% endif %} - -{% assign lang = site.lang | split: '-' | first %} - -{% case lang %} - {% when 'pt' %} - {% assign lang = site.lang %} - - {% when 'zh' %} - {% assign lang_last = site.lang | split: '-' | last %} - {% case lang_last %} - {% when 'cn', 'sg', 'my', 'hans' %} - {% assign lang = 'cn' %} - {% when 'tw', 'hk', 'mo', 'hant' %} - {% assign lang = 'zh-tw' %} - {% endcase %} - - {% comment %} Add a new language using when... if needed {% endcomment %} - {% comment %} If you still encounter language-display issues, check the available locale codes in github-readme-stats (different from ISO-639 standard used in your website) {% endcomment %} - {% comment %} https://github.com/anuraghazra/github-readme-stats?tab=readme-ov-file#available-locales {% endcomment %} -{% endcase %} - -{% if site.data.repositories.repo_description_lines_max %} - {% assign max_lines = site.data.repositories.repo_description_lines_max %} -{% else %} - {% assign max_lines = 2 %} -{% endif %} - -
    - - {{ include.repository }} - {{ include.repository }} - -
    diff --git a/_includes/repository/repo_trophies.liquid b/_includes/repository/repo_trophies.liquid deleted file mode 100644 index d0f3e9ca5c015..0000000000000 --- a/_includes/repository/repo_trophies.liquid +++ /dev/null @@ -1,42 +0,0 @@ -
    - - - {{ include.username }} - {{ include.username }} - - - - {{ include.username }} - {{ include.username }} - - - - {{ include.username }} - {{ include.username }} - - -
    diff --git a/_includes/repository/repo_user.liquid b/_includes/repository/repo_user.liquid deleted file mode 100644 index d41519c9c69ec..0000000000000 --- a/_includes/repository/repo_user.liquid +++ /dev/null @@ -1,34 +0,0 @@ -{% assign lang = site.lang | split: '-' | first %} - -{% case lang %} - {% when 'pt' %} - {% assign lang = site.lang %} - - {% when 'zh' %} - {% assign lang_last = site.lang | split: '-' | last %} - {% case lang_last %} - {% when 'cn', 'sg', 'my', 'hans' %} - {% assign lang = 'cn' %} - {% when 'tw', 'hk', 'mo', 'hant' %} - {% assign lang = 'zh-tw' %} - {% endcase %} - - {% comment %} Add a new language using when... if needed {% endcomment %} - {% comment %} If you still encounter language-display issues, check the available locale codes in github-readme-stats (different from ISO-639 standard used in your website) {% endcomment %} - {% comment %} https://github.com/anuraghazra/github-readme-stats?tab=readme-ov-file#available-locales {% endcomment %} -{% endcase %} - -
    - - {{ include.username }} - {{ include.username }} - -
    diff --git a/_includes/scripts.liquid b/_includes/scripts.liquid deleted file mode 100644 index e6b21ae57437b..0000000000000 --- a/_includes/scripts.liquid +++ /dev/null @@ -1,378 +0,0 @@ - - - - - - - -{% if site.enable_masonry %} - - - - -{% endif %} - -{% if page.mermaid and page.mermaid.enabled %} - - - {% if page.mermaid.zoomable %} - - {% endif %} - -{% endif %} - -{% if page.code_diff %} - - - - -{% endif %} - -{% if page.map %} - - - -{% endif %} - -{% if page.chart and page.chart.chartjs %} - - - -{% endif %} - -{% if page.chart and page.chart.echarts %} - - - {% if site.enable_darkmode %} - - {% endif %} - -{% endif %} - -{% if page.calendar %} - - -{% endif %} - -{% if page.chart and page.chart.plotly %} - - - -{% endif %} - -{% if page.chart and page.chart.vega_lite %} - - - - - -{% endif %} - -{% if page.tikzjax %} - - -{% endif %} - -{% if page.typograms %} - - -{% endif %} - -{% if site.enable_tooltips %} - - -{% endif %} - -{% if site.enable_medium_zoom %} - - - -{% endif %} - -{% if page.toc and page.toc.sidebar %} - - -{% endif %} - -{% if page.pretty_table %} - - - -{% endif %} - - - - - - - - - - -{% if site.enable_publication_badges.altmetric %} - -{% endif %} -{% if site.enable_publication_badges.dimensions %} - -{% endif %} - -{% if site.enable_math %} - - - {% unless page.pseudocode %} - - - {% else %} - - - {% endunless %} -{% endif %} - -{% if site.enable_cookie_consent %} - - - -{% endif %} - -{% if site.enable_google_analytics %} - - - - -{% endif %} - -{% if site.enable_cronitor_analytics %} - - - -{% endif %} -{% if site.enable_pirsch_analytics %} - -{% endif %} -{% if site.enable_openpanel_analytics %} - - -{% endif %} - -{% if site.enable_progressbar %} - - -{% endif %} - -{% if page.images %} - - {% if page.images.compare %} - - {% endif %} - {% if page.images.lightbox2 %} - - {% endif %} - {% if page.images.photoswipe %} - - {% endif %} - {% if page.images.slider %} - - {% endif %} - {% if page.images.spotlight %} - - {% endif %} - {% if page.images.venobox %} - - - {% endif %} -{% endif %} - -{% if page.tabs %} - - -{% endif %} - -{% if site.back_to_top %} - - - -{% endif %} - -{% if site.search_enabled %} - - - - - - -{% endif %} - -{% if site.newsletter.enabled %} - -{% endif %} diff --git a/_includes/selected_papers.liquid b/_includes/selected_papers.liquid deleted file mode 100644 index e9bf0935dd145..0000000000000 --- a/_includes/selected_papers.liquid +++ /dev/null @@ -1,3 +0,0 @@ -
    - {% bibliography --group_by none --query @*[selected=true]* %} -
    diff --git a/_includes/video.liquid b/_includes/video.liquid deleted file mode 100644 index 8823106f5b28d..0000000000000 --- a/_includes/video.liquid +++ /dev/null @@ -1,97 +0,0 @@ -{% assign extension = include.path | split: '.' | last %} - -
    - {% if extension == 'mp4' or extension == 'webm' or extension == 'ogg' %} -