---
domd-id: 13614fae-a58c-4174-8f85-ea394f985388
---

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

This is the **content directory** for [subfolio-astro](../subfolio-astro) — a portfolio site where structure and metadata are authored entirely through file-naming conventions. There is no database, no CMS, and no build step in this repo. The Astro project in `../subfolio-astro` reads this directory at build time via its custom content loader.

## How content is authored

Each subfolder is a portfolio project (e.g., `k2/`, `puma/`). Files within it are interpreted by their names and extensions — not their paths in any config file.

### Position prefixes (embeds)

Files prefixed `-t-`, `-m-`, or `-b-` are injected into the **top**, **middle**, or **bottom** zones of a listing page, in alphabetical order within each zone:

- `-t-00-intro.txt` — Markdown/HTML text rendered at the top
- `-t-01-hero.png` — image displayed at the top after the text
- `-m-screenshot.png` — image in the middle zone
- `-b-footer.txt` — text at the bottom

The numeric part after the prefix (`00`, `01`, `02`…) controls sort order within the zone.

### Enhancer extensions

Files with these extensions attach metadata to their sibling folder or file:

| Extension | Purpose | Key YAML fields |
|---|---|---|
| `.info` | Comment on a file/folder | `comment:` |
| `.link` | External link (replaces file with redirect) | `url:`, `target:`, `comment:` |
| `.pop` | Popup window | `url:`, `width:`, `height:`, `style:` |
| `.cut` | Shortcut to another folder | `name:`, `directory:` |
| `.ftr` | Feature card (promotes an item visually) | `title:`, `folder:` or `link:`, `image:`, `width:`, `height:`, `description:` |
| `.rss` | RSS feed embed | `feedurl:`, `count:`, `cache:` |

### Folder suffixes (special views)

Appending a suffix to a folder name changes how Astro renders it:

- `foldername.slide` — renders as a slideshow
- `foldername.site` — renders as a single mini-site view
- `foldername.oplx` — renders as an Oplx project plan view

### Hidden items

- Prefix a folder name with `-hidden` or `.` to exclude it from listings while still allowing shortcuts (`.cut`) to reference it.
- Files with enhancer extensions (`.ftr`, `.cut`, `.link`, `.pop`, `.info`, `.rss`) are excluded from plain file listings automatically.

### Thumbnails

- `-thumbnails/` — auto-generated thumbnails directory (managed by `../subfolio-astro`'s `gen-thumbs` script)
- `-thumbnails-custom/` — manually placed custom thumbnails referenced by `.ftr` enhancers

### Header images

Files prefixed `-hdr` (e.g., `-hdr.png`, `-hdr-the-corner.png`) serve as the folder's header/hero image.

## YAML authoring rules

All enhancer files (`.info`, `.link`, `.pop`, `.cut`, `.ftr`, `.rss`) use YAML with legacy Subfolio quirks:

- Files **must be UTF-8 encoded**
- Indentation, spacing, and text case are significant
- Multi-line descriptions use the legacy Spyc folded-scalar marker: `description:>` (no space before `>`) with a leading space on each body line — this differs from standard YAML `description: >` and is normalized by the loader
- Lines starting with `#` are YAML comments and are ignored by the parser

## Connecting to the Astro project

To preview this content locally:

```sh
# In ../subfolio-astro
SUBFOLIO_CONTENT_DIR=/path/to/subfolio-astro-content ./dev-content.sh
# or set SUBFOLIO_CONTENT_DIR in ../subfolio-astro/.env and run ./dev-content.sh
```

The `examples/` folder in `../subfolio-astro/content/examples/` is the bundled fixture that exercises every convention — it is the canonical reference for how naming conventions behave.