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

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/.

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:

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:

style_order:
  - extra
  - classic
  - flat
  - awesome

Quick Reference

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:

   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:

   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:

   categories:
     - id: my-category
       name: My Category
       icon: "🎯"
       description: Description of this category
       order: 10
       subcategories:
         - id: general
           name: General
   

3. Run the generator:

   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):

   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:

   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:

   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):

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:

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)