A vibrant community directory showcasing open-source developers and software engineers from around the world.

🔗 Live Site: https://nextcommunity.github.io

📋 Table of Contents

🎯 About the Project

🛠️ Tech Stack

✨ Features

🚀 How to Add Yourself

Step 1: Fork the Repository

Step 2: Clone Your Fork and Set Up Upstream

# 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

Step 3: Create a Feature Branch

# 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

Step 4: Create Your Profile File

Step 5: Fill In Your Details

name: Your Full Name
github: your-github-username
website: https://yourwebsite.com
email: [email protected]
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!

Step 6: Test Locally (Optional but Recommended)

# Install dependencies
npm install

# Start the development server
npm start

Step 7: Commit Your Changes

# 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

Step 9: Wait for Review ⏳

📝 YAML File Format

Required Fields

Optional Fields

Field Guidelines

📚 Real Examples

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.

name: Carlos Rodriguez
github: carlosr
website: https://carlos.dev
email: [email protected]
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)

Prerequisites

Installation

# 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

Build Commands

# Start development server with live reload
npm start

# Build for production
npm run build

Quality Checks with prek

# 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

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 <script> tags included by footer
│   │   ├── skills-list.njk            # Renders a developer's skills/languages
│   │   ├── system-log.njk             # Scrolling system-log UI element
│   │   └── system-override.njk        # "System override" easter egg UI
│   ├── assets/
│   │   ├── css/
│   │   │   ├── style.css              # Custom styles
│   │   │   ├── tailwind-input.css     # Tailwind CSS entry point
│   │   │   └── tailwind.css           # Generated Tailwind CSS output
│   │   ├── img/
│   │   │   ├── github-fork-me.png     # GitHub ribbon image asset
│   │   │   └── next.jpeg              # Site logo / avatar image
│   │   └── js/
│   │       ├── eggs.js                # Easter egg interactions
│   │       ├── phaser-init.js         # Phaser game engine bootstrap
│   │       ├── script.js              # Core interactivity & XP system
│   │       └── games/                 # Mini-game modules
│   │           ├── code-breaker.js    # Code puzzle mini-game
│   │           ├── config.js          # Shared game constants & CDN URL
│   │           ├── dev-duel.js        # Reflex mini-game
│   │           ├── game-manager.js    # Game lifecycle (load/create/destroy)
│   │           └── space-invaders.js  # Shooter mini-game
│   ├── users/                         # 👈 Developer profile YAML files
│   │   ├── users.json                 # Eleventy data file aggregating YAMLs
│   │   ├── jbampton.yaml
│   │   └── ...                        # One <github-username>.yaml per dev
│   ├── games.njk                      # Games page template
│   ├── index.njk                      # Homepage template
│   ├── robots.njk                     # robots.txt template
│   └── sitemap.njk                    # XML sitemap template
├── .editorconfig                      # Editor formatting rules
├── .eleventy.js                       # Eleventy configuration
├── .firebaserc                        # Firebase project alias config
├── .gitattributes                     # Git text normalization rules
├── .gitignore                         # Git ignored files
├── .ls-lint.yml                       # File and directory naming rules
├── .npmrc                             # npm configuration
├── .pre-commit-config-audit.yaml      # prek audit config
├── .pre-commit-config.yaml            # prek hooks config
├── LICENSE                            # Project license
├── biome.json                         # Biome formatter / linter config
├── firebase.json                      # Firebase Hosting configuration
├── package-lock.json                  # Locked npm dependency versions
├── package.json                       # Node.js dependencies & scripts
├── postcss.config.js                  # PostCSS / Tailwind build config
├── pyproject.toml                     # Python tooling config for prek/uv
├── uv.lock                            # Locked Python dev dependencies
└── README.md                          # This documentation

🤝 Contribution Guidelines

Code of Conduct

PR Review Process

What Gets Approved?

CI/CD Checks

🔧 Troubleshooting & FAQ

Common Issues

❌ Build Fails: "Invalid YAML"

❌ "GitHub username not found"

❌ My profile doesn't show up

❌ prek hooks fail

# Install prek
uv sync --only-group dev

# Run checks manually
uv run prek run --all-files

FAQ

🔀 Git Workflow & Keeping in Sync

The Golden Rules

🛠️ Essential Git Commands for Contributors

1. git remote — Manage your remote connections

# View all configured remotes
git remote -v

# Add the upstream remote (do this once, right after cloning)
git remote add upstream https://github.com/NextCommunity/NextCommunity.github.io.git

# After running the above, git remote -v should output:
# origin    https://github.com/YOUR-USERNAME/NextCommunity.github.io.git (fetch)
# origin    https://github.com/YOUR-USERNAME/NextCommunity.github.io.git (push)
# upstream  https://github.com/NextCommunity/NextCommunity.github.io.git (fetch)
# upstream  https://github.com/NextCommunity/NextCommunity.github.io.git (push)

2. git fetch — Download changes without merging

# Fetch everything from the upstream repo
git fetch upstream

# Now you can inspect what changed without affecting your local branches
git log HEAD..upstream/main --oneline

3. git pull — Fetch and integrate in one step

# Sync your local main with upstream/main
git checkout main
git pull upstream main

# Keep your fork's main in sync too (pushes updated main to your fork on GitHub)
git push origin main

4. git checkout -b — Create and switch to a feature branch

# Create a new branch and switch to it
git checkout -b my-feature-branch

# List all local branches (the active branch is marked with *)
git branch

# Switch between existing branches
git checkout main
git checkout my-feature-branch

5. git rebase — Replay your commits on top of the latest upstream

# First, fetch the latest upstream changes
git fetch upstream

# Rebase your feature branch on top of upstream/main
git checkout my-feature-branch
git rebase upstream/main

# 1. Open the conflicting file(s), resolve the conflict markers (<<<<, ====, >>>>)
# 2. Stage the resolved file(s)
git add src/users/your-github-username.yaml

# 3. Continue the rebase
git rebase --continue

# If you want to abort and go back to before the rebase started
git rebase --abort

# Force push — only safe on your own feature branch, NEVER on main
git push origin my-feature-branch --force-with-lease

6. git stash — Save work-in-progress without committing

# Save all uncommitted changes
git stash

# Switch to another branch, do some work, then come back
git checkout main
git pull upstream main
git checkout my-feature-branch

# Restore your stashed changes
git stash pop

# View all stashes
git stash list

# Apply a specific stash without removing it from the stash list
git stash apply stash@{0}

7. git log — Explore commit history

# View the last 10 commits in a compact format
git log --oneline -10

# See a visual branch graph
git log --oneline --graph --decorate --all

# See all commits by a specific author
git log --author="Your Name" --oneline

# See what changed in the last commit
git log -1 --stat

🔄 Full Day-to-Day Sync Workflow

# 1. Switch to main and pull the latest upstream changes
git checkout main
git fetch upstream
git merge upstream/main   # or: git pull upstream main

# 2. Push the updated main to your fork so GitHub is also up to date
git push origin main

# 3. Create a new feature branch from the freshly synced main
git checkout -b my-feature-branch

# 4. Make your changes, then stage and commit them
git add src/users/your-github-username.yaml
git commit -m "Add [Your Name] to developer directory"

# 5. Push your feature branch to your fork on GitHub
git push origin my-feature-branch

# 6. Open a Pull Request on GitHub from your feature branch → NextCommunity/main

git fetch upstream
git rebase upstream/main
git push origin my-feature-branch --force-with-lease

🖥️ Contributing with GitHub CLI

Step 1: Fork the Repository

# Fork the repo and clone it locally in one command
gh repo fork NextCommunity/NextCommunity.github.io --clone=true --remote=true
cd NextCommunity.github.io

Step 2: Create a Feature Branch

# 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 add-your-github-username

Step 3: Create Your Profile File

# Navigate to the users directory and create your YAML file
cp src/users/_template.yaml src/users/your-github-username.yaml

Step 4: Test Locally (Optional but Recommended)

npm install
npm start

Step 5: Commit and Push

# Stage your new profile 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
git push origin add-your-github-username

Step 6: Open a Pull Request with gh

gh pr create \
  --base main \
  --title "Add [Your Name] to directory" \
  --body "Fixes #213

Adding my profile to the NextCommunity developer directory."

Step 7: Monitor CI and Respond to Feedback

# Watch the status of checks on your PR
gh pr checks

# View any review comments left by maintainers
gh pr view --comments

# If changes are requested, edit your file, then commit and push again
git add src/users/your-github-username.yaml
git commit -m "Address review feedback"
git push origin add-your-github-username

📄 License

What this means

🙏 Acknowledgments

📞 Contact & Support