chore: sync content to repo (#9717)

Co-authored-by: kamranahmedse <4921183+kamranahmedse@users.noreply.github.com>

.astro/settings.json

@@ -3,6 +3,6 @@
 		"enabled": false
 	},
 	"_variables": {
-		"lastUpdateCheck": 1749494681580
+		"lastUpdateCheck": 1763378528944
 	}
 }

.astro/types.d.ts

@@ -1 +1,2 @@
 /// <reference types="astro/client" />
+/// <reference path="content.d.ts" />

.cursor/rules/content-migration.mdc

@@ -0,0 +1,155 @@
+---
+description: When user requests migrating old roadmap content to new folder from content-old to content folder
+globs: 
+alwaysApply: false
+---
+# Content Migration Rule
+
+## Rule Name: content-migration
+
+## Description
+This rule provides a complete process for migrating roadmap content from old structure to new structure using migration mapping files.
+
+## When to Use
+Use this rule when you need to:
+- Migrate content from content-old directories to content directories
+- Use a migration-mapping.json file to map topic paths to content IDs
+- Populate empty content files with existing content from legacy structure
+
+## Process
+
+### 1. Prerequisites Check
+- Verify the roadmap directory has a `migration-mapping.json` file
+- Confirm `content-old/` directory exists with source content
+- Confirm `content/` directory exists with target files
+
+### 2. Migration Script Creation
+Create a Node.js script with the following functionality:
+
+```javascript
+const fs = require('fs');
+const path = require('path');
+
+// Load the migration mapping
+const migrationMapping = JSON.parse(fs.readFileSync('migration-mapping.json', 'utf8'));
+
+// Function to find old content file based on topic path
+function findOldContentFile(topicPath) {
+  const parts = topicPath.split(':');
+  
+  if (parts.length === 1) {
+    // Top level file like "introduction"
+    return path.join('content-old', parts[0], 'index.md');
+  } else if (parts.length === 2) {
+    // Like "introduction:what-is-rust"
+    const [folder, filename] = parts;
+    return path.join('content-old', folder, `${filename}.md`);
+  } else if (parts.length === 3) {
+    // Like "language-basics:syntax:variables"
+    const [folder, subfolder, filename] = parts;
+    return path.join('content-old', folder, subfolder, `${filename}.md`);
+  }
+  
+  return null;
+}
+
+// Function to find new content file based on content ID
+function findNewContentFile(contentId) {
+  const contentDir = 'content';
+  const files = fs.readdirSync(contentDir);
+  
+  // Find file that ends with the content ID
+  const matchingFile = files.find(file => file.includes(`@${contentId}.md`));
+  
+  if (matchingFile) {
+    return path.join(contentDir, matchingFile);
+  }
+  
+  return null;
+}
+
+// Process each mapping
+console.log('Starting content migration...\n');
+
+let migratedCount = 0;
+let skippedCount = 0;
+
+for (const [topicPath, contentId] of Object.entries(migrationMapping)) {
+  const oldFilePath = findOldContentFile(topicPath);
+  const newFilePath = findNewContentFile(contentId);
+  
+  if (!oldFilePath) {
+    console.log(`❌ Could not determine old file path for: ${topicPath}`);
+    skippedCount++;
+    continue;
+  }
+  
+  if (!newFilePath) {
+    console.log(`❌ Could not find new file for content ID: ${contentId} (topic: ${topicPath})`);
+    skippedCount++;
+    continue;
+  }
+  
+  if (!fs.existsSync(oldFilePath)) {
+    console.log(`❌ Old file does not exist: ${oldFilePath} (topic: ${topicPath})`);
+    skippedCount++;
+    continue;
+  }
+  
+  try {
+    // Read old content
+    const oldContent = fs.readFileSync(oldFilePath, 'utf8');
+    
+    // Write to new file
+    fs.writeFileSync(newFilePath, oldContent);
+    
+    console.log(`✅ Migrated: ${topicPath} -> ${path.basename(newFilePath)}`);
+    migratedCount++;
+  } catch (error) {
+    console.log(`❌ Error migrating ${topicPath}: ${error.message}`);
+    skippedCount++;
+  }
+}
+
+console.log(`\n📊 Migration complete:`);
+console.log(`   Migrated: ${migratedCount} files`);
+console.log(`   Skipped: ${skippedCount} files`);
+console.log(`   Total: ${Object.keys(migrationMapping).length} mappings`);
+```
+
+### 3. Execution Steps
+1. Navigate to the roadmap directory (e.g., `src/data/roadmaps/[roadmap-name]`)
+2. Create the migration script as `migrate_content.cjs`
+3. Run: `node migrate_content.cjs`
+4. Review the migration results
+5. Clean up the temporary script file
+
+### 4. Validation
+After migration:
+- Verify a few migrated files have proper content (not just titles)
+- Check that the content structure matches the old content
+- Ensure proper markdown formatting is preserved
+
+## File Structure Expected
+```
+roadmap-directory/
+├── migration-mapping.json
+├── content/
+│   ├── file1@contentId1.md
+│   ├── file2@contentId2.md
+│   └── ...
+└── content-old/
+    ├── section1/
+    │   ├── index.md
+    │   ├── topic1.md
+    │   └── subsection1/
+    │       └── subtopic1.md
+    └── section2/
+        └── ...
+```
+
+## Notes
+- The migration mapping uses colons (`:`) to separate nested paths
+- Content files in the new structure use the pattern `filename@contentId.md`
+- The script handles 1-3 levels of nesting in the old structure
+- Always create the script with `.cjs` extension to avoid ES module issues

.env.example

@@ -7,4 +7,6 @@ PUBLIC_STRIPE_INDIVIDUAL_MONTHLY_PRICE_ID=
 PUBLIC_STRIPE_INDIVIDUAL_YEARLY_PRICE_ID=
 
 PUBLIC_STRIPE_INDIVIDUAL_MONTHLY_PRICE_AMOUNT=10
-PUBLIC_STRIPE_INDIVIDUAL_YEARLY_PRICE_AMOUNT=100
+PUBLIC_STRIPE_INDIVIDUAL_YEARLY_PRICE_AMOUNT=100
+
+ROADMAP_API_KEY=

.github/ISSUE_TEMPLATE/05-project-contribution.yml

@@ -1,35 +0,0 @@
-name: "🙏 ​ ​Submit a Project Idea"
-description: Help us add project ideas to roadmaps.
-labels: [project contribution]
-assignees: []
-body:
-  - type: markdown
-    attributes:
-      value: |
-        Thanks for taking the time to submit a project idea! Please fill out the information below and we'll get back to you as soon as we can.
-  - type: input
-    id: roadmap-title
-    attributes:
-      label: What Roadmap is this project for?
-      placeholder: e.g. Backend Roadmap
-    validations:
-      required: true
-  - type: dropdown
-    id: project-difficulty
-    attributes:
-      label: Project Difficulty
-      options:
-        - Beginner
-        - Intermediate
-        - Advanced
-    validations:
-      required: true
-  - type: textarea
-    id: roadmap-description
-    attributes:
-      label: Add Project Details
-      description: Please write a detailed description of the project in 3rd person e.g. "You are required to build a..."
-      placeholder: |
-          e.g. You are required to build a RESTful API...
-    validations:
-      required: true

.github/workflows/cleanup-orphaned-content.yml

@@ -0,0 +1,80 @@
+name: Cleanup Orphaned Content
+
+on:
+  workflow_dispatch:
+    inputs:
+      roadmap_slug:
+        description: "The ID of the roadmap to clean up"
+        required: true
+
+jobs:
+  cleanup-content:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm@v9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+          run_install: false
+
+      - name: Setup Node.js Version 20 (LTS)
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install Dependencies and Run Cleanup
+        run: |
+          echo "Installing Dependencies"
+          pnpm install
+          echo "Running Orphaned Content Cleanup"
+          npm run cleanup:orphaned-content -- --roadmap-slug=${{ inputs.roadmap_slug }}
+
+      - name: Read cleanup summary
+        id: read-summary
+        run: |
+          if [ -f .cleanup-summary.md ]; then
+            {
+              echo 'summary<<EOF'
+              cat .cleanup-summary.md
+              echo 'EOF'
+            } >> $GITHUB_OUTPUT
+          fi
+
+      - name: Check for changes
+        id: verify-changed-files
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Delete summary file
+        if: steps.verify-changed-files.outputs.changed == 'true'
+        run: rm -f .cleanup-summary.md
+
+      - name: Create PR
+        if: steps.verify-changed-files.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          delete-branch: false
+          branch: "chore/cleanup-orphaned-content-${{ inputs.roadmap_slug }}"
+          base: "master"
+          labels: |
+            automated pr
+          reviewers: jcanalesluna,kamranahmedse
+          commit-message: "chore: cleanup orphaned content files"
+          title: "chore: cleanup orphaned content - ${{ inputs.roadmap_slug }}"
+          body: |
+            ${{ steps.read-summary.outputs.summary }}
+
+            > [!IMPORTANT]
+            > This PR removes orphaned/duplicate content files for: ${{ inputs.roadmap_slug }}
+            >
+            > Commit: ${{ github.sha }}
+            > Workflow Path: ${{ github.workflow_ref }}
+
+            **Please review the changes and merge the PR if everything looks correct.**

.github/workflows/refresh-roadmap-content-json.yml

@@ -1,52 +0,0 @@
-name: Refresh Roadmap Content JSON
-
-on:
-  workflow_dispatch:
-  schedule:
-    - cron: '0 0 * * *'
-
-jobs:
-  refresh-content:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-
-      - name: Setup pnpm@v9
-        uses: pnpm/action-setup@v4
-        with:
-          version: 9
-          run_install: false
-
-      - name: Setup Node.js Version 20 (LTS)
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-          cache: 'pnpm'
-
-      - name: Install Dependencies and Generate Content JSON
-        run: |
-          pnpm install
-          npm run generate:roadmap-content-json
-      
-      - name: Create PR
-        uses: peter-evans/create-pull-request@v7
-        with:
-          delete-branch: false
-          branch: "chore/update-content-json"
-          base: "master"
-          labels: |
-            dependencies
-            automated pr
-          reviewers: kamranahmedse
-          commit-message: "chore: update roadmap content json"
-          title: "Updated Roadmap Content JSON - Automated"
-          body: |
-            ## Updated Roadmap Content JSON
-            
-            > [!IMPORTANT]
-            > This PR Updates the Roadmap Content JSON files stored in the `public` directory.
-            >
-            > Commit: ${{ github.sha }}
-            > Workflow Path: ${{ github.workflow_ref }}
-
-            **Please Review the Changes and Merge the PR if everything is fine.**

.github/workflows/sync-content-to-repo.yml

@@ -0,0 +1,66 @@
+name: Sync Content to Repo
+
+on:
+  workflow_dispatch:
+    inputs:
+      roadmap_slug:
+        description: "The ID of the roadmap to sync"
+        required: true
+        default: "__default__"
+
+jobs:
+  sync-content:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm@v9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+          run_install: false
+
+      - name: Setup Node.js Version 20 (LTS)
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Install Dependencies and Sync Content
+        run: |
+          echo "Installing Dependencies"
+          pnpm install
+          echo "Syncing Content to Repo"
+          npm run sync:content-to-repo -- --roadmap-slug=${{ inputs.roadmap_slug }} --secret=${{ secrets.GH_SYNC_SECRET }}
+
+      - name: Check for changes
+        id: verify-changed-files
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "changed=true" >> $GITHUB_OUTPUT
+          else
+            echo "changed=false" >> $GITHUB_OUTPUT
+          fi
+      
+      - name: Create PR
+        if: steps.verify-changed-files.outputs.changed == 'true'
+        uses: peter-evans/create-pull-request@v7
+        with:
+          delete-branch: false
+          branch: "chore/sync-content-to-repo-${{ inputs.roadmap_slug }}"
+          base: "master"
+          labels: |
+            automated pr
+          reviewers: jcanalesluna,kamranahmedse
+          commit-message: "chore: sync content to repo"
+          title: "chore: sync content to repository - ${{ inputs.roadmap_slug }}"
+          body: |
+            ## Sync Content to Repo
+            
+            > [!IMPORTANT]
+            > This PR Syncs the Content to the Repo for the Roadmap: ${{ inputs.roadmap_slug }}
+            >
+            > Commit: ${{ github.sha }}
+            > Workflow Path: ${{ github.workflow_ref }}
+
+            **Please Review the Changes and Merge the PR if everything is fine.** 

.github/workflows/sync-repo-to-database.yml

@@ -0,0 +1,57 @@
+name: Sync Repo to Database
+
+on:
+  workflow_dispatch:
+    inputs:
+      roadmap_slug:
+        description: "The slug of the roadmap to sync (e.g., frontend, backend)"
+        required: true
+
+jobs:
+  sync-roadmap:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup pnpm@v9
+        uses: pnpm/action-setup@v4
+        with:
+          version: 9
+          run_install: false
+
+      - name: Setup Node.js Version 20 (LTS)
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: 'pnpm'
+
+      - name: Get all roadmap files
+        id: roadmap-files
+        run: |
+          ROADMAP_DIR="src/data/roadmaps/${{ inputs.roadmap_slug }}"
+
+          if [ ! -d "$ROADMAP_DIR" ]; then
+            echo "Error: Roadmap directory '$ROADMAP_DIR' does not exist"
+            exit 1
+          fi
+
+          echo "Getting all files in $ROADMAP_DIR"
+
+          ALL_FILES=$(find "$ROADMAP_DIR" -type f | tr '\n' ',')
+
+          echo "Files to sync:"
+          echo "$ALL_FILES"
+
+          echo "files=$ALL_FILES" >> $GITHUB_OUTPUT
+
+      - name: Install Dependencies
+        run: |
+          echo "Installing Dependencies"
+          pnpm install
+
+      - name: Run sync script
+        run: |
+          echo "Running sync script for roadmap: ${{ inputs.roadmap_slug }}"
+          echo "Files: ${{ steps.roadmap-files.outputs.files }}"
+
+          npm run sync:repo-to-database -- --files="${{ steps.roadmap-files.outputs.files }}" --secret=${{ secrets.GH_SYNC_SECRET }}

astro.config.mjs

@@ -20,10 +20,29 @@ export default defineConfig({
       status: 301,
       destination: '/ai',
     },
-  },
-  vite: {
-    server: {
-      allowedHosts: ['roadmap.sh', 'port3k.kamranahmed.info'],
+    '/best-practices': {
+      status: 301,
+      destination: '/roadmaps',
+    },
+    '/best-practices/aws': {
+      status: 301,
+      destination: '/aws-best-practices',
+    },
+    '/best-practices/backend-performance': {
+      status: 301,
+      destination: '/backend-performance-best-practices',
+    },
+    '/best-practices/frontend-performance': {
+      status: 301,
+      destination: '/frontend-performance-best-practices',
+    },
+    '/best-practices/api-security': {
+      status: 301,
+      destination: '/api-security-best-practices',
+    },
+    '/best-practices/code-review': {
+      status: 301,
+      destination: '/code-review-best-practices',
     },
   },
   markdown: {
@@ -72,5 +91,8 @@ export default defineConfig({
     ssr: {
       noExternal: [/^@roadmapsh\/editor.*$/],
     },
+    server: {
+      allowedHosts: ['roadmap.sh', 'port3k.kamranahmed.info'],
+    },
   },
 });

contributing.md

@@ -6,8 +6,10 @@ First of all, thank you for considering to contribute. Please look at the detail
 - [Existing Roadmaps](#existing-roadmaps)
 - [Adding Projects](#adding-projects)
 - [Adding Content](#adding-content)
+  - [How To Structure Content](#how-to-structure-content)
 - [Guidelines](#guidelines)
 - [Good vs. Not So Good Contributions](#good-vs-not-so-good-contributions)
+- [Local Development](#local-development)
 
 ## New Roadmaps
 
@@ -21,7 +23,7 @@ For new roadmaps, you can either:
 For the existing roadmaps, please follow the details listed for the nature of contribution:
 
 - **Fixing Typos** — Make your changes in the [roadmap markdown file](https://github.com/kamranahmedse/developer-roadmap/tree/master/src/data/roadmaps) and submit a [PR](https://github.com/kamranahmedse/developer-roadmap/pulls).
-- **Adding or Removing Nodes** — Please open an [issue](https://github.com/kamranahmedse/developer-roadmap/issues) with your suggestion.
+- **Adding/Removing Nodes and Modifying Node Titles** — Please open an [issue](https://github.com/kamranahmedse/developer-roadmap/issues) with your suggestion.
 
 **Note:** Please note that our goal is **not to have the biggest list of items**. Our goal is to list items or skills most relevant today.
 
@@ -53,6 +55,7 @@ Find [the content directory inside the relevant roadmap](https://github.com/kamr
 
 - Content must be in English.
 - Maximum of 8 links per topic.
+- **No GeeksforGeeks links** — Links to geeksforgeeks.org are not accepted.
 - Follow the below style guide for content.
 
 Please note that we are intentionally keeping the content under the topic popup concise. You MUST always aim to explain the topic simply in a **single paragraph** or so and provide external resources where users can learn more about the topic.

license

@@ -10,10 +10,3 @@ conditions do not apply to the readonly GitHub forks created using the Fork butt
 GitHub with the whole purpose of contributing to the project.
 
 Copyright © 2017 - Present. Kamran Ahmed <kamranahmed.se@gmail.com>
-
-Please note that I am really flexible with allowing the usage of the content in this
-repository. If you reach out to me with a brief detail of why and how you would like
-to use this content, there is a good chance that I will allow you to use it. The reason
-behind this strictness in the license is to stop the people who have been using these
-roadmaps in ill manners e.g. ripping people off with suggesting random affiliate links,
-redistributing these roadmaps just for the sake of monetizing the traffic.

package.json

@@ -16,6 +16,7 @@
     "roadmap-links": "node scripts/roadmap-links.cjs",
     "roadmap-dirs": "node scripts/roadmap-dirs.cjs",
     "roadmap-assets": "tsx scripts/editor-roadmap-assets.ts",
+    "refresh-assets": "tsx scripts/refresh-assets.ts",
     "editor-roadmap-dirs": "tsx scripts/editor-roadmap-dirs.ts",
     "editor-roadmap-content": "tsx scripts/editor-roadmap-content.ts",
     "roadmap-content": "node scripts/roadmap-content.cjs",
@@ -28,9 +29,16 @@
     "compress:images": "tsx ./scripts/compress-images.ts",
     "generate:roadmap-content-json": "tsx ./scripts/editor-roadmap-content-json.ts",
     "migrate:editor-roadmaps": "tsx ./scripts/migrate-editor-roadmap.ts",
+    "sync:content-to-repo": "tsx ./scripts/sync-content-to-repo.ts",
+    "sync:repo-to-database": "tsx ./scripts/sync-repo-to-database.ts",
+    "sync:roadmap": "tsx ./scripts/sync-roadmap-to-database.ts",
+    "migrate:content-repo-to-database": "tsx ./scripts/migrate-content-repo-to-database.ts",
+    "cleanup:orphaned-content": "tsx ./scripts/cleanup-orphaned-content.ts",
+    "official:roadmap-assets": "tsx ./scripts/official-roadmap-assets.ts",
     "test:e2e": "playwright test"
   },
   "dependencies": {
+    "@ai-sdk/react": "2.0.0-beta.34",
     "@astrojs/node": "^9.2.1",
     "@astrojs/react": "^4.2.7",
     "@astrojs/sitemap": "^3.4.0",
@@ -42,6 +50,7 @@
     "@radix-ui/react-popover": "^1.1.14",
     "@resvg/resvg-js": "^2.6.2",
     "@roadmapsh/editor": "workspace:*",
+    "@shikijs/transformers": "^3.9.2",
     "@tailwindcss/vite": "^4.1.7",
     "@tanstack/react-query": "^5.76.1",
     "@tiptap/core": "^2.12.0",
@@ -64,6 +73,7 @@
     "image-size": "^2.0.2",
     "jose": "^6.0.11",
     "js-cookie": "^3.0.5",
+    "katex": "^0.16.22",
     "lucide-react": "^0.511.0",
     "luxon": "^3.6.1",
     "markdown-it-async": "^2.2.0",
@@ -73,15 +83,20 @@
     "npm-check-updates": "^18.0.1",
     "playwright": "^1.52.0",
     "prismjs": "^1.30.0",
+    "radix-ui": "^1.4.2",
     "react": "^19.1.0",
     "react-calendar-heatmap": "^1.10.0",
     "react-confetti": "^6.4.0",
     "react-dom": "^19.1.0",
     "react-dropzone": "^14.3.8",
+    "react-markdown": "^10.1.0",
     "react-resizable-panels": "^3.0.2",
     "react-textarea-autosize": "^8.5.9",
     "react-tooltip": "^5.28.1",
     "rehype-external-links": "^3.0.0",
+    "rehype-katex": "^7.0.1",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
     "remark-parse": "^11.0.0",
     "roadmap-renderer": "^1.0.7",
     "sanitize-html": "^2.17.0",
@@ -96,6 +111,7 @@
     "tiptap-markdown": "^0.8.10",
     "turndown": "^7.2.0",
     "unified": "^11.0.5",
+    "zod": "^4.0.17",
     "zustand": "^5.0.4"
   },
   "devDependencies": {
@@ -111,7 +127,7 @@
     "@types/react-slick": "^0.23.13",
     "@types/sanitize-html": "^2.16.0",
     "@types/turndown": "^5.0.5",
-    "ai": "^4.3.16",
+    "ai": "5.0.0-beta.34",
     "csv-parser": "^3.2.0",
     "gh-pages": "^6.3.0",
     "js-yaml": "^4.1.0",