diff --git a/.gemini/settings.json b/.gemini/settings.json new file mode 100644 index 0000000..a01c594 --- /dev/null +++ b/.gemini/settings.json @@ -0,0 +1,14 @@ +{ + "context": [ + "AGENTS.md", + ".github/copilot-instructions.md", + ".github/agents/customize.agent.md", + ".github/agents/docs.agent.md", + ".github/instructions/**/*.md", + "CUSTOMIZE.md", + "INSTALL.md", + "TROUBLESHOOTING.md", + "QUICKSTART.md", + "README.md" + ] +} diff --git a/.github/GIT_WORKFLOW.md b/.github/GIT_WORKFLOW.md new file mode 100644 index 0000000..674db4a --- /dev/null +++ b/.github/GIT_WORKFLOW.md @@ -0,0 +1,47 @@ +# Git Workflow + +This document outlines the conventions for using Git and writing commit messages in this project. + +## Commit Message Format + +All commit messages should follow this format: + +``` +: + + +``` + +**Types:** + +- `feat`: A new feature +- `fix`: A bug fix +- `docs`: Documentation only changes +- `style`: Changes that do not affect the meaning of the code (white-space, formatting, etc.) +- `config`: Changes to configuration files +- `chore`: Changes to the build process or auxiliary tools and libraries + +**Examples:** + +``` +feat: Add dark mode toggle button to header +fix: Correct baseurl in project site configuration +docs: Update INSTALL.md with Docker troubleshooting +style: Format all Liquid templates with Prettier +config: Enable blog section in _config.yml +chore: Update Jekyll dependencies with bundle update --all +``` + +## Staging Changes + +**Always `git add` files explicitly.** Do not stage everything with `git add .` unless you are certain of what's being committed. Check `git status` first to review your changes. + +## What NOT to Commit + +**Always obey the project's [`.gitignore`](../.gitignore) file.** It prevents the accidental commit of: + +- Build outputs (`_site/`, `.jekyll-cache/`) +- Dependencies (`node_modules/`, `vendor/`) +- OS-specific files (`.DS_store`) +- Editor temporary files (`.idea/`, `.swp`, `.swo`) +- Secrets and API keys (never commit credentials) diff --git a/AGENTS.md b/AGENTS.md index ba782a1..8b22fd6 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # Agent Guidelines for al-folio -This is a hub for AI agents and automation tools working with the al-folio repository. It directs you to specialized resources by role and task type. +A simple, clean, and responsive Jekyll theme for academics. ## Quick Links by Role @@ -16,35 +16,40 @@ This is a hub for AI agents and automation tools working with the al-folio repos ### Local Development (Docker) +The recommended approach is using Docker. + ```bash # Initial setup & start dev server docker compose pull && docker compose up # Site runs at http://localhost:8080 -# Rebuild with updated dependencies +# Rebuild after changing dependencies or Dockerfile docker compose up --build -# Stop containers +# Stop containers and free port 8080 docker compose down ``` ### Pre-Commit Checklist -```bash -# 1. Format code -npm install --save-dev prettier @shopify/prettier-plugin-liquid # (first time only) -npx prettier . --write +Before every commit, you **must** run these steps: -# 2. Build locally -docker compose up --build +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:** -# 3. Verify site -# → Visit http://localhost:8080 and check navigation, pages, images, dark mode + ```bash + # Rebuild the site + docker compose up --build -# 4. Commit with clear message -git add . -git commit -m "type: description" # See "Commit Format" below -``` + # Verify by visiting http://localhost:8080. + # Check navigation, pages, images, and dark mode. + ``` ## Critical Configuration @@ -54,40 +59,10 @@ When modifying `_config.yml`, these **must be updated together**: - **Project site:** `url: https://username.github.io` + `baseurl: /repo-name/` - **YAML errors:** Quote strings with special characters: `title: "My: Cool Site"` -## Common Issues +## Development Workflow -For troubleshooting common build, deployment, and configuration issues, see: - -- [Common Pitfalls & Workarounds](https://github.com/alshedivat/al-folio/blob/master/.github/copilot-instructions.md#common-pitfalls--workarounds) in copilot-instructions.md -- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for detailed solutions -- [GitHub Issues](https://github.com/alshedivat/al-folio/issues) to search for your specific problem - -## Commit Format - -``` -: - - -``` - -**Types:** `feat` (feature), `fix` (bug), `docs` (docs), `style` (formatting), `config` (configuration), `chore` (maintenance) - -**Examples:** - -``` -feat: Add dark mode toggle button to header -fix: Correct baseurl in project site configuration -docs: Update INSTALL.md with Docker troubleshooting -style: Format all Liquid templates with Prettier -config: Enable blog section in _config.yml -chore: Update Jekyll dependencies with bundle update --all -``` - -**Always git add explicitly** – Do not stage everything with `git add .` unless you're certain of what's being committed. Check `git status` first. - -## Code-Specific Instructions - -Always consult the relevant instruction file for your code type: +- **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 | | --------------------------------------------- | ----------------------------------------------------------------------------------------------- | @@ -97,23 +72,10 @@ Always consult the relevant instruction file for your code type: | Liquid templates (`_includes/`, `_layouts/`) | [liquid-templates.instructions.md](.github/instructions/liquid-templates.instructions.md) | | JavaScript (`_scripts/`) | [javascript-scripts.instructions.md](.github/instructions/javascript-scripts.instructions.md) | -## Auto-Loaded Context +## Common Issues -The following files are automatically available to you in this agent context: +For troubleshooting, see: -- [`.github/copilot-instructions.md`](.github/copilot-instructions.md) – Primary technical reference -- [`.github/instructions/*.md`](.github/instructions/) – Code-specific instruction files (loaded when editing relevant file types) - -Other files need to be accessed explicitly. - -## What NOT to Commit - -**Always obey [`.gitignore`](.gitignore).** It prevents accidental commits of: - -- Build outputs (`_site/`, `.jekyll-cache/`, etc.) -- Dependencies (`node_modules/`, `Gemfile.lock`, `vendor/`) -- OS files (`.DS_store`) -- Editor temp files (`.idea/`, `.swp`, `.swo`) -- Secrets and API keys (never commit credentials) - -If you create new files, ensure they follow the patterns in `.gitignore`. +- [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. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md