The README usually begins as an invitation: what this project is, why it exists, and how to try it.
Then the project survives.
Results arrive. Architecture decisions need a home. A workshop talk becomes a long explanation. There are three related tools now, not one. Someone asks for API reference. Another person wants the reasoning behind a failed approach. The README becomes a table of contents, a release log, a portfolio, a manual, and a graveyard of links—all while remaining the first page a new reader is expected to understand.
The failure is not insufficient Markdown. It is insufficient information architecture.
TidyPress exists because a repository can be a body of work, not merely a unit of software. A body of work needs several reader promises without becoming several disconnected websites.
Folders locate files. Public surfaces tell a reader what kind of answer each file provides.
Consider a small research lab
Imagine a lab maintaining an open-source analysis package. Its repository may contain all of these:
- the package and its API;
- a reproducible experiment;
- a notebook with intermediate analysis;
- a result worth explaining to people outside the lab;
- two utilities built along the way;
- an architectural decision about data retention;
- onboarding instructions for a new collaborator;
- a short biography and contact page.
GitHub can store all of it. Storage is not the problem. The problem is that each visitor arrives with a different question.
A user asks, “How do I install this?” A reviewer asks, “What evidence supports the result?” A potential collaborator asks, “What kind of work does this lab do?” A future maintainer asks, “Why was this dependency chosen?” A coding agent asks, “Which files define the public API?”
One enormous README cannot answer those questions in the order each reader needs. A collection can.
Collections are reading contracts
TidyPress separates the name of a collection from its behavioral kind. The project chooses words that fit its work; the framework supplies tested reading behavior.
collections: {
works: { kind: 'projects', basePath: '/work' },
tools: { kind: 'projects', basePath: '/tools' },
notes: { kind: 'writing', basePath: '/notes' },
reference: { kind: 'content', basePath: '/reference' },
process: { kind: 'content', basePath: '/process' },
}works and tools can share project behavior while speaking the lab’s own
language. notes can use dated-writing behavior without being forced to call
itself a blog. reference and process can share a navigable content shell
while making different editorial promises.
This distinction prevents two common mistakes. A rigid framework forces every project to adopt its vocabulary. A folder-only generator makes every new word a custom programming job. Keys and kinds let the publication remain personal without rebuilding common behavior.
Each surface answers a different question
The body-of-work starter uses six surfaces because they correspond to stable
reader needs:
| Surface | The question it answers |
|---|---|
| Works | What outcomes are you proud enough to explain? |
| Projects | What tools, experiments, or repositories can I try? |
| Writing | What have you learned, argued, or changed your mind about? |
| Reference | What exact facts will I need while working? |
| Process | Why was this decision made, and what happened next? |
| Pages | Who are you, what are you doing now, and how can I reach you? |
Product documentation is separate because it has a different job again:
helping a user succeed through tutorials, tasks, explanation, and reference.
The body-of-work-docs starter combines both when one site needs them.
The point is not to fill every shelf. Empty collections can stay disabled. The point is to avoid making one page impersonate every content type.
Metadata must create behavior
A tag that only decorates a card is not doing enough work.
In TidyPress writing, tags create actual archive routes and also define the
candidate graph for related-post navigation. An author name creates an author
archive. A date orders the feed, supplies reading context, and creates year
archives. A project’s status, url, and featured fields affect how the work
is presented rather than remaining hidden database trivia.
This produces an important feeling for the reader: the publication has memory.
Clicking research-methods does not run a temporary client-side filter; it opens
a stable page containing the published work in that cluster. Following an
author does not search text; it opens that author’s body of writing.
Meaningful metadata becomes navigation.
One site should not mean one template
Many portfolio tools solve fragmentation by flattening everything into cards. A paper, a library, an essay, and a status update become the same rectangle with a title and link. The site looks consistent because it has erased what made the items different.
TidyPress aims for coherence without sameness:
- project indexes emphasize outcomes, status, and destinations;
- writing indexes emphasize chronology, authorship, tags, and reading;
- documentation exposes hierarchy and task progress;
- reference and process remain searchable bodies of knowledge;
- root pages hold identity and contact without becoming collections.
They share a navigation system, visual language, search index, domain, and build artifact. They do not have to share a single page model.
The homepage becomes an editorial decision
Once the work has types, the homepage can show what matters instead of listing everything. A lab may lead with two major works, then active tools, then recent notes. An independent engineer may lead with projects and writing. A devtool may lead with documentation and a changelog.
The body-of-work preset deliberately leaves reference and process out of the primary header by default. Those shelves remain available through quieter navigation because not every useful surface deserves equal visual weight.
That is the kind of decision a README cannot express. A README has one order. A public interface can establish several paths through the same source.
What this does not solve
Information architecture cannot create substance. Six empty collections are worse than one clear page. A project still needs judgment about what deserves a case study, which experiment is reproducible, when a note has become an essay, and whether an old decision remains useful.
TidyPress also does not turn arbitrary repository files into a meaningful site by guessing. The author chooses which work becomes public and supplies the context a reader needs. Automation can assist that process; it cannot replace the editorial decision.
The framework’s job is narrower: when the work is ready, it should have an obvious home, a stable URL, a presentation suited to its meaning, and a place in the larger publication.
A repository can be more than a project page
The common advice is to make a portfolio separate from the work. Copy the final result into a card, add a sentence, and link back to GitHub.
That loses the most interesting part: the relationship between what was built, what was learned, why it changed, how to use it, and what came next.
When those records remain in one repository and one public interface, a reader can move from result to method, from method to tool, and from tool to reference without crossing a set of disconnected publishing systems.
The README can return to being a good README. The body of work finally gets a structure large enough to tell the truth about it.