Contribution guide
Content is data here
There is no CMS and no markdown to guess at. Pages are rendered from typed objects, so a contributor edits a data file and the UI picks it up: navigation, counts, search, filters and cross-links all derive from the same entry.
Add a tool
Eight steps, in order.
- 1Create src/data/tools/<slug>.ts exporting a single typed `Tool` object.
- 2Set `category` and `subcategory` to existing slugs — add a subcategory in src/data/categories.ts first if the topic is genuinely new.
- 3Fill `installation` per platform. A method that needs sudo or Administrator must set requiresElevation.
- 4Add `commands` with `title`, `description` and `command` for each. A command without a description is rejected in review.
- 5Record `commonErrors`, `tips`, `alternatives` and `relatedTools` by slug so cross-links resolve automatically.
- 6List `references`: official docs, the repository, the man page. Content without a source stays unverified.
- 7Export the object from src/data/tools/index.ts and add it to RAW_TOOLS.
- 8Run the type check and build; the data model will catch most omissions for you.
Writing a command entry
The bar is simple: a reader must understand what the command does, when it needs privileges, and how to read the output.
{
id: "service-version",
title: "Service version detection",
description: "Probes each open port and reports the banner or fingerprint it receives.",
command: "nmap -sV 192.0.2.10",
shell: "bash",
notes: ["Version probes can disturb fragile embedded services."],
}- Do — Use documentation addresses (192.0.2.0/24, 203.0.113.0/24) in examples.
- Do — Mark privileges: requiresElevation on an install method, warnings[] on a command.
- Don't — Copy the manual. Summarise and link.
- Don't — Invent versions, dates, star counts or benchmarks.
Data model at a glance
Everything lives in src/types; components never invent their own shape.
Command
src/types/common.ts
id, title, description, command, shell, platform, difficulty, example, expectedOutput, notes[], warnings[], tags[]
InstallationMethod
src/types/common.ts
platform, method, title, kind (recommended|alternative|manual), commands[], requirements[], notes[], requiresElevation, official, sourceUrl
Roadmap / RoadmapStage
src/types/learning.ts
stages carry topics (optionally linking to internal pages), tools by slug, exercises and resources
Comparison
src/types/learning.ts
features[] grouped by a `group` string; values may be boolean, string, or { text, note }
Frontend contributions
Components are primitives, pages are compositions, and design tokens live in one file.
- Tokens: src/app/globals.css declares every colour, font and motion. Components use semantic classes (bg-card, border-line, text-ink-soft) — raw hex in a component is a review comment.
- Primitives: Button, Card, Badge, Tabs, Callout, Disclosure, CodeSurface, States. Reuse them instead of restyling locally.
- Motion: transform and opacity only, under 200 ms for micro-interactions, and every decorative animation is switched off by the prefers-reduced-motion block.
- Breakpoints: each component decides where it reflows. Tool grids go 1 → 2 → 3 → 4; the docs sidebar only exists at lg and above.
- Accessibility: real buttons and links, labelled dialogs, focus trapped in overlays, visible focus ring, no state communicated by colour alone.