From 3b622d6948691a04aae07ba89ce9e5c28d581324 Mon Sep 17 00:00:00 2001 From: pwb25 Date: Sun, 26 Jul 2026 20:45:39 +0900 Subject: [PATCH] docs: make README more beginner-friendly Add context on what DevHub is, expand setup steps with plain-language explanations, and describe the purpose of each top-level folder so newcomers can navigate the project without prior context. Also adds the contrib.rocks contributors image as requested in the issue. Closes #51 --- README.md | 65 ++++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 52 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 83cc8d5..f0daeed 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # DevHub -The official website for the DevHub developer community. Built with Next.js, TypeScript, and Tailwind CSS. +DevHub is a developer community focused on helping people learn, build, and connect with other developers. This repository holds the source for [devhub.vercel.app](https://devhub.vercel.app) — the community's website, including the landing page, guides, and resource library. + +New to the project? This README walks you through what's here, how to run it locally, and how the code is organized, so you can start contributing without needing to already know the codebase. + +Built with Next.js, TypeScript, and Tailwind CSS. ## What's in here @@ -31,31 +35,60 @@ The official website for the DevHub developer community. Built with Next.js, Typ - **Icons** - Lucide - **Deployment** - Vercel +If you're new to any of these, you don't need to be an expert to contribute — most changes only touch a small part of the stack at a time. + ## Getting Started -### Prerequisites +Follow these steps to get the site running on your own machine. + +### 1. Check your prerequisites + +You'll need: -- Node.js 18+ -- bun, npm, yarn, or pnpm +- **Node.js 18+** — [download here](https://nodejs.org/) if you don't have it. Run `node -v` to check your current version. +- A package manager: **bun**, **npm**, **yarn**, or **pnpm** (npm comes bundled with Node.js, so that's the easiest option if you're not sure which to pick) -### Setup +### 2. Get the code + +If you plan to contribute, fork this repository first (click **Fork** at the top of the GitHub page), then clone your fork: ```bash -# Clone the repo -git clone https://github.com/open-devhub/website +git clone https://github.com/YOUR_USERNAME/website cd website +``` + +(If you're just running the site locally without contributing, you can clone this repo directly instead.) -# Install dependencies +### 3. Install dependencies + +```bash npm install +``` + +This downloads all the packages the project needs. It may take a minute the first time. + +### 4. Start the dev server -# Start the dev server +```bash npm run dev ``` -Open [http://localhost:3000](http://localhost:3000) and you're in. +### 5. Open it in your browser + +Go to [http://localhost:3000](http://localhost:3000). The page will automatically reload as you edit files. ## Project Structure +Here's a quick orientation to the main folders, in the order you're most likely to touch them: + +- **`app/`** — The pages of the site, using Next.js's App Router. Each folder under `app/` generally maps to a URL path. +- **`components/`** — Reusable React components, split into `home/` (landing page sections), `site/` (shared layout pieces like the navbar and footer), `ui/` (generic building blocks like buttons and dialogs), and `bits/` (visual/animation effects). +- **`content/`** — Site copy and structured data (page listings, resources, community rules) kept separate from the components that render them. +- **`lib/`** — Shared utility code: animations, color helpers, config, and the markdown parser. +- **`hooks/`** — Custom React hooks. + +Full tree, for reference: + ``` ├── 📁 .github │ └── 📁 workflows @@ -158,9 +191,9 @@ Open [http://localhost:3000](http://localhost:3000) and you're in. ## Contributing -We welcome contributions of all kinds: bug fixes, new features, documentation improvements, and design feedback. +We welcome contributions of all kinds: bug fixes, new features, documentation improvements, and design feedback — you don't need to be an expert in the stack to help out. -See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide. The short version: +See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide, including branch naming, commit message conventions, and the PR process. The short version: 1. Fork the repo 2. Create a branch (`git checkout -b feature/your-cool-feature`) @@ -168,7 +201,7 @@ See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full guide. The short version: 4. Run `npm run lint` 5. Open a PR with a clear description -First time contributing to open source? Look for issues tagged [`good first issue`](https://github.com/open-devhub/website/issues?q=is%3Aopen+label%3A%22good+first+issue%22). +First time contributing to open source? Look for issues tagged [`good first issue`](https://github.com/open-devhub/website/issues?q=is%3Aopen+label%3A%22good+first+issue%22) — they're scoped to be approachable even if you've never opened a PR before. ## Scripts @@ -189,3 +222,9 @@ npm run format # Run Prettier ## License Licensed under the GNU GPL v3.0 License. See the [LICENSE](./LICENSE) file for details. + +## Contributors + + + +