docs: add CLAUDE.md, GEMINI.md, AGENTS.md, and update CONTRIBUTING.md (#36)

hasansezertasan · claude · web-flow · commit 5deead1552f8 · 2026-02-02T13:18:33.000+03:00
Co-authored-by: Claude Haiku 4.5 &lt;noreply@anthropic.com&gt;
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1 @@
+CLAUDE.md
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,82 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an "awesome list" repository that curates and ranks open-source Python HTML generation projects. It uses the [best-of-generator](https://github.com/best-of-lists/best-of-generator) to automatically generate a ranked README from project metadata.
+
+**Key insight**: This is NOT a code project. It's a metadata/content management repository where the README.md is auto-generated from `projects.yaml`.
+
+## Architecture
+
+```
+projects.yaml          → Source of truth for all project metadata
+     ↓
+best-of-update-action  → GitHub Action that fetches metrics and generates README
+     ↓
+README.md              → Auto-generated ranked list (never edit directly)
+```
+
+**Template files:**
+
+- `config/header.md` - README header template (supports variables: `{project_count}`, `{stars_count}`, `{category_count}`)
+- `config/footer.md` - README footer template
+
+## Working with This Repository
+
+### Adding/Updating Projects
+
+Edit `projects.yaml` only. Never modify README.md directly.
+
+**Required project properties:**
+
+- `name` - Unique project name
+- `github_id` - Format: `owner/repo` (e.g., `pelme/htpy`)
+
+**Optional properties:**
+
+- `category` - One of: `html-generation`, `html-form-generation`, `related-projects`, `miscellaneous`
+- `labels` - List of labels
+- `pypi_id`, `conda_id`, `npm_id`, `dockerhub_id`, `maven_id` - Package manager IDs
+
+**Example entry:**
+
+```yaml
+- name: htpy
+  github_id: pelme/htpy
+  category: "html-generation"
+```
+
+### Automated Updates
+
+The GitHub workflow (`update-best-of-list.yml`) runs weekly:
+
+1. Creates an `update/YYYY.MM.DD` branch
+2. Fetches GitHub metrics and package manager data
+3. Regenerates README.md with updated rankings
+4. Creates a PR and draft release
+
+Manual trigger: Run workflow from GitHub Actions with optional version input.
+
+### Contribution Conventions
+
+See `CONTRIBUTING.md` for full details. Key points:
+
+- **One project per PR/issue**
+- **Branch naming**: `feat/<github_id>` for projects, `docs/<description>` for docs
+- **PR title**: `` Add `project:<github_id>` `` (use backtick-wrapped identifiers)
+- **PR title with category**: `` Add `project:<github_id>` and `category:<id>` ``
+- **Docs PR title**: `docs: <description>`
+- **PR body**: Fill in `.github/PULL_REQUEST_TEMPLATE.md` — check the change type box, add a project link with description, check both checklist items
+- **Commits**: Squash-merged using the PR title, so branch commit messages don't matter
+
+## Files You Should Know
+
+| File                | Purpose                                      |
+| ------------------- | -------------------------------------------- |
+| `projects.yaml`     | All project metadata - the only file to edit |
+| `config/header.md`  | README header template                       |
+| `config/footer.md`  | README footer template                       |
+| `latest-changes.md` | Auto-generated trending projects summary     |
+| `history/`          | Historical snapshots of each update          |
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,4 +1,5 @@
 <!-- markdownlint-disable MD024 -->
+
 # Contribution Guidelines
 
 Thanks for your interest in contributing to our project. This page will give you a quick overview of how things are organized and, most importantly, how to get involved. Everyone is welcome to contribute, and we value everybody's contribution.
@@ -10,7 +11,8 @@ Thanks for your interest in contributing to our project. This page will give you
 3. [Improve metadata collection](#improve-metadata-collection)
 4. [Improve markdown generation](#improve-markdown-generation)
 5. [Create your own best-of list](#improve-markdown-generation)
-6. [Code of conduct](#code-of-conduct)
+6. [Conventions](#conventions)
+7. [Code of conduct](#code-of-conduct)
 
 ## Add a project
 
@@ -23,14 +25,14 @@ Before opening an issue or pull request, please ensure that you adhere to the fo
 
 - Please make sure that the project was not already added or suggested to this best-of list. You can ensure this by searching the projects.yaml, the Readme, and the issue list.
 - Add the project to the `projects.yaml` and never to the `README.md` file directly. Use the yaml format and the properties documented in the [project properties](#project-properties) section below to add a new project, for example:
-    ```yaml
-    - name: Tensorflow
-      github_id: tensorflow/tensorflow
-      pypi_id: tensorflow
-      conda_id: tensorflow
-      labels: ["tensorflow"]
-      category: ml-frameworks
-    ```
+  ```yaml
+  - name: Tensorflow
+    github_id: tensorflow/tensorflow
+    pypi_id: tensorflow
+    conda_id: tensorflow
+    labels: ["tensorflow"]
+    category: ml-frameworks
+  ```
 - Please create an individual issue or pull request for each project.
 - Please use the following title format for the issue or pull request: `Add project: project-name`.
 - If a project doesn't fit into any of the pre-existing categories, it should go under the `Others` category by not assigning any category. You can also suggest a new category via the add or update category template on the [issue page](https://github.com/hasansezertasan/awesome-python-html/issues/new/choose).
@@ -113,6 +115,41 @@ If you like to contribute to or share suggestions regarding the markdown generat
 
 If you want to create your own best-of list, we strongly recommend to follow [this guide](https://github.com/best-of-lists/best-of/blob/main/create-best-of-list.md). With this guide, it will only take about 3 minutes to get you started. It is already set-up to automatically run the best-of generator via our Github Action and includes other useful template files.
 
+## Conventions
+
+### Branch naming
+
+| Change type            | Format                     | Example                  |
+| ---------------------- | -------------------------- | ------------------------ |
+| Add a project          | `feat/<github_id>`         | `feat/pelme/htpy`        |
+| Add project + category | `feat/<github_id>`         | `feat/Knio/dominate`     |
+| Documentation          | `docs/<short-description>` | `docs/add-claude-md`     |
+| Update a project       | `update/<project-name>`    | `update/htpy`            |
+
+### PR title
+
+| Change type            | Format                                                       | Example                                                              |
+| ---------------------- | ------------------------------------------------------------ | -------------------------------------------------------------------- |
+| Add a project          | `` Add `project:<github_id>` ``                              | `` Add `project:pelme/htpy` ``                                       |
+| Add project + category | `` Add `project:<github_id>` and `category:<category-id>` `` | `` Add `project:Knio/dominate` and `category:html-generation` ``     |
+| Documentation          | `docs: <description>`                                        | `docs: add CLAUDE.md for Claude Code guidance`                       |
+| Update a project       | `Update project: <name>`                                     | `Update project: htpy`                                               |
+
+### PR body
+
+Fill in the [pull request template](./.github/PULL_REQUEST_TEMPLATE.md):
+
+1. **What kind of change** — Check the appropriate box(es) with `[x]`.
+2. **Description** — Link to the project's GitHub page with a short description, e.g.:
+   ```
+   [A modern Python library for generating HTML in a functional way.](https://github.com/pelme/htpy)
+   ```
+3. **Checklist** — Check both boxes after verifying.
+
+### Commit messages
+
+This repository uses squash merges, so the final commit message matches the PR title. No special commit message format is needed in your branch.
+
 ## Code of Conduct
 
 All members of the project community must abide by the [Contributor Covenant, version 2.0](./.github/CODE_OF_CONDUCT.md). Only by respecting each other we can develop a productive, collaborative community. Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting a project maintainer.
diff --git a/GEMINI.md b/GEMINI.md
@@ -0,0 +1 @@
+CLAUDE.md
diff --git a/projects.yaml b/projects.yaml
@@ -339,6 +339,10 @@ projects:
     category: "related-projects"
     group_id: "knio/dominate"
     labels:
+  - name: "python-hiccup"
+    github_id: "DavidVujic/python-hiccup"
+    category: "html-generation"
+    labels:
   - name: "Why Kotlin Is The Best Language (to use with htmx) - YouTube"
     homepage: "https://www.youtube.com/watch?v=zJNkIJCQohU"
     resource: True
