feat: added more comments for clarity

ikelaiah · ikelaiah · commit d7f7eebbd661 · 2025-08-22T08:19:23.000+10:00
diff --git a/layouts/index.html b/layouts/index.html
@@ -14,6 +14,15 @@ <h1>Pascal</h1>
                 <!-- <p class="version-info">Latest: Free Pascal 3.2.2 • Lazarus 4.2</p> -->
             </div>
             <div class="hero-code">
+                <!--
+                  Code tabs
+                  - To add a new example:
+                    1) Add a button here with data-example="yourkey"
+                    2) Add a matching <div class="code-example" id="example-yourkey"> below.
+                    3) Define a Hugo variable with backticks (e.g., $yourCode := `...`) and render with
+                       {{ highlight $yourCode "objectpascal" "linenos=false" }}
+                  - The tab switching is implemented in JS inside layouts/_default/baseof.html.
+                -->
                 <div class="code-selector">
                     <button class="code-tab active" data-example="webserver">Web Server</button>
                     <button class="code-tab" data-example="sorting">Data Processing</button>
@@ -24,6 +33,12 @@ <h1>Pascal</h1>
                     <button class="code-tab" data-example="concurrent">Concurrency</button>
                 </div>
                 
+                <!--
+                  Code examples container
+                  - Each .code-example corresponds to a tab via id="example-<key>".
+                  - We use Hugo's built-in Chroma highlighter. Language: "objectpascal"
+                  - The extra class "capsule-fpc" adds an FPC label via CSS (see static/css/main.css).
+                -->
                 <div class="code-examples">
                     <div class="code-example active" id="example-webserver">
                         {{ $webserverCode := `program webserver;
@@ -309,6 +324,7 @@ <h3>Productivity</h3>
 <!-- Getting Started Section -->
 <section class="content-section">
     <div class="container">
+        <!-- Three-step quick start cards. Update links/titles as content grows. -->
         <h2 class="section-title">Quick Start</h2>
         <div class="cards">
             <div class="card">
@@ -333,6 +349,7 @@ <h3>3. Build</h3>
 <!-- Community Section -->
 <section class="content-section" style="background-color: var(--bg-secondary);">
     <div class="container">
+        <!-- Call-to-action to join the community. Adjust copy/URL as needed. -->
         <h2 class="section-title">Join the Community</h2>
         <p style="text-align: center; font-size: 1.1rem; max-width: 600px; margin: 0 auto var(--spacing-xl);">
             Connect with Pascal developers worldwide, share knowledge, and contribute to the growing Pascal ecosystem.
diff --git a/static/css/main.css b/static/css/main.css
@@ -1,4 +1,8 @@
-/* CSS Variables for theming */
+/*
+  Global CSS variables and design system tokens.
+  These drive light/dark colors, spacing, typography, and layout.
+  If you need to tweak the look-and-feel, prefer changing these first.
+*/
 :root {
   /* Light theme colors */
   --bg-primary: #fafbfc;
@@ -32,7 +36,10 @@
   --transition: all 0.2s ease;
 }
 
-/* Dark theme colors - Professional and modern */
+/*
+  Dark theme overrides.
+  The <body> gets data-theme="dark" via JS (see baseof.html) which triggers these vars.
+*/
 [data-theme="dark"] {
   --bg-primary: #0d1117;
   --bg-secondary: #161b22;
@@ -101,7 +108,10 @@ a:hover {
   color: var(--accent-hover);
 }
 
-/* Header */
+/*
+  Header and top navigation bar.
+  The mobile experience uses a hamburger that toggles a dropdown (see media query section).
+*/
 .site-header {
   background-color: var(--bg-primary);
   border-bottom: 1px solid var(--border-color);
@@ -186,7 +196,10 @@ a:hover {
   transform-origin: center;
 }
 
-/* Animate hamburger -> X */
+/*
+  Animate hamburger -> X when menu is open.
+  JS toggles .mobile-menu-toggle.active (see baseof.html).
+*/
 .mobile-menu-toggle.active span:nth-child(1) {
   transform: translateY(12px) rotate(45deg);
 }
@@ -448,7 +461,9 @@ a:hover {
   position: relative;
 }
 
-/* Pascal compatibility capsules */
+/*
+  Compatibility "capsules" shown on code blocks (e.g., FPC). Purely decorative labels.
+*/
 .highlight.capsule-fpc::before {
   content: 'FPC';
   position: absolute;
@@ -597,13 +612,20 @@ hr {
   color: var(--text-muted);
 }
 
-/* Responsive design */
+/*
+  Responsive design
+  Mobile navigation lives here: a dropdown that expands/collapses with a smooth transition.
+*/
 @media (max-width: 768px) {
   .container {
     padding: 0 var(--spacing-md);
   }
   
-  /* Mobile dropdown menu (smooth transition) */
+  /*
+    Mobile dropdown menu (smooth transition)
+    Hidden state uses max-height + opacity + translateY for a smooth open/close.
+    We also keep the nav list in column layout in both states to avoid sideways shifting.
+  */
   .navbar-menu {
     display: flex;               /* keep layout consistent */
     flex-direction: column;
@@ -626,6 +648,7 @@ hr {
     visibility: hidden;
     transition: max-height 0.25s ease, opacity 0.2s ease, transform 0.2s ease, visibility 0.2s ease;
   }
+
   /* Shown when hamburger is toggled */
   .navbar-menu.is-open {
     max-height: 60vh;
@@ -634,6 +657,7 @@ hr {
     pointer-events: auto;
     visibility: visible;
   }
+
   /* Keep column layout during both open and closing transitions to prevent sideways shift */
   .navbar-menu .navbar-nav {
     flex-direction: column;
