Merge branch 'master' into add-home-page

Signed-off-by: Lee Calcote <lee.calcote@layer5.io>

Author: leecalcote

.gitignore

@@ -26,5 +26,6 @@ resources/
 .hugo_build.lock
 content/*
 !content/_index.md
+!content/instructor-toolkit.md
 
 .DS_Store

README.md

@@ -25,6 +25,111 @@ In addition to this core structure, the following content types are available:
   final-test)
 - **Certification** - Certification programs
 
+### Where Content Should Live
+
+Keep publishable Academy content and any org-specific supporting files inside
+the organization directory. Files outside the org directory are not part of
+the publishable Academy content tree. Validation catches these cases, and the
+files may be skipped during publication or change shared site behavior in
+unexpected ways.
+
+Use this general layout:
+
+```text
+content/
+  learning-paths/
+    <org-id>/
+      _index.md
+      course-1/
+        _index.md
+        module-1/
+          _index.md
+  certifications/
+    <org-id>/
+      _index.md
+  challenges/
+    <org-id>/
+      _index.md
+layouts/
+  shortcodes/
+    <org-id>/
+      *.html
+static/
+  <org-id>/
+    ...
+data/
+  <org-id>/
+    ...
+```
+
+Put org-specific content, shortcodes, static files, and data under the org
+directory. If you place them elsewhere, the Academy may not publish them and
+the build can emit warnings or break shared assumptions for other content.
+
+Shared theme assets, icons, and reusable partials should stay in
+academy-theme itself rather than in a consuming org repository.
+
+## Quiz JSON contract
+
+Quiz JSON emitted by the `test` layouts is normalized toward the
+`meshery/schemas` academy Quiz contract. The generated JSON now uses
+canonical quiz/question field names, numeric `timeLimit`, hyphenated question
+types, and UUIDs for page, parent, question, and option IDs.
+
+Authors can still keep front matter ergonomic:
+
+- page, question, and option `id` values may stay short slugs;
+- legacy snake_case quiz keys such as `pass_percentage`, `time_limit`,
+  `max_attempts`, `correct_answer`, and `is_correct` are still accepted in
+  front matter during the transition;
+- emitted UUIDs are derived deterministically from the content file path plus
+  the authored ID, so repeated builds produce stable values.
+
+## ID Validation
+
+The theme checks publishable root Academy content during Hugo builds and emits
+warnings by default. This is intentionally warning-first so authors can keep
+working locally while still seeing what needs to be fixed before publication.
+
+Configure the shared registry URL in the theme, and set the Instructor Console
+URL in each content repo:
+
+```yaml
+params:
+  academy:
+    registryURL: "<shared-academy-registry-api-url>"
+    consoleURL: "<per-repo-instructor-console-url>"
+    validationMode: warn
+```
+
+The registry URL is the same for all Academy sites. The console URL varies by
+domain, so each content repo should set its own value. For example, Exoscale
+uses `https://exoscale.layer5.io/academy/instructors-console`, while Meshery
+uses `https://cloud.meshery.io/academy/instructors-console`.
+
+Supported `validationMode` values:
+
+- `warn` keeps builds running and prints actionable warnings.
+- `error` fails only for broken publishable content, for stricter CI use.
+- `off` suppresses content health warnings and skips registry lookups.
+
+Registry lookups are scoped to root learning paths, challenges, and
+certifications. Draft root content is not warning-producing and is hidden from
+the Instructor Toolkit report. Nested course/module/page/test IDs are not
+checked against the Cloud curriculum registry.
+
+If `params.academy.registryURL` is not configured, the build prints one
+configuration warning and does not report existing IDs as invalid because they
+have not been checked against the registry.
+
+The registry response is cached once per org and registry URL in Hugo's site
+store during a build. The remote response uses a cache key scoped to the current
+Hugo process, so incremental rebuilds reuse the same response. Rebuild the
+site completely to refresh the cached registry API response for fresh ID
+lookups.
+
+The Instructor Toolkit surfaces the same build-generated report.
+
 ## Important Notes
 
 ⚠️ **Deprecated Features**

archetypes/final-test.md

@@ -1,69 +1,70 @@
 ---
 title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
-pass_percentage: 70 # Minimum percentage required to pass the test
-time_limit: 15 # Duration of the test in minutes
+passPercentage: 70 # Minimum percentage required to pass the test
+timeLimit: 15 # Duration of the test in minutes
 level: "beginner" # Difficulty level of the test
 category: "Programming Languages" # Category of the test
 tags: ["golang", "basics", "syntax", "fundamentals"] # Tags for the test, useful for search and categorization
 type: "test" # Type of the content, in this case, a test ( required for the test to be recognized by the system )
 final: true # Indicates that this test is the final exam and must be completed to complete the course , module or section
 
 questions:
+  # IDs can stay short slugs in front matter; academy-theme derives stable UUIDs in emitted quiz JSON.
   # Multiple Choice Question (Single Answer)
   # NOTE: The 'marks' field must be a positive number (greater than 0). Negative or zero values will cause a build error.
   - id: "q1"
     text: "What keyword is used to define a function in Go?"
-    type: "multiple_answers"
+    type: "single-answer"
     marks: 2
     explanation: "The 'func' keyword is used to declare functions in Go, similar to how 'function' is used in JavaScript."
     options:
       - id: "a"
         text: "function"
-        is_correct: false
+        isCorrect: false
       - id: "b"
         text: "def"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "func"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "fn"
-        is_correct: false
+        isCorrect: false
 
   # Short Answer Question
   - id: "q2"
     text: "Go is a statically typed language. (true/false)"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "true"
+    correctAnswer: "true"
     case_sensitive: false
     explanation: "Go is indeed a statically typed language, meaning variable types are determined at compile time."
 
   # Short Answer Question (Numeric)
   - id: "q3"
     text: "What is the zero value of an uninitialized int in Go?"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "0"
+    correctAnswer: "0"
     explanation: "In Go, the zero value for numeric types like int is 0."
 
   # Multiple Choice Question (Multiple Answers)
   - id: "q4"
     text: "What are the purposes of the 'defer' keyword in Go? (Select all that apply)"
-    type: "multiple_answers"
+    type: "multiple-answers"
     marks: 2
     explanation: "The defer keyword is commonly used to delay function execution until the surrounding function returns, often used for cleanup tasks like closing files."
     options:
       - id: "a"
         text: "To delay the execution of a function until the surrounding function returns"
-        is_correct: true
+        isCorrect: true
       - id: "b"
         text: "To define a constant value"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "To close resources like files or network connections"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "To handle errors in a function"
-        is_correct: false
+        isCorrect: false
 ---

archetypes/optional-test.md

@@ -1,69 +1,70 @@
 ---
 title: '{{ replace .File.ContentBaseName `-` ` ` | title }}'
-pass_percentage: 70 # Minimum percentage required to pass the test
-time_limit: 15 # Duration of the test in minutes
+passPercentage: 70 # Minimum percentage required to pass the test
+timeLimit: 15 # Duration of the test in minutes
 level: "beginner" # Difficulty level of the test
 category: "Programming Languages" # Category of the test
 tags: ["golang", "basics", "syntax", "fundamentals"] # Tags for the test, useful for search and categorization
 type: "test" # Type of the content, in this case, a test ( required for the test to be recognized by the system )
 is_optional: true # Indicates that this test is optional and does not need to be completed to take the final exam
 
 questions:
+  # IDs can stay short slugs in front matter; academy-theme derives stable UUIDs in emitted quiz JSON.
   # Multiple Choice Question (Single Answer)
   # NOTE: The 'marks' field must be a positive number (greater than 0). Negative or zero values will cause a build error.
   - id: "q1"
     text: "What keyword is used to define a function in Go?"
-    type: "multiple_answers"
+    type: "single-answer"
     marks: 2
     explanation: "The 'func' keyword is used to declare functions in Go, similar to how 'function' is used in JavaScript."
     options:
       - id: "a"
         text: "function"
-        is_correct: false
+        isCorrect: false
       - id: "b"
         text: "def"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "func"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "fn"
-        is_correct: false
+        isCorrect: false
 
   # Short Answer Question
   - id: "q2"
     text: "Go is a statically typed language. (true/false)"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "true"
+    correctAnswer: "true"
     case_sensitive: false
     explanation: "Go is indeed a statically typed language, meaning variable types are determined at compile time."
 
   # Short Answer Question (Numeric)
   - id: "q3"
     text: "What is the zero value of an uninitialized int in Go?"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "0"
+    correctAnswer: "0"
     explanation: "In Go, the zero value for numeric types like int is 0."
 
   # Multiple Choice Question (Multiple Answers)
   - id: "q4"
     text: "What are the purposes of the 'defer' keyword in Go? (Select all that apply)"
-    type: "multiple_answers"
+    type: "multiple-answers"
     marks: 2
     explanation: "The defer keyword is commonly used to delay function execution until the surrounding function returns, often used for cleanup tasks like closing files."
     options:
       - id: "a"
         text: "To delay the execution of a function until the surrounding function returns"
-        is_correct: true
+        isCorrect: true
       - id: "b"
         text: "To define a constant value"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "To close resources like files or network connections"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "To handle errors in a function"
-        is_correct: false
+        isCorrect: false
 ---

archetypes/test.md

@@ -1,49 +1,50 @@
 ---
 title: 'test'
-pass_percentage: 70 # Minimum percentage required to pass the test
-time_limit: 15 # Duration of the test in minutes
-max_attempts: 3 # Maximum number of attempts allowed
+passPercentage: 70 # Minimum percentage required to pass the test
+timeLimit: 15 # Duration of the test in minutes
+maxAttempts: 3 # Maximum number of attempts allowed
 level: "beginner" # Difficulty level of the test
 category: "Programming Languages" # Category of the test
 tags: ["golang", "basics", "syntax", "fundamentals"] # Tags for the test, useful for search and categorization
 type: "test" # Type of the content, in this case, a test ( required for the test to be recognized by the system )
 
 questions:
+  # IDs can stay short slugs in front matter; academy-theme derives stable UUIDs in emitted quiz JSON.
   # Multiple Choice Question (Single Answer)
   - id: "q1"
     text: "What keyword is used to define a function in Go?"
-    type: "multiple_answers"
+    type: "single-answer"
     marks: 2
     explanation: "The 'func' keyword is used to declare functions in Go, similar to how 'function' is used in JavaScript."
     options:
       - id: "a"
         text: "function"
-        is_correct: false
+        isCorrect: false
       - id: "b"
         text: "def"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "func"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "fn"
-        is_correct: false
+        isCorrect: false
 
   # Short Answer Question
   - id: "q2"
     text: "Go is a statically typed language. (true/false)"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "true"
+    correctAnswer: "true"
     case_sensitive: false
     explanation: "Go is indeed a statically typed language, meaning variable types are determined at compile time."
 
   # Short Answer Question (Numeric)
   - id: "q3"
     text: "What is the zero value of an uninitialized int in Go?"
-    type: "short_answer"
+    type: "short-answer"
     marks: 2
-    correct_answer: "0"
+    correctAnswer: "0"
     explanation: "In Go, the zero value for numeric types like int is 0."
 
   # Multiple Choice Question (Multiple Answers)
@@ -55,14 +56,14 @@ questions:
     options:
       - id: "a"
         text: "To delay the execution of a function until the surrounding function returns"
-        is_correct: true
+        isCorrect: true
       - id: "b"
         text: "To define a constant value"
-        is_correct: false
+        isCorrect: false
       - id: "c"
         text: "To close resources like files or network connections"
-        is_correct: true
+        isCorrect: true
       - id: "d"
         text: "To handle errors in a function"
-        is_correct: false
+        isCorrect: false
 ---

assets/scss/_styles_project.scss

@@ -290,6 +290,19 @@ a:not([href]):not([class]):hover {
       background-color: rgba($primary, 0.1);
       color: dark;
     }
+
+    &.academy-sidebar-toolkit {
+      color: $dark;
+      font-weight: $font-weight-bold;
+    }
+
+    &.active.academy-sidebar-toolkit {
+      border: 2px solid $lightslategray !important;
+      padding: 0.25rem;
+      padding-left: 0.5rem !important;
+      background-color: rgba($primary, 0.1);
+      color: $dark;
+    }
   }
 }