Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
236 lines (167 loc) · 6.53 KB

CONTRIBUTING.md

File metadata and controls

236 lines (167 loc) · 6.53 KB

Contributing to Curated Design Resources

To contribute, or not to contribute, that is the question!

Hey there! The future contributor of this lovely project.

I'm sure you will find it quite easy to contribute to the project. You will find step-by-step instructions down below to make it even more easier for you to contribute.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

📋 How It Works

This project uses README.md as the single source of truth for all content. The website automatically generates category pages and resource listings from the README.

  1. Edit README.md - Add/update categories and resources
  2. Run Parser - Convert README to JSON files
  3. Auto-Update - Website reflects changes immediately

✨ Adding New Content

Adding a New Resource

Throughout the instructions, I will use the Tailwind CSS resource as an example.

Step 1: Update README.md

Open the README.md file in your code editor and find the proper section for your resource. Enter the required information as in the example below. You must enter the new resource in alphabetical order in the list.

- [Tailwind CSS](https://tailwindcss.com/): Rapidly build modern websites without ever leaving your HTML.

Format Rules:

  • Use markdown link format: [Title](URL): Description
  • Include a colon (:) after URL before description
  • Keep it in alphabetical order

Step 2: Commit Your Changes

That's it! 🎉 You only need to edit README.md. The JSON files are automatically generated by GitHub Actions when your changes are merged to master.

No need to:

  • ❌ Run npm run parse-readme manually
  • ❌ Commit JSON files
  • ❌ Install dependencies locally

GitHub Actions handles everything automatically!

Commit message format:

Add [Resource Name] --> [Category Name]

Example:

Add [Tailwind CSS] --> [Frontend Design]

Commit only:

  • ✅ README.md (your changes)

JSON files will be auto-generated and committed by GitHub Actions!

🔄 Development Workflow

For Contributors (External)

  1. Fork the repository
  2. Clone your fork locally
  3. Create a new branch for your contribution
  4. Edit README.md with your changes
  5. Commit only README.md
  6. Push to your fork
  7. Create a Pull Request

Important: You only need to commit README.md. The JSON files will be automatically generated by GitHub Actions after your PR is merged!

Optional: If you want to preview your changes locally, you can install dependencies and run the dev server:

npm install
npm run parse-readme  # Generate JSON files locally
npm run dev           # Start development server

But this is completely optional for contributions!

For Maintainers (Internal)

If you have write access to the repository:

  1. Edit README.md directly on master or in a branch
  2. Commit and push your changes
  3. GitHub Actions will automatically run the parser
  4. JSON files will be auto-committed within seconds

🤖 GitHub Actions Automation

This repository uses GitHub Actions to automatically parse README.md and generate JSON files.

How It Works

  1. Trigger: Runs when README.md is changed on master branch
  2. Parse: Executes npm run parse-readme
  3. Commit: Auto-commits generated JSON files
  4. Push: Pushes changes back to the repository

When Does It Run?

  • ✅ When a PR is merged to master (and README.md changed)
  • ✅ When you push directly to master (and README.md changed)
  • ❌ Does NOT run on pull request branches (only after merge)

What Gets Generated?

  • src/data/*.json - Individual category JSON files
  • src/data/categories-index.json - Summary of all categories

Workflow File

The automation is defined in .github/workflows/parse-readme.yml

You can see the workflow runs at:

https://github.com/selfishprimate/mossaique/actions

🛠️ Technical Details

Parser Script

  • Location: scripts/parse-readme.js
  • Input: README.md
  • Output: src/data/*.json
  • Language: Node.js (ES Modules)

Data Structure

Each category JSON file contains:

{
  "id": "color",
  "title": "Color",
  "description": "The best tools for creating color schemes",
  "icon": "Palette",
  "resources": [
    {
      "title": "Adobe Color",
      "link": "https://color.adobe.com",
      "description": "Create beautiful color themes!"
    }
  ]
}

⚠️ Important Notes

  1. Only edit README.md - JSON files are auto-generated
  2. Commit only README.md - GitHub Actions handles JSON generation
  3. Don't manually edit JSON files (they'll be overwritten by automation)
  4. Keep format consistent in README.md for proper parsing
  5. Alphabetical order - Keep resources sorted alphabetically
  6. GitHub Actions will automatically run after your PR is merged to master

🐛 Troubleshooting

Parser doesn't find resources

  • Check markdown link format: [Title](URL): Description
  • Ensure colon (:) after URL before description
  • No extra spaces or line breaks

Missing category

  • Check category header uses ## (Level 2 heading)
  • Category should have a description in _italics_
  • Run parser again

Icons not showing

  • Check if icon exists in iconMap in scripts/parse-readme.js
  • Add custom mapping if needed
  • Icon names must match Lucide icon names

📝 Complete Example

Step 1 - Edit README.md:

## Frontend Design

_Suppose you're a designer. You also love to write HTML, CSS, JavaScript!_

- [Bootstrap](https://getbootstrap.com/): Build fast, responsive sites with Bootstrap.
- [Tailwind CSS](https://tailwindcss.com/): Rapidly build modern websites without ever leaving your HTML.

Step 2 - Commit and push to master (or merge PR)

Step 3 - GitHub Actions automatically generates (frontend-design.json):

{
  "id": "frontend-design",
  "title": "Frontend Design",
  "description": "Suppose you're a designer...",
  "icon": "Code",
  "resources": [
    {
      "title": "Bootstrap",
      "link": "https://getbootstrap.com/",
      "description": "Build fast, responsive sites with Bootstrap."
    },
    {
      "title": "Tailwind CSS",
      "link": "https://tailwindcss.com/",
      "description": "Rapidly build modern websites without ever leaving your HTML."
    }
  ]
}

Well, that's all you need to know. It was easy, wasn't it?

Need help? Open an issue on GitHub and we'll be happy to assist you!

Thank you for contributing! 🎉