---
title: "README Generation & Asset Management"
description: "This document explains how the README and its visual assets are generated and maintained. It's mostly a reference document for development purposes, written and maintained by the coding agents who write most of the code, with some commentary sprinkled in."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/readme-generation
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:36:04.243Z
license: CC-BY-4.0
attribution: "README Generation & Asset Management — Claudary (https://claudary.paisolsolutions.com/skills/readme-generation)"
---

# README Generation & Asset Management
This document explains how the README and its visual assets are generated and maintained. It's mostly a reference document for development purposes, written and maintained by the coding agents who write most of the code, with some commentary sprinkled in.

## Overview

# README Generation & Asset Management

This document explains how the README and its visual assets are generated and maintained. It's mostly a reference document for development purposes, written and maintained by the coding agents who write most of the code, with some commentary sprinkled in.

## Overview

The repository implements a "multi-list" pattern, with one centralized "list" (which is effectively a kind of backend) and numerous "views" that are strictly generated from the central data source. In that sense, it's maybe the only "full-stack" Awesome list on GitHub - maybe that's a sign that it's a silly thing to do, but I figured if I was going to spend so much time maintaining a list, I had better do something interesting with it. To my knowledge, it's one of the few "full-stack applications" that's entirely hosted on GitHub.com (i.e. not a GitHub Pages site). (Yes, there are others. And yes, calling this an "application" is obviously a little bit of a stretch.)

- **`THE_RESOURCES_TABLE.csv`** - The master data file containing all resources (repo root)
- **`acc-config.yaml`** - Global configuration (root style, style selector settings)
- **`templates/categories.yaml`** - Category and subcategory definitions
- **`scripts/readme/generate_readme.py`** - The generator script (class-based architecture)
- **`scripts/readme/helpers/readme_config.py`** - Config loader and style path helpers
- **`scripts/readme/helpers/readme_utils.py`** - Shared parsing/anchor utilities
- **`scripts/readme/helpers/readme_assets.py`** - SVG asset writers (badges, TOC rows, headers)
- **`scripts/readme/markup/`** - Markdown/HTML renderers by style
- **`scripts/readme/svg_templates/`** - SVG renderers used by the generator
- **`assets/`** - SVG visual assets (badges, headers, dividers, etc.)

The multi-list is maintained via a single source of truth, combined with generators that take templates (which implement the various styles), and generate all the READMEs. The complexity is mostly self-inflicted, and is an artefact of platform-specific features of GitHub.

### Generated README Styles

| Style | Primary Output | Template | Description |
|-------|-------------|----------|-------------|
| Extra (Visual) | `README_ALTERNATIVES/README_EXTRA.md` | `README_EXTRA.template.md` | Full visual theme with SVG badges, CRT-style TOC |
| Classic | `README_ALTERNATIVES/README_CLASSIC.md` | `README_CLASSIC.template.md` | Plain markdown with collapsible sections |
| Awesome | `README_ALTERNATIVES/README_AWESOME.md` | `README_AWESOME.template.md` | Clean awesome-list style |
| Flat | `README_ALTERNATIVES/README_FLAT_*.md` | Built-in template (optional `templates/README_FLAT.template.md`) | 44 table views (category × sort combinations) |

All styles are always generated under `README_ALTERNATIVES/`. The `root_style` is additionally written to `README.md`.

#### Etymology

- **Classic:** The style of the list as it was initially maintained and iterated upon, before the "multi-list" pattern was adopted.
- ***Extra:*** Heightened visual style, consisting almost entirely of SVG assets - "extra" does not mean "additional", it means _extra_.
- **Flat:** Lacks internal structure or visual hierarchy; the "flat" views are basically just a dump of the CSV data with shields.io badges - information-dense and straightforward. This was implemented due to a single user's request, but it became a more interesting problem when the user asked for dynamic table features like sorting and filtering. This is "not possible" with Markdown, which is why I decided to do it - since you can't have any JavaScript on a README, the sorting and filtering functionality is simulated by generating every permutation of Sort x Filter as a separate file, and so the table operations become navigation.
- **Awesome:** The style that is more or less compliant with the Awesome List style guide.

Generation runs in two phases:
1. Generate all styles under `README_ALTERNATIVES/`.
2. Generate `README.md` using the configured `root_style`.

If everything lived at the repo root, this would be a very easy thing to build, but then the user would have to scroll a lot before they even hit the first `h1`. So the whole complexity is due to the necessity of supporting multiple generated README files at two different paths. I'm not even sure if many people enjoy the "Flat" view, and without the 44 permutations, it probably wouldn't be a big deal at all to just put everything at the root... Hm. Nevertheless, I'm grateful to that user for giving me the opportunity to learn some new things, and to build this ridiculous Titanic just to host a list, and I hope the "curiosity" of it compensates for any aesthetic crimes that I've committed in building it.

## Configuration (`acc-config.yaml`)

The `acc-config.yaml` file at the repository root controls global README generation settings.

### Root Style

The `readme.root_style` setting determines which README style is additionally written to the repo root (`README.md`). All styles are always generated in `README_ALTERNATIVES/`.

```yaml
readme:
  root_style: extra  # Options: extra, classic, awesome, flat
```

Changing this value and regenerating will:
- Write the new root style to `README.md`
- Keep all styles (including the root) in `README_ALTERNATIVES/`
- Update the style selector links to reflect which style is root

### Style Selector Configuration

The `styles` section defines each README style's metadata for the style selector:

```yaml
styles:
  extra:
    name: Extra                    # Display name for badge alt text
    badge: badge-style-extra.svg   # Badge filename in assets/
    highlight_color: "#6a6a8a"     # Border color when selected
    filename: README_EXTRA.md

  classic:
    name: Classic
    badge: badge-style-classic.svg
    highlight_color: "#c9a227"
    filename: README_CLASSIC.md
  # ... other styles
```

`filename` is the README variant filename under `README_ALTERNATIVES/` used for selector links and references.

The `style_order` list controls the left-to-right order of badges in the selector:

```yaml
style_order:
  - extra
  - classic
  - flat
  - awesome
```

## Quick Reference

| Task | Automated? | What to do |
|------|------------|------------|
| Add a new resource | Yes | Add row to CSV, run `make generate` |
| Add a new category | Yes | Use `make add-category` or edit `categories.yaml` |
| Add a new subcategory | Yes | Edit `categories.yaml`, run `make generate-toc-assets`, run generator |
| Update resource info | Yes | Edit CSV, run `make generate` |
| Customize asset style | Manual | Edit generator templates or asset files |

## Backups (README Outputs)

The README generators create a backup of the existing output file before overwriting it.

- Location: `.myob/backups/` at repo root
- Naming: `{basename}.{YYYYMMDD_HHMMSS}.bak` (e.g., `README.md.20250105_154233.bak`)
- Behavior: only created when the target file already exists
- Coverage: applies to README outputs written by `scripts/readme/generate_readme.py`
- Retention: keeps the most recent backup per output file; older backups are pruned

## Adding a New Resource

This process is now handled entirely by GitHub workflows. Due to the intricate, not-at-all-over-engineered design ~~mistakes~~ choices, having people submit PRs became unmanageable. Instead, all of the data that goes into a resource entry is processed as a "form" using GitHub's Issue form templates. That makes the shape of an Issue predictable, and the different fields are machine-readable. Since the resources table is the single source of truth for the list entries, the goal is just to get the necessary data points into the CSV, and everything else is controlled by the template/generator system. This eliminated any problems around merge conflicts, stale resource PRs, etc. (Trying to fix merge conflicts in a CSV file is not a good way to spend an afternoon.) The _state_ of resource recommendation Issues is managed by (i) labels (`pending-validation`, `validation-passed`, `approved`, etc.), which indicate the current state; (ii) "slash commands" (`/approve`, `/request-changes`, etc.), which trigger a workflow that transitions the state (if they're written by the maintainer). This is a simplified piecture of what the GitHub bot does once a resource is approved:

1. **Edit `THE_RESOURCES_TABLE.csv`** - Add a new row with these columns:
   - `Display Name` - The resource name shown in the README
   - `Primary Link` - URL to the resource (usually GitHub)
   - `Author Name` - Creator's name (optional but recommended)
   - `Author Link` - URL to author's profile
   - `Description` - Brief description of the resource
   - `Category` - Must match a category name in `categories.yaml`
   - `Sub-Category` - Must match a subcategory in `categories.yaml`
   - `Active` - Set to `TRUE` to include in README
   - `Removed From Origin` - Set to `TRUE` if the original repo/resource was deleted

The reason for the last field is due to the fact that (i) well, it's good to know if you're sharing a link that's dead; (ii) for a while, I was maintaing copies of the third-party authors' resources on the list (when it was licensed in a way that allowed me to do that), but that was when the resource were usually a bit of plaintext. Most entries are full repositories, and re-hosting entire repositories is out of scope. That directory is still present, but it's not currently maintained, and may become deprecated.

2. **Run the generator:**
   ```bash
   make generate
   # or directly:
   python3 scripts/readme/generate_readme.py
   ```

3. **What gets auto-generated:**
   - `assets/badge-{resource-name}.svg` - Theme-adaptive badge with initials box
   - Entry in all README styles

## Adding a New Category

1. **Use the interactive tool:**
   ```bash
   make add-category
   # or with arguments:
   make add-category ARGS='--name "My Category" --prefix mycat --icon "🎯"'
   ```

   Note: `make add-category` uses `scripts/categories/add_category.py` (experimental). It rewrites
   `templates/categories.yaml` via PyYAML and updates `.github/ISSUE_TEMPLATE/recommend-resource.yml`,
   so review the diff after running it.

2. **Or manually edit `templates/categories.yaml`:**
   ```yaml
   categories:
     - id: my-category
       name: My Category
       icon: "🎯"
       description: Description of this category
       order: 10
       subcategories:
         - id: general
           name: General
   ```

3. **Run the generator:**
   ```bash
   make generate
   ```

4. **What gets auto-generated:**
   - `assets/header_{category}.svg` - Dark mode category header (CRT style)
   - `assets/header_{category}-light-v3.svg` - Light mode category header
   - `assets/subheader_{subcat}.svg` - Subcategory header (when resources exist)
   - Section in all README styles

5. **Regenerate subcategory TOC SVGs** (if subcategories were added):
   ```bash
   make generate-toc-assets
   ```
   This creates/updates `assets/toc-sub-{subcat}.svg` and `assets/toc-sub-{subcat}-light-anim-scanline.svg` files for all subcategories.

6. **What needs manual creation:**
   - `assets/toc-row-{category}.svg` and `assets/toc-row-{category}-light-anim-scanline.svg` - TOC row assets (category-level)
   - Card assets if using the EXTRA style navigation grid

## Adding a New Subcategory

Subcategories can be added to any category.

1. **Edit `templates/categories.yaml`:**
   ```yaml
   categories:
     - id: tooling
       name: Tooling
       subcategories:
         - id: general
           name: General
         - id: my-new-subcat    # Add new subcategory
           name: My New Subcat
   ```

2. **Regenerate subcategory TOC SVGs:**
   ```bash
   make generate-toc-assets
   ```
   This creates/updates the `toc-sub-*.svg` and `toc-sub-*-light-anim-scanline.svg` files in `assets/` for all subcategories.

3. **Run the generator** - Subcategory headers are auto-generated alongside the README content

## If You Change Category IDs or Names

Update these locations:
1. `templates/categories.yaml` - Category definitions
2. Card-grid anchors in `templates/README_EXTRA.template.md` (they use trailing `-` anchors)
3. Any static assets that embed text (for example, card SVGs)

## Adding a New README Style

1. Create a template file in `templates/` (for example, `README_NEWSTYLE.template.md`)
2. Add a generator class extending `ReadmeGenerator` under `scripts/readme/generators/`
3. Register the class in `STYLE_GENERATORS` in `scripts/readme/generate_readme.py`
4. Create a style selector badge in `assets/badge-style-newstyle.svg`
5. Add the style to `acc-config.yaml`:
   - Add an entry under `styles:` with name, badge, highlight_color, filename
   - Add the style ID to `style_order:`
6. Ensure your template includes `{{STYLE_SELECTOR}}`

## Generator Architecture

The generator uses a class-based architecture with the Template Method pattern.
Generator classes live under `scripts/readme/generators/` and are wired in
`scripts/readme/generate_readme.py`:

```
ReadmeGenerator (ABC)
├── VisualReadmeGenerator      → README_ALTERNATIVES/README_EXTRA.md
├── MinimalReadmeGenerator     → README_ALTERNATIVES/README_CLASSIC.md
├── AwesomeReadmeGenerator     → README_ALTERNATIVES/README_AWESOME.md
└── ParameterizedFlatListGenerator → README_ALTERNATIVES/README_FLAT_*.md (44 files)

The `root_style` also gets an additional copy written to `README.md`.
```

### Category Management

Categories can be managed via `scripts/categories/category_utils.py` (experimental):

```python
from scripts.categories.category_utils import category_manager

# Get all categories
categories = category_manager.get_categories_for_readme()

# Get category by name
cat = category_manager.get_category_by_name("Tooling")
```

### Template Placeholders

Templates use `{{PLACEHOLDER}}` syntax for dynamic content. Key placeholders:

| Placeholder | Description | Generator Method |
|-------------|-------------|------------------|
| `{{ASSET_PATH('file.svg')}}` | Tokenized asset path resolved per output location | `resolve_asset_tokens()` |
| `{{STYLE_SELECTOR}}` | "Pick Your Style" badge row linking to all README variants | `get_style_selector()` |
| `{{REPO_TICKER}}` | Animated SVG ticker showing featured projects | `generate_repo_ticker()` |
| `{{ANNOUNCEMENTS}}` | Latest announcements from `templates/announcements.yaml` | `load_announcements()` |
| `{{WEEKLY_SECTION}}` | Latest additions section | `generate_weekly_section()` |
| `{{TABLE_OF_CONTENTS}}` | Table of contents | `generate_toc()` |
| `{{BODY_SECTIONS}}` | Main resource listings | `generate_section_content()` |
| `{{FOOTER}}` | Footer template content | `load_footer()` |

Template content outside these placeholders is treated as manual copy and is not regenerated.

Asset references use token placeholders (e.g. `{{ASSET_PATH('logo.svg')}}`) that are resolved after templating based on the destination README path. Resolution walks upward to the repo root (`pyproject.toml`)

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/readme-generation) · https://claudary.paisolsolutions.com