feat: add /guides command and ability to sync all guides to a discord channel (#7)

hmd-ali · wiktoriavh · web-flow · commit 333e5376fbb8 · 2025-10-18T17:27:43.000+03:00
* 🔨 refactor: Adjust "tailwind with vite" command title and file name

* 🌟 feat: guides - add vue guide

* 🌟 feat: guides - add accessibility guide

* 🌟 feat: guides - add backend guide

* 🌟 feat: guides - add css guide

* 🌟 feat: guides - add frontend guide

* 🌟 feat: guides - add javascript guide

* 🌟 feat: add `guides-tracker.json` to gitignore

* 🌟 feat: add new env vars

* 🌟 feat: implement guide synchronization and management functionality

* 🤖 ci: add GUIDES_CHANNEL_ID and GUIDES_TRACKER_PATH to deployment environment

* 📚 docs: move guides docs to the docs folder

---------

Co-authored-by: Wiktoria Van Harneveldt &lt;w.dev+git@mailbox.org&gt;
diff --git a/.env.example b/.env.example
@@ -1,2 +1,3 @@
 DISCORD_TOKEN="" # Your bot token
 CLIENT_ID="" # Your bot's application ID
+GUIDES_CHANNEL_ID="" # The ID of the channel where guides will be posted
diff --git a/.gitignore b/.gitignore
@@ -15,4 +15,7 @@ yarn-error.log*
 !.env.example
 .env
 .env.local
-.env.*.local
+.env.*.local
+
+# guides tracker
+guides-tracker.json
diff --git a/docs/GUIDE_SYNC.md b/docs/GUIDE_SYNC.md
@@ -0,0 +1,27 @@
+# Guide Synchronization System
+
+The bot automatically synchronizes guide markdown files from `src/commands/guides/subjects/` to a Discord channel when it starts up.
+
+## Setup
+
+Add to your `.env.local` file:
+```
+GUIDES_CHANNEL_ID=1234567890123456789
+```
+
+## Commands
+
+- `npm run sync-guides` - Manual sync (updates only changed guides)
+- `npm run sync-guides:init` - Force sync (posts all guides fresh)
+
+## Guide Format
+
+Guides need frontmatter with a `name` field:
+
+```markdown
+---
+name: JavaScript
+---
+
+Your guide content here...
+```
diff --git a/package.json b/package.json
@@ -20,7 +20,9 @@
     "test": "pnpm run build:dev && node --test dist/**/*.test.js",
     "test:ci": "node --test dist/**/*.test.js",
     "prepare": "husky",
-    "pre-commit": "lint-staged"
+    "pre-commit": "lint-staged",
+    "sync-guides": "tsx scripts/sync-guides.js",
+    "sync-guides:init": "tsx scripts/sync-guides.js --initialize"
   },
   "keywords": [],
   "author": "",
diff --git a/scripts/sync-guides.js b/scripts/sync-guides.js
@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+/**
+ * Standalone script for synchronizing guides to Discord channel
+ * Usage: npm run sync-guides [--initialize]
+ */
+
+import { Client, GatewayIntentBits } from 'discord.js';
+import { config } from '../src/env.js';
+import { syncGuidesToChannel, initializeGuidesChannel } from '../src/util/post-guides.js';
+
+async function main() {
+  const args = process.argv.slice(2);
+  const shouldInitialize = args.includes('--initialize');
+
+  if (!config.guides.channelId) {
+    console.error('❌ GUIDES_CHANNEL_ID environment variable is required');
+    console.error('Please set it in your environment variables');
+    process.exit(1);
+  }
+
+  console.log(`🤖 Starting Discord client for guide sync...`);
+  
+  const client = new Client({
+    intents: [
+      GatewayIntentBits.Guilds,
+      GatewayIntentBits.GuildMessages,
+    ],
+  });
+
+  try {
+    await client.login(config.discord.token);
+    console.log(`✅ Logged in as ${client.user?.tag}`);
+
+    if (shouldInitialize) {
+      console.log('🚀 Initializing guides channel (will post all guides fresh)...');
+      await initializeGuidesChannel(client, config.guides.channelId);
+    } else {
+      console.log('🔄 Synchronizing guides...');
+      await syncGuidesToChannel(client, config.guides.channelId);
+    }
+
+    console.log('✅ Guide synchronization completed successfully');
+  } catch (error) {
+    console.error('❌ Guide synchronization failed:', error);
+    process.exit(1);
+  } finally {
+    await client.destroy();
+    console.log('👋 Discord client disconnected');
+  }
+}
+
+main().catch((error) => {
+  console.error('❌ Unexpected error:', error);
+  process.exit(1);
+});
diff --git a/src/commands/guides/subjects/a11y.md b/src/commands/guides/subjects/a11y.md
@@ -0,0 +1,12 @@
+---
+name: Accessibility (A11y)
+---
+
+Improve your web accessibility skills with these valuable free resources:
+
+**Reference & Guidelines**  
+- [**MDN Web Accessibility**](<https://developer.mozilla.org/en-US/docs/Learn/Accessibility>) - Comprehensive guides and best practices.  
+- [**WAI (Web Accessibility Initiative)**](<https://www.w3.org/WAI/>) - Official guidelines and resources for web accessibility.  
+- [**a11y Project**](<https://www.a11yproject.com/>) - Community-driven resources and checklists.  
+- [**WebAIM**](<https://webaim.org/>) - Articles, tools, and training on web accessibility.
+- [**web.dev Accessibility**](<https://web.dev/accessibility/>) - Tutorials and best practices for building accessible web experiences.
diff --git a/src/commands/guides/subjects/backend.md b/src/commands/guides/subjects/backend.md
@@ -0,0 +1,16 @@
+---
+name: Backend Development
+---
+
+Boost your backend development skills with these top free resources:
+
+**Structured Learning Paths**  
+- [**Roadmap**](<https://roadmap.sh/backend>) - A comprehensive guide to backend technologies and concepts.  
+
+**Backends**  
+- SQLlite (recommended) - Lightweight, disk-based database.
+- PostgreSQL (recommended) - Advanced, open-source relational database.
+- Mongodb (only pick if you have to.) - NoSQL database for flexible, JSON-like documents.
+- Redis - In-memory data structure store, used as a database, cache, and message broker.  
+
+
diff --git a/src/commands/guides/subjects/css.md b/src/commands/guides/subjects/css.md
@@ -1,8 +1,15 @@
 ---
-name: Css
+name: CSS
 ---
 
-CSS can be tricky to get right, especially with the various browsers and their quirks. Here are some common issues and solutions:
-1. **Box Model Issues**: Ensure you understand the CSS box model (content, padding, border, margin). Use `box-sizing: border-box;` to make width and height include padding and border.
-2. **Specificity Problems**: If your styles aren't applying, check the specificity of your selectors. More specific selectors override less specific ones.
-3. **Flexbox and Grid Layouts**: These modern layout systems can be complex. Make sure to understand their properties and how they interact.
+Level up your CSS skills with these free and practical resources:
+
+**Reference & Guides**  
+- [**MDN**](<https://developer.mozilla.org/en-US/docs/Web/CSS>) - Comprehensive CSS documentation.  
+- [**web.dev**](<https://web.dev/css>) - Modern CSS best practices and tutorials.  
+- [**CSS Tricks**](<https://css-tricks.com/category/articles/>) - Tips, tricks, and in-depth articles.  
+
+**Interactive Learning**  
+- [**CSS Grid Garden**](<https://cssgridgarden.com/>) - Master CSS Grid with fun exercises.  
+- [**Flexbox Froggy**](<https://flexboxfroggy.com/>) - Learn Flexbox by solving interactive challenges.  
+- [**A Complete Guide to Flexbox**](<https://css-tricks.com/snippets/css/a-guide-to-flexbox/>) - Detailed reference and examples.
diff --git a/src/commands/guides/subjects/frontend.md b/src/commands/guides/subjects/frontend.md
@@ -0,0 +1,18 @@
+---
+name: Frontend Development
+---
+
+Sharpen your frontend skills with these curated free resources:
+
+**Structured Learning Paths**  
+- [**The Odin Project**](<https://www.theodinproject.com/paths/foundations/courses/foundations>) - A full curriculum from basics to projects.  
+- [**Roadmap**](<https://roadmap.sh/frontend>) - Step-by-step guide of what to learn next in frontend development.  
+
+**Practice & Challenges**  
+- [**Frontend Mentor**](<https://www.frontendmentor.io/>) - Build real projects and improve your coding skills.  
+
+**Reference & Guides**  
+- [**JavaScript Info**](<https://javascript.info/>) - Deep dive into JavaScript concepts and examples.  
+- [**CSS Tricks**](<https://css-tricks.com/>) - Tips, tricks, and guides for CSS and modern layouts.  
+- [**MDN Web Docs**](<https://developer.mozilla.org/en-US/curriculum/>) - Comprehensive reference for HTML, CSS, and JS.
+
diff --git a/src/commands/guides/subjects/html.md b/src/commands/guides/subjects/html.md
diff --git a/src/commands/guides/subjects/javascript.md b/src/commands/guides/subjects/javascript.md
@@ -0,0 +1,16 @@
+---
+name: JavaScript
+---
+
+Enhance your JavaScript skills with these essential free resources:
+
+**Reference & Guides**  
+- [**MDN JavaScript**](<https://developer.mozilla.org/en-US/docs/Web/JavaScript>) - Complete documentation and tutorials.  
+- [**JavaScript Info**](<https://javascript.info/>) - In-depth guides from basics to advanced concepts.  
+- [**Eloquent JavaScript**](<https://eloquentjavascript.net/>) - A modern introduction to programming using JavaScript.  
+- [**web.dev**](<https://web.dev/learn/javascript/>) - Learn JavaScript with practical examples and best practices.  
+- [**Roadmap**](<https://roadmap.sh/javascript>) - A structured path to mastering JavaScript.
+
+**Interactive Learning & Challenges**  
+- [**Frontend Mentor (JS Projects)**](<https://www.frontendmentor.io/>) - Apply JS in real-world projects.  
+- [**FreeCodeCamp (JS Course)**](<https://www.freecodecamp.org/learn/full-stack-developer>) - Learn JavaScript through interactive coding challenges.
diff --git a/src/commands/guides/subjects/tailwind-with-vite.md b/src/commands/guides/subjects/tailwind-with-vite.md
@@ -1,5 +1,5 @@
 ---
-name: Tailwind Setup Issues
+name: Tailwind with Vite
 ---
 
 We've heard you have issues with setting up Tailwind in Vite. Have you followed all the steps described in the docs?
diff --git a/src/commands/guides/subjects/vue.md b/src/commands/guides/subjects/vue.md
@@ -0,0 +1,15 @@
+---
+name: Vue
+---
+
+Enhance your Vue.js skills with these valuable free resources:
+
+**Official Documentation & Guides**  
+- [**Vue.js Official Documentation**](<https://vuejs.org/>) - Comprehensive guides and API references.  
+
+**Community Guides**  
+- [**How to learn Vue**](<https://vue-land.github.io/faq/learning-vue>) - A guide to learning Vue effectively.  
+
+**Tools**
+- [**Vueuse**](<https://vueuse.org/>) - A collection of essential Vue Composition Utilities.
+- [**Vue Playground**](<https://play.vuejs.org/>) - An online editor to experiment with Vue.js code snippets.
diff --git a/src/env.ts b/src/env.ts
@@ -1,5 +1,9 @@
 import './loadEnvFile.js';
 
+function optionalEnv(key: string): string | undefined {
+  return process.env[key];
+}
+
 function requireEnv(key: string): string {
   const value = process.env[key];
   if (!value) {
@@ -16,6 +20,10 @@ export const config = {
     token: requireEnv('DISCORD_TOKEN'),
     clientId: requireEnv('CLIENT_ID'),
   },
+  guides: {
+    channelId: requireEnv('GUIDES_CHANNEL_ID'),
+    trackerPath: optionalEnv('GUIDES_TRACKER_PATH'),
+  },
   // Add more config sections as needed:
   // database: {
   //   url: requireEnv('DATABASE_URL'),
diff --git a/src/events/ready.ts b/src/events/ready.ts
@@ -1,12 +1,22 @@
 import { Events } from 'discord.js';
+import { config } from '../env.js';
 import { createEvent } from '../util/events.js';
+import { syncGuidesToChannel } from '../util/post-guides.js';
 
 export const readyEvent = createEvent(
   {
     name: Events.ClientReady,
     once: true,
   },
-  (client) => {
+  async (client) => {
     console.log(`Ready! Logged in as ${client.user.tag}`);
+
+    // Sync guides to channel
+    try {
+      console.log(`🔄 Starting guide sync to channel ${config.guides.channelId}...`);
+      await syncGuidesToChannel(client, config.guides.channelId);
+    } catch (error) {
+      console.error('❌ Failed to sync guides:', error);
+    }
   }
 );
diff --git a/src/util/post-guides.ts b/src/util/post-guides.ts

Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`DISCORD_TOKEN="" # Your bot token`
`2`	`2`	`CLIENT_ID="" # Your bot's application ID`
	`3`	`+GUIDES_CHANNEL_ID="" # The ID of the channel where guides will be posted`