b67d2a19d8
This pull request updates project documentation to clarify and standardize the development workflow, Git practices, and troubleshooting resources. The main changes include adding a dedicated Git workflow guide and reorganizing the `AGENTS.md` file for better clarity and usability. **Documentation and Workflow Improvements:** * Added a new `.github/GIT_WORKFLOW.md` file detailing commit message conventions, types, and best practices for staging and ignoring files. * Reorganized and clarified the pre-commit checklist and local development instructions in `AGENTS.md`, emphasizing Docker usage and proper code formatting. * Updated the section on configuration and troubleshooting in `AGENTS.md` to better direct users to relevant resources and removed redundant or outdated instructions. [[1]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L57-R58) [[2]](diffhunk://#diff-a54ff182c7e8acf56acfd6e4b9c3ff41e2c41a31c9b211b2deb9df75d9a478f9L100-R74) **Configuration and Context Updates:** * Added a `.gemini/settings.json` file to define context files for Gemini agent operations, ensuring relevant documentation is available for automation tools. * Created `CLAUDE.md` file pointing to `AGENTS.md`. --------- Signed-off-by: George Araújo <george.gcac@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
82 lines
3.5 KiB
Markdown
82 lines
3.5 KiB
Markdown
# Agent Guidelines for al-folio
|
|
|
|
A simple, clean, and responsive Jekyll theme for academics.
|
|
|
|
## Quick Links by Role
|
|
|
|
- **Are you a coding agent?** → Read [`.github/copilot-instructions.md`](.github/copilot-instructions.md) first (tech stack, build, CI/CD, common pitfalls & solutions)
|
|
- **Customizing the site?** → See [`.github/agents/customize.agent.md`](.github/agents/customize.agent.md)
|
|
- **Writing documentation?** → See [`.github/agents/docs.agent.md`](.github/agents/docs.agent.md)
|
|
- **Need setup/deployment help?** → [INSTALL.md](INSTALL.md)
|
|
- **Troubleshooting & FAQ?** → [TROUBLESHOOTING.md](TROUBLESHOOTING.md)
|
|
- **Customization & theming?** → [CUSTOMIZE.md](CUSTOMIZE.md)
|
|
- **Quick 5-min start?** → [QUICKSTART.md](QUICKSTART.md)
|
|
|
|
## Essential Commands
|
|
|
|
### Local Development (Docker)
|
|
|
|
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 after changing dependencies or Dockerfile
|
|
docker compose up --build
|
|
|
|
# Stop containers and free port 8080
|
|
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
|
|
|
|
For troubleshooting, see:
|
|
|
|
- [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.
|