Update guidelines for new storage system

technoph1le · technoph1le · commit 06e4987ff9f5 · 2025-01-01T19:15:36.000+02:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -13,121 +13,161 @@ You can contribute in two main ways:
 
 If you have a feature request or want to fix a bug, feel free to:
 
-- [Open an Issue](https://github.com/dostonnabotov/quicksnip/issues) to let me know what’s up.
-- [Send a pull request](https://github.com/dostonnabotov/quicksnip/pulls) with your changes.
+- [Open an Issue](https://github.com/dostonnabotov/quicksnip/issues) to let us know what’s up.
+- [Send a Pull Request](https://github.com/dostonnabotov/quicksnip/pulls) with your changes.
 
 ---
 
 ## Adding Snippets
 
-### Adding to an Existing Category
+### Adding a New Snippet
 
-1. **Find the language file:**
+To add a new code snippet:
 
-Head over to the `/public/data` folder and locate the language file you need, like javascript.json or python.json
+1. **Navigate to the relevant folder:**
+  
+    - Go to the `/snippets` folder in the root directory.
+    - Locate the folder for the programming language of your snippet, such as `javascript` or `python`.
 
-2. **Find the category:**
+2. **Choose the correct category:**
 
-Look for the categoryName where your snippet belongs.
+    - Within the language folder, find the relevant category folder for your snippet.
+    - If no suitable category exists, refer to [Adding a New Category](#adding-a-new-category).
 
-3. **Add your snippet** in this format:
+3. **Create a markdown file:**
 
-```json
-{
-  "title": "Name of the snippet",
-  "description": "A short explanation of what the snippet does",
-  "code": [
-    "your code goes here", 
-    "  this is a newline with a space"
-  ],
-  "tags": ["tag1", "tag2", "tag3"],
-  "author": "your_github_username"
-}
+    - Create a new file with a `.md` extension.
+    - Name the file appropriately, keeping it descriptive and concise.
+
+4. **Add your snippet:**
+
+    - Use the following format to structure your snippet:
+
+```md
+---
+title: Name of the snippet
+description: A short explanation of what the snippet does
+tags: tag1, tag2, tag3
+author: your-github-username
+---
+
+// Your code here
 ```
 
 Here’s an example for JavaScript:
 
-```json
-// javascript.json
-[
-  {
-    "categoryName": "Date and Time",
-    "snippets": [
-      {
-        "title": "Format Date",
-        "description": "Formats a date in 'YYYY-MM-DD' format.",
-        "code": [
-          "const formatDate = (date) => date.toISOString().split('T')[0];",
-          "",
-          "// Usage:",
-          "console.log(formatDate(new Date())); // Output: '2024-12-10'"
-        ],
-        "tags": ["javascript", "date", "format"],
-        "author": "technoph1le"
-      }
-    ]
-  }
-]
 ```
+---
+title: Format Date
+description: Formats a date in 'YYYY-MM-DD' format.
+author: dostonnabotov
+tags: javascript,date,format,utility
+---
 
-### Adding a New Category
+const formatDate = (date) => date.toISOString().split('T')[0];
 
-If your snippet doesn’t fit into any existing category, you can create a new one! Just make sure it’s unique and doesn’t overlap with others (e.g., don’t create separate categories for “Date” and “Time” when “Date and Time” works).
+// Usage:
+console.log(formatDate(new Date())); // Output: '2024-12-10'
+```
 
-Use this format:
-
-```json
-[
-  {
-    "categoryName": "New Category Name",
-    "snippets": [
-      {
-        "title": "Name of the snippet",
-        "description": "A short explanation of what it does",
-        "code": [
-          "your code goes here", 
-          "  this is a newline with a space"
-        ],
-        "tags": ["tag1", "tag2", "tag3"],
-        "author": "your_github_username"
-      }
-    ]
-  }
-]
+5. **Use syntax highlighting:**
+    - Enclose your code with triple backticks (```).
+    - Specify the language after the first set of backticks for syntax highlighting.
+
+![snippet code example in markdown file](https://github.com/user-attachments/assets/be650cfe-fd17-49e7-ae82-e1c88e30d4c9)
+
+6. **Test your snippet:**
+   - Ensure your code runs as expected.
+
+Expected structure:
+
+```txt
+snippets
+  |- language
+    |- category
+      |- your-snippet-here.md
 ```
 
-### Adding a New Language
+### Editing a Existing Snippet
 
-Want to include a new programming language? Here's what to do:
+If you’d like to refine or improve an existing snippet:
 
-1. **Create a new file:**
+1. **Add a `contributors` field:**
 
-In the `/public/data` folder, create a file named after the language (e.g., `go.json`).
+    - Include your GitHub username under the `contributors` field in the metadata section.
 
-2. **Add categories and snippets:**
+```md
+---
+title: Name of the snippet
+description: A short explanation of what the snippet does
+tags: tag1, tag2, tag3
+author: original-author
+contributors: your-github-username
+---
+
+Updated code here
+```
+
+2. **Credit all contributors:**
 
-Follow the formats explained above.
+    - If contributors already exist, add your username separated by a comma
 
-3. **Update the `_index.json`:**
+```md
+contributors: contributor1, contributor2, your-github-username
+```
+
+3. **Document changes:**
+
+Clearly indicate what you updated and why in your pull request description.
+
+We want to make sure that original author and contributor(s) are credited for their work.
+
+
+### Adding a New Category
+
+If your snippet doesn’t fit into any existing category, you can create a new one! Just make sure it’s unique and doesn’t overlap with others (e.g., don’t create separate categories for “Date” and “Time” when “Date and Time” works).
+
+1. **Create a new category folder:**
+
+    - In the relevant language directory, add a new folder.
+    - Use a lowercase name with hyphens for separation (e.g., `file-handling`).
 
-Add your new language like this:
+2. **Add snippets:**
 
-```json
-[
-  {
-    "lang": "Go",
-    "icon": "/icons/go.svg"
-  }
-]
+    - Follow the [Adding a New Snippet](#adding-a-new-snippet) instructions.
+
+
+Example structure:
+
+```md
+/snippets
+  |_ python
+       |_ file-handling
+       |_ list-manipulation
+       |_ ....
 ```
 
+### Adding a New Language
+
+If you want to introduce a new programming language, here's how to do it:
+
+1. **Create a language folder:**
+
+    - Add a new folder under the `snippets` directory.
+    - Name it after the language in lowercase (e.g., `go`, `ruby`).
+
+2. **Add categories and snippets:**
+
+    - Follow the [Adding a New Snippet](#adding-a-new-snippet) and [Adding a New Category](#adding-a-new-category) guidelines.
+
 4. **Include an icon:**
 
-Upload a logo for your language into the `/public/icons` folder. Make sure the filename matches the one you used in `_index.json`. Icons should be 50x50px in `.svg` format.
+    - Add an `icon.svg` file (50x50px) in the same language folder.
+    - Use tools like [Resize SVG](https://www.iloveimg.com/resize-image/resize-svg) to ensure the correct size.
 
 5. **Double-check your work:**
 
-Test on your side and confirm if it works properly.
+    - Verify that everything is structured correctly and displays as intended.
 
 ---
 
diff --git a/README.md b/README.md
@@ -16,7 +16,8 @@ Want to help make QuickSnip even better? You can contribute by:
 
 - **Improving the Code**: Fix bugs, suggest new features, or optimize the project.
 - **Adding New Snippets**: Share your favorite snippets to grow the database.
-  Be sure to check out the [CONTRIBUTING.md](/CONTRIBUTING.md) file for detailed guidelines.
+
+Be sure to check out the [CONTRIBUTING.md](/CONTRIBUTING.md) file for detailed guidelines.
 
 ### Improving the code
 
@@ -27,30 +28,36 @@ Got a feature idea or bug fix? Here's how you can contribute:
 
 ### Adding a Snippet
 
-The snippets database is located in the `/public/data` folder.
-
-If you’d like to add a snippet for an **existing language** and **category**, use the following format:
-
-```json
-{
-  "title": "Name of the snippet",
-  "description": "A short explanation of what the snippet does",
-  "code": [
-    "your code goes here", 
-    "  this is a newline with a space"
-  ],
-  "tags": ["tag1", "tag2", "tag3"],
-  "author": "your_github_username"
-}
+The snippets database is located in the `/snippets` folder.
+
+1. Find the relevant language folder.
+
+2. Locate the appropriate category folder for your snippet.
+
+3. Create a markdown file and add your snippet using the following format:
+
+```md
+---
+title: Name of the snippet
+description: A short explanation of what the snippet does
+tags: tag1, tag2, tag3
+author: your-github-username
+---
+
+// Your code here
 ```
 
-For details about adding new categories or programming languages, check out the [CONTRIBUTING.md](/CONTRIBUTING.md) file.
+Here's an example for JavaScript:
+
+![code example in markdown file](https://github.com/user-attachments/assets/dba9fda3-76fe-4d92-b12a-8bc065286b90)
+
+For more details about adding new categories or programming languages, check out the [CONTRIBUTING.md](/CONTRIBUTING.md) file.
 
 ## Guidelines for Contributions
 
 To keep things smooth and consistent, please:
 
-- Use proper JSON formatting.
+- Follow the formatting rules described above.
 - Include all mandatory fields in the snippet.
 - Test your snippet to ensure it works as expected.
 
