Code Map
A generated CODEMAP.md that says what each area of the repository is for and which local README to open next — a navigation guide, not a reference.
- Kind
- Architecture
- Domain
- Documentation & Metadata
- Applies at
CODEMAP.md- Status
- Stable
- Source · managed
CODEMAP.md
01 Defines
A single generated page at the repository root that shows the expected shape of the tree, gives a quick lookup from concern to directory, and points each area at its own owner documentation.
02 Applies when
- A new contributor needs to find where something lives before reading any area in depth.
- A repository follows a shared layout and only uses some of its areas.
- Area documentation exists and needs a single entry point.
03 Boundaries
- The code map says what an area is for and where to go next; detail stays in the area’s
README.md. - The tree is the shape the conventions expect, not a literal directory listing.
- The file is generated from the repository structure and is not edited by hand.
Expected behaviour
- 01Only the areas the repository actually has appear; an unused area is simply absent.
- 02Placeholders in angle brackets stand for whatever a repository puts there.
- 03A Quick Lookup list maps each concern to its directory.
- 04Each area section ends with “Read:” links to that area’s owner documentation.
Behaviour#
The code map is the first page to open and the shortest route to the right second page. It is organised in three layers, each more specific than the last, and every layer hands off to owner documentation instead of growing its own detail.
- 01 Structure An annotated tree of the shape the conventions expect
- 02
Quick Lookup
One line per concern: Static Websites →
www, Command Surface →Makefile - 03 Area sections A short paragraph on what the area is for, then “Read:” links
- 04
Owner documentation
The area’s own
README.mdcarries the rules and detail Owner Documentation
Because it is generated from the repository structure, the code map changes when the tree changes. That is what keeps it from drifting: a hand-written map is the first document to fall out of date when areas are added or removed.
Grouping#
Area sections are grouped by concern so a reader can skip whole categories:
| Group | Areas |
|---|---|
| Product Code | Static Websites |
| Infrastructure And Runtime | Deployable Infrastructure, Reusable Modules, Developer Runtime Workspaces |
| Development Environment And Tooling | Development Container, Command Surface, Command Helpers, Tools, Linting, CI |
| Documentation And Metadata | Documentation, Product Development Life Cycle, Catalog Metadata |
Examples#
Each area section is two or three sentences and a list of links:
### Continuous Integration
Workflow and action definitions live under `.gitea/`. Workflows orchestrate
the repository commands; they should not reimplement the work those commands do.
Read:
The Read: list that follows links each owner README.md in the area —
.gitea/README.md, .gitea/workflows/README.md, and .gitea/actions/README.md
— so the map hands the reader on rather than repeating what those files say.
The page states its own limit near the top: “This page only says what each area is for and where to go next.”
Connections