diff --git a/README.md b/README.md index 5be6bcb5..26a452e5 100644 --- a/README.md +++ b/README.md @@ -1,902 +1 @@ -
-

🌐 NextCommunity Developer Directory

- -[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE) -[![Built with Eleventy](https://img.shields.io/badge/Built%20with-Eleventy-black)](https://www.11ty.dev/) -[![Run JavaScript Everywhere](https://img.shields.io/badge/Run%20JavaScript%20Everywhere-yellow)](https://nodejs.org/en) -[![Built with Nunjucks](https://img.shields.io/badge/Built%20with-Nunjucks-darkgreen)](https://mozilla.github.io/nunjucks/) -[![Built with Tailwind CSS](https://img.shields.io/badge/Built%20with-Tailwind-blue)](https://tailwindcss.com/) - -[![Super-Linter](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/super-linter.yml/badge.svg?branch=main)](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/super-linter.yml?query=branch%3Amain) -[![Audit hooks](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/prek-audit.yml/badge.svg?branch=main)](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/prek-audit.yml?query=branch%3Amain) -[![Manual hooks](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/prek-manual.yml/badge.svg?branch=main)](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/prek-manual.yml?query=branch%3Amain) -[![Standard hooks](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/prek.yml/badge.svg?branch=main)](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/prek.yml?query=branch%3Amain) -[![ls-lint](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/ls-lint.yml/badge.svg?branch=main)](https://github.com/NextCommunity/NextCommunity.github.io/actions/workflows/ls-lint.yml?query=branch%3Amain) - -[![Easter Eggs](https://img.shields.io/badge/Easter-Eggs-ff69b4?labelColor=9b59b6)](https://nextcommunity.github.io) - -> A vibrant community directory showcasing open-source developers and software engineers from around the world. - -**πŸ”— Live Site:** [https://nextcommunity.github.io](https://nextcommunity.github.io) - -
- ---- - -## πŸ“‹ Table of Contents - - - - -- [🎯 About the Project](#-about-the-project) - - [πŸ› οΈ Tech Stack](#-tech-stack) - - [✨ Features](#-features) -- [πŸš€ How to Add Yourself](#-how-to-add-yourself) - - [Step 1: Fork the Repository](#step-1-fork-the-repository) - - [Step 2: Clone Your Fork and Set Up Upstream](#step-2-clone-your-fork-and-set-up-upstream) - - [Step 3: Create a Feature Branch](#step-3-create-a-feature-branch) - - [Step 4: Create Your Profile File](#step-4-create-your-profile-file) - - [Step 5: Fill In Your Details](#step-5-fill-in-your-details) - - [Step 6: Test Locally (Optional but Recommended)](#step-6-test-locally-optional-but-recommended) - - [Step 7: Commit Your Changes](#step-7-commit-your-changes) - - [Step 8: Create a Pull Request](#step-8-create-a-pull-request) - - [Step 9: Wait for Review ⏳](#step-9-wait-for-review-) -- [πŸ“ YAML File Format](#-yaml-file-format) - - [Required Fields](#required-fields) - - [Optional Fields](#optional-fields) - - [Field Guidelines](#field-guidelines) - - [πŸ“š Real Examples](#-real-examples) -- [πŸ’» Local Development (Optional)](#-local-development-optional) - - [Prerequisites](#prerequisites) - - [Installation](#installation) - - [Build Commands](#build-commands) - - [Quality Checks with prek](#quality-checks-with-prek) - - [Project Structure](#project-structure) -- [🀝 Contribution Guidelines](#-contribution-guidelines) - - [Code of Conduct](#code-of-conduct) - - [PR Review Process](#pr-review-process) - - [What Gets Approved?](#what-gets-approved) - - [CI/CD Checks](#cicd-checks) -- [πŸ”§ Troubleshooting & FAQ](#-troubleshooting--faq) - - [Common Issues](#common-issues) - - [❌ Build Fails: "Invalid YAML"](#-build-fails-invalid-yaml) - - [❌ "GitHub username not found"](#-github-username-not-found) - - [❌ My profile doesn't show up](#-my-profile-doesnt-show-up) - - [❌ prek hooks fail](#-prek-hooks-fail) - - [FAQ](#faq) -- [πŸ”€ Git Workflow & Keeping in Sync](#-git-workflow--keeping-in-sync) - - [The Golden Rules](#the-golden-rules) - - [πŸ› οΈ Essential Git Commands for Contributors](#-essential-git-commands-for-contributors) - - [1. `git remote` β€” Manage your remote connections](#1-git-remote--manage-your-remote-connections) - - [2. `git fetch` β€” Download changes without merging](#2-git-fetch--download-changes-without-merging) - - [3. `git pull` β€” Fetch and integrate in one step](#3-git-pull--fetch-and-integrate-in-one-step) - - [4. `git checkout -b` β€” Create and switch to a feature branch](#4-git-checkout--b--create-and-switch-to-a-feature-branch) - - [5. `git rebase` β€” Replay your commits on top of the latest upstream](#5-git-rebase--replay-your-commits-on-top-of-the-latest-upstream) - - [6. `git stash` β€” Save work-in-progress without committing](#6-git-stash--save-work-in-progress-without-committing) - - [7. `git log` β€” Explore commit history](#7-git-log--explore-commit-history) - - [πŸ”„ Full Day-to-Day Sync Workflow](#-full-day-to-day-sync-workflow) -- [πŸ–₯️ Contributing with GitHub CLI](#-contributing-with-github-cli) - - [Step 1: Fork the Repository](#step-1-fork-the-repository-1) - - [Step 2: Create a Feature Branch](#step-2-create-a-feature-branch) - - [Step 3: Create Your Profile File](#step-3-create-your-profile-file) - - [Step 4: Test Locally (Optional but Recommended)](#step-4-test-locally-optional-but-recommended) - - [Step 5: Commit and Push](#step-5-commit-and-push) - - [Step 6: Open a Pull Request with `gh`](#step-6-open-a-pull-request-with-gh) - - [Step 7: Monitor CI and Respond to Feedback](#step-7-monitor-ci-and-respond-to-feedback) -- [πŸ“„ License](#-license) - - [What this means](#what-this-means) -- [πŸ™ Acknowledgments](#-acknowledgments) -- [πŸ“ž Contact & Support](#-contact--support) - - - ---- - -## 🎯 About the Project - -NextCommunity is a static site directory built with Eleventy (11ty), JavaScript, Nunjucks and TailwindCSS. -NextCommunity celebrates the global developer community. Each developer gets their own profile page -showcasing their skills, bio, and social links. - -### πŸ› οΈ Tech Stack - -- **Interactivity**: [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript) -- **Static Site Generator**: [Eleventy (11ty)](https://www.11ty.dev/) -- **Styling**: [TailwindCSS](https://tailwindcss.com/) -- **Templating**: [Nunjucks](https://mozilla.github.io/nunjucks/) -- **Data Format**: [JSON](https://www.json.org/json-en.html) / [YAML](https://yaml.org/) -- **Deployment**: [GitHub Pages](https://docs.github.com/en/pages) - -### ✨ Features - -- 🎲 Randomized display of developer profiles on build -- πŸŒ“ Dark/Light/Random theme support -- πŸ“± Fully responsive design -- πŸ” Individual profile pages for each developer -- 🎨 Modern, premium UI with smooth animations - ---- - -## πŸš€ How to Add Yourself - -Adding yourself to the directory is simple! Just follow these steps: - -### Step 1: Fork the Repository - -1. Click the **"Fork"** button at the top-right of this repository -2. This creates a copy of the repository under your GitHub account - -### Step 2: Clone Your Fork and Set Up Upstream - -```bash -# Clone your fork -git clone https://github.com/YOUR-USERNAME/NextCommunity.github.io.git -cd NextCommunity.github.io - -# Add the original repo as "upstream" so you can sync future changes -git remote add upstream https://github.com/NextCommunity/NextCommunity.github.io.git - -# Verify your remotes (you should see both origin and upstream) -git remote -v -``` - -Replace `YOUR-USERNAME` with your actual GitHub username. - -### Step 3: Create a Feature Branch - -**Never commit directly to `main`.** Always work on a dedicated feature branch: - -```bash -# Make sure your local main is up to date first -git checkout main -git pull upstream main - -# Create and switch to a new feature branch -git checkout -b my-feature-branch -``` - -Use a descriptive branch name that reflects your change, e.g. `add-jbampton` or `fix-yaml-typo`. - -### Step 4: Create Your Profile File - -1. Navigate to the `src/users/` directory -2. Create a new file named `your-github-username.yaml` - - **Important**: Use your actual GitHub username in lowercase - - Example: If your GitHub username is `JohnDoe`, create `johndoe.yaml` - -### Step 5: Fill In Your Details - -Copy the template below and customize it with your information: - -```yaml -name: Your Full Name -github: your-github-username -website: https://yourwebsite.com -email: your.email@example.com -instagram: https://instagram.com/yourusername -twitter: https://twitter.com/yourhandle -linkedin: https://linkedin.com/in/yourprofile -country: Your Country -location: Your City -role: Your Professional Title -languages: JavaScript Python Go Rust -bio: | - Write your professional bio here. - You can use multiple lines. - Share your experience, interests, and what you're passionate about. - - Add your skills, projects, or anything else you'd like to highlight! -``` - -> πŸ’‘ **Tip**: Check out existing files in `src/users/` for real examples! - -### Step 6: Test Locally (Optional but Recommended) - -```bash -# Install dependencies -npm install - -# Start the development server -npm start -``` - -Visit `http://localhost:8080` to preview your profile before submitting. - -### Step 7: Commit Your Changes - -```bash -# Add your new file -git add src/users/your-github-username.yaml - -# Commit with a descriptive message -git commit -m "Add [Your Name] to developer directory" - -# Push your feature branch to your fork (NOT main!) -# Replace 'my-feature-branch' with the branch name you created in Step 3 -git push origin my-feature-branch -``` - -### Step 8: Create a Pull Request - -1. Go to your forked repository on GitHub -2. Click the **"Contribute"** button, then **"Open Pull Request"** -3. Make sure the **base** branch is `main` on `NextCommunity/NextCommunity.github.io` and the **compare** branch is your feature branch -4. Write a clear title: `Add [Your Name] to directory` -5. In the description, mention: - - ```markdown - Fixes #213 - - Adding my profile to the NextCommunity developer directory. - ``` - -6. Click **"Create Pull Request"** - -### Step 9: Wait for Review ⏳ - -- The maintainers will review your PR -- Automated checks will verify your YAML file -- You may receive feedback or requested changes -- Once approved, your profile will be merged and live! πŸŽ‰ - ---- - -## πŸ“ YAML File Format - -### Required Fields - -| Field | Description | Example | -| ----------- | ------------------------------------ | -------------------------- | -| `name` | Your full name | `John Bampton` | -| `github` | Your GitHub username (without @) | `jbampton` | -| `country` | Your country | `Australia` | -| `location` | Your city | `Brisbane` | -| `role` | Your professional title | `Scrum Master` | -| `languages` | Space-separated list of technologies | `JavaScript, Python, Ruby` | -| `bio` | Multi-line biography | See template above | - -### Optional Fields - -| Field | Description | Example | -| ----------- | -------------------------- | ---------------------------------- | -| `email` | Your email address | `you@example.com` | -| `instagram` | Full Instagram profile URL | `https://instagram.com/username` | -| `linkedin` | Full LinkedIn profile URL | `https://linkedin.com/in/username` | -| `twitter` | Full Twitter/X profile URL | `https://twitter.com/username` | -| `website` | Your personal website URL | `https://yoursite.com` | - -### Field Guidelines - -- **`name`**: Use your real name or preferred professional name -- **`github`**: Must match your actual GitHub username for links to work -- **`languages`**: Separate with spaces, not commas (e.g., `Python Java Go`) -- **`bio`**: Use the `|` syntax for multi-line text. Be professional and concise -- **`role`**: Keep it short and clear (e.g., "Full Stack Developer", "DevOps Engineer") - -### πŸ“š Real Examples - -**Example 1: Minimal Profile** - -```yaml -name: Jane Smith -github: janesmith -country: USA -location: San Francisco -role: Backend Developer -languages: Python Django PostgreSQL -bio: | - Passionate backend developer with 3 years of experience. - Love working with Python and building scalable APIs. -``` - -**Example 2: Complete Profile** - -```yaml -name: Carlos Rodriguez -github: carlosr -website: https://carlos.dev -email: carlos@example.com -twitter: https://twitter.com/carlos_codes -linkedin: https://linkedin.com/in/carlosrodriguez -country: Spain -location: Barcelona -role: Full Stack Engineer -languages: TypeScript React Node.js AWS -bio: | - Full-stack engineer specializing in modern web technologies. - - Currently building cloud-native applications and contributing to open source. - Passionate about clean code, testing, and developer experience. -``` - ---- - -## πŸ’» Local Development (Optional) - -Want to contribute to the project code or test your profile locally? Here's how to set up the development environment. - -### Prerequisites - -- **Node.js**: Version 22.x or higher ([Download](https://nodejs.org/)); check the Node.js release EOL schedule at [endoflife.date/nodejs](https://endoflife.date/nodejs) -- **npm**: Comes with Node.js -- **Python**: Optional; use version 3.13 or higher if you want to provide your own interpreter for the repository's `uv sync`-managed dev tools -- **uv**: Recommended for installing Python dev tools and can download a compatible Python version when needed -- **Git**: For version control - -### Installation - -```bash -# Clone the repository -git clone https://github.com/NextCommunity/NextCommunity.github.io.git -cd NextCommunity.github.io - -# Install dependencies -npm install - -# Start the development server -npm start -``` - -The site will be available at `http://localhost:8080` with live reload enabled. - -### Build Commands - -```bash -# Start development server with live reload -npm start - -# Build for production -npm run build -``` - -### Quality Checks with prek - -This repository uses [prek](https://github.com/j178/prek) to run its local quality checks and Git hooks from `.pre-commit-config.yaml`. - -If Python 3.13+ is not already installed, `uv` can download a compatible version for these commands. - -```bash -# Install Python dev tools, including prek -uv sync --only-group dev - -# Install Git hooks in your clone -uv run prek install - -# Run the standard hooks across the repository -uv run prek run --all-files - -# Run the manual hooks when needed -uv run prek run --all-files --hook-stage manual -``` - -### Project Structure - -```text -NextCommunity.github.io/ -β”œβ”€β”€ .github/ -β”‚ β”œβ”€β”€ linters/ -β”‚ β”‚ β”œβ”€β”€ .markdown-lint.yml # Markdown linting rules -β”‚ β”‚ β”œβ”€β”€ .markdown-link-check.json # Markdown link checker config -β”‚ β”‚ β”œβ”€β”€ .yaml-lint.yml # YAML linting rules -β”‚ β”‚ β”œβ”€β”€ codespell.txt # Accepted words for spell checks -β”‚ β”‚ └── zizmor.yml # GitHub Actions security lint config -β”‚ β”œβ”€β”€ workflows/ -β”‚ β”‚ β”œβ”€β”€ deploy.yml # Production deployment workflow -β”‚ β”‚ β”œβ”€β”€ firebase-hosting-merge.yml # Firebase deploy on merge -β”‚ β”‚ β”œβ”€β”€ firebase-hosting-pull-request.yml # Firebase preview deploys for PRs -β”‚ β”‚ β”œβ”€β”€ prek-audit.yml # prek audit workflow -β”‚ β”‚ β”œβ”€β”€ prek-manual.yml # Manual prek workflow -β”‚ β”‚ β”œβ”€β”€ prek.yml # Standard prek workflow -β”‚ β”‚ └── super-linter.yml # Super-linter workflow -β”‚ β”œβ”€β”€ CODEOWNERS # Code ownership rules -β”‚ β”œβ”€β”€ dependabot.yml # Dependabot configuration -β”‚ └── FUNDING.yml # Sponsorship links -β”œβ”€β”€ src/ -β”‚ β”œβ”€β”€ _data/ # Site-wide data files -β”‚ β”‚ β”œβ”€β”€ build.js # Build metadata injected into templates -β”‚ β”‚ β”œβ”€β”€ levels.json # XP level definitions for gamification -β”‚ β”‚ └── site.js # Global site metadata -β”‚ β”œβ”€β”€ _includes/ # Reusable Nunjucks templates -β”‚ β”‚ β”œβ”€β”€ bio.njk # Individual developer profile layout -β”‚ β”‚ β”œβ”€β”€ footer.njk # Site footer wrapper -β”‚ β”‚ β”œβ”€β”€ footer-details.njk # Footer content (links, credits) -β”‚ β”‚ β”œβ”€β”€ game-modal.njk # Modal overlay for mini-games -β”‚ β”‚ β”œβ”€β”€ game-stats.njk # In-game XP / stats display -β”‚ β”‚ β”œβ”€β”€ github-ribbon.njk # "Fork me on GitHub" ribbon include -β”‚ β”‚ β”œβ”€β”€ header.njk # Site header wrapper -β”‚ β”‚ β”œβ”€β”€ header-details.njk # Header content (nav, theme toggle) -β”‚ β”‚ β”œβ”€β”€ layouts/ -β”‚ β”‚ β”‚ └── base.njk # Base page layout wrapper -β”‚ β”‚ β”œβ”€β”€ matrix-overlay.njk # Matrix rain easter egg overlay -β”‚ β”‚ β”œβ”€β”€ seo-meta.njk # SEO/Open Graph metadata tags -β”‚ β”‚ β”œβ”€β”€ scripts.njk # JS