Readme of drevendev/beautifulrepo

Tip

Beautiful is not “more decoration.” A strong repository reduces the time from landing on the page to understanding the result, trying it, trusting it, and knowing how to contribute.

Working proof

A real checkout command, not a concept image. The tested Rowcount starter reads a bundled CSV fixture locally. You need Python 3.11+ and Git. Get a checkout:

git clone https://github.com/drevendev/BeautifulRepo.git
cd BeautifulRepo

Then, from the repository root:

python examples/cli-starter/rowcount.py examples/cli-starter/sample.csv

Expected stdout, checked by the example's unit tests:

Data rows: 3

The input CSV and Python implementation are available to inspect. This is a deliberately small count of data records, not a schema validator or a hosted service. No package installation or network access is required. CI runs the examples and checks on Ubuntu (Python 3.11 and 3.14) and Windows (Python 3.14); macOS is not tested.

For a real application of this approach to BeautifulRepo itself, see the README before/after case: fixed revisions, a clean-clone run, horizontal reflow observations at three emulated widths, and contrast measured only for light at 1280 px and dark at 375 px. Keyboard navigation, real 400% zoom and screen readers remain untested.

For an actual before/after documentation diagnostic, run python examples/repository-audit/demo.py from the same root. Its test-backed walkthrough shows four warnings becoming one after README fixes; the fictional input is disclosed, and unresolved license/contribution observations remain visible.

Start here

Your goal	First step	Visible result
Diagnose an existing repository	Run the offline audit and use the repository checklist	Specific findings, not a beauty score
Start a new one	Adapt the README scaffold with the first-success checklist	A reproducible command and an honest scope
Borrow a working example	Choose from five starter types	Real source, tests and exact limitations

The visitor journey

A repository should answer the next question before the reader has to hunt for it.

flowchart LR
    A["1 · Promise<br/>What is this?"] --> B["2 · Evidence<br/>What do I get?"]
    B --> C["3 · First success<br/>Can I try it?"]
    C --> D["4 · Trust<br/>Can I rely on it?"]
    D --> E["5 · Contribute<br/>How can I help?"]

Text alternative: Promise (what is this?) → Evidence (what do I get?) → First success (can I try it?) → Trust (can I rely on it?) → Contribute (how can I help?). Follow the stages in that order.

That sequence is the core BeautifulRepo test. Decoration is optional; a clear path is not.

What you get

📋 Checklists — prioritize clarity, onboarding, trust, accessibility and maintenance.
🧱 Patterns — source-backed examples of what strong repositories do and why it works.
🧰 Templates — reusable README, application, collection, research and security-policy scaffolds with explicit placeholders.
🔎 Tools — small dependency-free checks that keep repository documentation honest.
🖼️ Visual guidance — theme-aware media, useful alt text and evidence-first screenshots.
🧭 Community guidance — contribution and reporting surfaces that do not invent unsupported promises.

See the difference

The PocketDiff before/after page is an explicitly fictional copy and visual-layout exercise. It contrasts vague superlatives and decorative badges with a concrete (illustrative) CSV report, a text alternative and a command transcript. PocketDiff is not an installable or tested CLI.

The design-intent brief explains why the light/dark illustrations fit that imagined reader, what was rejected, and how to replace them with evidence from a real product. For a genuinely runnable result, use the Rowcount command in Working proof instead.

This repository checks itself

BeautifulRepo includes small offline checks instead of relying on “looks good to me.”

From a checkout with Python 3.11+:

python tools/catalog.py
python tools/docs_links.py
python tools/html_navigation.py
python -m unittest discover -s tests -v
python tools/repo_audit.py .

Each command exits with status 0 when the check passes. The tools print a line starting with OK: (the audit prints a summary with 0 error(s)), and the unit tests end with OK. A failure prints ERROR: or a test name with the file to fix.

The same checks run in GitHub Actions. They validate structured catalog metadata, generated catalog drift, repository-owned relative Markdown destinations, and structural regressions in the examples and public repository surfaces.

CI also runs python -I tools/workflow_badges.py --root . --repo drevendev/BeautifulRepo --require-badge to catch a missing local workflow behind the root README's GitHub Actions status badge. This does not verify that CI ran or passed; it only checks the referenced workflow file.

The additional HTML navigation check verifies bounded local HTML links, media assets and section fragments. The additional action-pin check detects workflow SHA/annotation drift against a locally reviewed manifest; it does not verify upstream release signatures or CI success:

python -I tools/action_pins.py --root .

Other repositories can run the audit and both link checks as a GitHub Action pinned to a reviewed commit. See run the checks in your repository. Coding agents can run the same audit through the BeautifulRepo plugin for Claude Code and Codex. See use BeautifulRepo from an agent.

These tools do not claim to be a live-link crawler, complete GitHub Markdown renderer, security scanner, runtime accessibility certification, or repository beauty score. Manual judgement still matters.

Explore the handbook

Keep the three decisions above short. These are the detailed reference routes, not a second copy of the first-screen chooser.

Explain and present: README design, visual README patterns, editorial evidence kit, AI-written README evidence review, repository discoverability.
Adapt an actual starter: CLI guide and example; library guide and example; application guide and example; research/data guide and example; curated-collection guide and example.
Maintain evidence and trust: release notes with a release-note template, maintenance workflow, evidence-led issue triage, offline repository audit, tools and how to run them in your repository's CI or from Claude Code and Codex under the agent ground rules, confidentiality checklist for private repositories, plan-aware private repository guide, internal/private README template and filled fictional internal example, Community safety readiness.
Research and adapt: case studies and their procedure, annotated studies, reviewed sources, programs and community events, README template, application template, library template, research/data template, curated README template, and the roadmap.

Principles

Clarity before decoration. Explain the result before the implementation.
Evidence before badges. A badge must represent a real, relevant fact.
Patterns before imitation. Reuse ideas; verify permissions before copying material.
Useful before exhaustive. Every resource needs a reason to exist and a next action.
Accessible by default. Keep essential information readable without images, animation or color.

Status and contribution

BeautifulRepo is a working handbook, not an exhaustive or independently certified standard. The roadmap distinguishes published guidance from remaining work on real-agent evaluations, additional before/after cases and manually verified visual accessibility. Private-repository guidance and the repository self-check are already published; passing static CI is not evidence of a live model or accessibility test.

Suggestions and small improvements are welcome. Start with CONTRIBUTING.md. Ask questions in Discussions. Please report accessibility barriers through GitHub Issues, and follow the community safety guidance before posting sensitive material.

Public documentation is maintained in English.

For a practical continuity example, see the maintainer handoff recipe: it separates public onboarding from permissions, releases, and private reporting.

License

MIT. Linked projects and their assets retain their own licenses and trademarks. Listing a source does not endorse every claim it makes or relicense its contents.