Merge branch 'main' of https://github.com/BmanClark/arm-learning-paths

Author: BmanClark

.github/skills/draft-learning-path/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: draft-learning-path
+description: "Toggle draft mode on a Learning Path _index.md. Use when: marking a learning path as draft, hiding a learning path from publication, adding draft: true to front matter, unpublishing or disabling a learning path, removing draft, publishing a learning path, taking a learning path out of draft."
+---
+
+# Draft Learning Path
+
+Sets `draft: true` and `cascade: draft: true` in the front matter of a Learning Path `_index.md` file so the page and all its child pages are excluded from the published site.
+
+For new content intake where the goal is to prevent unreviewed content from publishing, use `.github/skills/intake-metadata-update/SKILL.md` instead.
+
+## Draft block to insert
+
+The following YAML must be added to the front matter, after the `title:` field. Leave a blank line between `title:` and the draft block for readability:
+
+```yaml
+title: Your Learning Path Title
+
+draft: true
+cascade:
+    draft: true
+```
+
+## Workflow
+
+1. **Identify the target file**
+   - If the user specifies a path, use that.
+   - Otherwise, use the currently open or most recently edited `_index.md` file in the workspace.
+   - Confirm the file is a Learning Path `_index.md` (contains Hugo front matter between `---` markers).
+
+2. **Read the file**
+   - Read the file to inspect the existing front matter.
+
+3. **Apply the draft block**
+   - If `draft: true` and `cascade:` with `draft: true` already exist, inform the user it is already in draft mode and stop.
+   - If a `draft:` field exists but no `cascade:` block, replace the existing `draft:` line with the full draft block above.
+   - If no `draft:` field exists, insert the draft block after the `title:` field, with a blank line between them.
+
+4. **Confirm**
+   - Report the file path and confirm the draft block has been set.
+   - Remind the user that Hugo will exclude this file and all child pages from the built site until the draft block is removed.
+
+## Undraft workflow
+
+If the user asks to publish, undraft, or remove draft mode:
+
+1. **Identify the target file** (same as above).
+2. **Read the file** to locate the draft block.
+3. **Remove the draft block**
+   - Remove the `draft: true` line.
+   - Remove the `cascade:` block (`cascade:` and its indented `draft: true` child line).
+   - Remove any blank line that was added between `title:` and the draft block, restoring the original spacing.
+   - If no draft block exists, inform the user the file is already published and stop.
+4. **Confirm**
+   - Report the file path and confirm draft mode has been removed.
+   - Remind the user the Learning Path will now appear on the published site.

.github/skills/frontmatter-audit/SKILL.md

@@ -25,13 +25,14 @@ For a Learning Path directory:
 - Public pages should have unique `weight` values within the directory.
 - Every page except for `_next-steps.md` must include a description.
 - `_index.md` must include `description`.
-- Required `_index.md` fields include `title`, `description`, `weight`, `layout`, `minutes_to_complete`, `prerequisites`, `author`, `subjects`, `armips`, `tools_software_languages`, `skilllevels`, and `operatingsystems`.
+- Required `_index.md` fields include `title`, `description`, `weight`, `layout`, `minutes_to_complete`, `prerequisites`, `author`, `generate_summary_faq`, `rerun_summary`, `rerun_faqs`, `subjects`, `armips`, `tools_software_languages`, `skilllevels`, and `operatingsystems`.
 - `layout` is usually `learningpathall`.
 - `title` should be task-led and use an imperative structure: verb + technology/tool + outcome.
 - `skilllevels` values are only `Introductory` or `Advanced`.
 - `subjects` and `operatingsystems` must match the closed lists in `content/learning-paths/cross-platform/_example-learning-path/write-2-metadata/`.
 - `armips` should use Arm IP families such as Neoverse, Cortex-A, or Cortex-M, not specific CPU models or Arm architecture versions.
 - `author` can list multiple authors with YAML list syntax.
+- `generate_summary_faq`, `rerun_summary`, and `rerun_faqs` values are only `true` and `false`.
 - Skip `_next-steps.md` for description updates unless the user explicitly asks how to handle it.
 
 ## Install guide checks

.github/skills/writing-style-review/SKILL.md

@@ -18,8 +18,8 @@ Use this skill for granular prose, voice, readability, terminology, and style re
 
 ## Voice and tone
 
-- Use second person: `you` and `your`.
-- Avoid first person: `I` and `we`.
+- Use second person: `you` and `your` for Learning Path summaries, Learning Path content, install guide content, answers to FAQs, and metadata descriptions. Avoid first person for these content types.
+- Use first person: `I` and `we` for FAQs.
 - Use active voice.
 - Use present tense for descriptions.
 - Use imperative mood for commands.
@@ -40,6 +40,7 @@ Use this skill for granular prose, voice, readability, terminology, and style re
 - Use plain English and avoid jargon overload.
 - Define acronyms on first use.
 - Use parallel structure in lists.
+- Avoid starting sentences with "In this Learning Path"/ "In this section"/"On this page" / "In this step".
 - Flag sections over 700 words and suggest natural split points.
 - Identify paragraphs with sentences averaging over 20 words.
 - Note sections that introduce more than two new concepts.
@@ -74,7 +75,7 @@ Use this skill for granular prose, voice, readability, terminology, and style re
 - Use `set up` as a verb and `setup` as a noun.
 - Use `avoid` instead of `try not to`.
 - Use `such as` instead of `like`.
-- Use `after` instead of `once`.
+- Use `after` or `when` instead of `once`.
 
 ## Tone cleanup
 
@@ -111,7 +112,7 @@ Use this skill for granular prose, voice, readability, terminology, and style re
 - Use `arm64` or `aarch64` for CPU architecture based on tool, package, or OS convention.
 - Use `ARM64` only when referring to Windows on Arm or Microsoft documentation.
 - Capitalize `Learning Path`.
-- Use `Azure Cobalt`, `Google Axion`, and `AWS Graviton` as processor names, not VM names.
+- Use `Azure Cobalt`, `Google Axion`, and `AWS Graviton` as processor names, not VM names. `Graviton-based instances`, not `Graviton instances`, for example.
 - Do not use bold or italics for product names such as LiteRT, XNNPACK, KleidiAI, and SME2 unless they are headings or UI labels.
 
 ## Avoid AI-sounding prose

.gitignore

@@ -8,7 +8,6 @@ package-lock.json
 .vscode
 .env
 startup.sh
-data/
 
 # macOS files
 *.DS_Store
@@ -26,4 +25,4 @@ z_local_saved/
 tags
 
 # Generated spell check config
-.spellcheck-non-draft.yml
+.spellcheck-non-draft.yml

.wordlist.txt

@@ -6324,4 +6324,35 @@ perfrunbook
 pprof
 prj
 reflashing
-unwinder
+unwinder
+AmazonECS
+Anupras
+Mohapatra
+RCTL
+Rafay
+Rafay's
+RafayEKSProvisioner
+aeaed
+aed
+balancer's
+cbd
+cdk
+dac
+dbdad
+dcf
+defaultproject
+deprovision
+dfbc
+ebdd
+ece
+edbfe
+ede
+fcdebd
+rafay
+rctl
+Prims
+bbe
+boundedness
+cbf
+dda
+efe

assets/contributors.csv

@@ -127,3 +127,4 @@ Sue Wu,Arm,,,,
 Sabika Tasneem,Memgraph,,,,
 Anupras Mohapatra,Arm,,,,
 Tomas Agustin Gonzalez Orlando,Arm,tgonzalezorlandoarm,tgorlando,,
+Steve Jordahl,Rafay,,,,

assets/css/content.css

@@ -153,7 +153,7 @@ img.content-uploaded-image.centered {
     /* have to style the span like a paragraph, required for nesting caption in default markdown configruation */
     display: block; /* or block, depending on the desired layout */
     font-style: italic;
-    font-weight: 500;
+    font-weight: 400;
     margin-top: 0px;
     font-size: 1rem;
 }

assets/css/cross-page.css

@@ -12,60 +12,35 @@
 
 /* UNIVERSAL FONTS */
 /****************************************************/
-/* Ignored for now, adding in head.html via google fonts. Can use this locally to optimize if needed */
-
-
-/* Lato font get from local fonts folder, not fonts.google.com as it loads facebook/youtube tracking data */
-    /* Normal, Italic, Bold 
-        300, 400, 500 */
-
-/*
+/* Lato font self-hosted from /fonts/ to avoid external requests and reduce CLS */
 @font-face {
     font-family: 'Lato';
     font-style: normal;
     font-weight: 300;
-    src: url('../fonts/LatoLatin-Light.woff2') format('woff2'),
-         url('../fonts/LatoLatin-Light.ttf') format('ttf');
-  }
-  
-  @font-face {
+    font-display: swap;
+    src: url('/fonts/LatoLatin-Light.woff2') format('woff2');
+}
+@font-face {
     font-family: 'Lato';
     font-style: normal;
     font-weight: 400;
-    src: url('../fonts/LatoLatin-Regular.woff2') format('woff2'),
-         url('../fonts/LatoLatin-Regular.ttf') format('ttf');
-  }
-  
-  @font-face {
-    font-family: 'Lato';
-    font-style: normal;
-    font-weight: 500;
-    src: url('../fonts/LatoLatin-Medium.woff2') format('woff2'),
-         url('../fonts/LatoLatin-Medium.ttf') format('ttf');
-  }
-  
+    font-display: swap;
+    src: url('/fonts/LatoLatin-Regular.woff2') format('woff2');
+}
 @font-face {
     font-family: 'Lato';
     font-style: italic;
     font-weight: 300;
-    src: url('../fonts/LatoLatin-LightItalic.woff2') format('woff2'),
-         url('../fonts/LatoLatin-LightItalic.ttf') format('ttf');
-  }  
-  @font-face {
+    font-display: swap;
+    src: url('/fonts/LatoLatin-LightItalic.woff2') format('woff2');
+}
+@font-face {
     font-family: 'Lato';
     font-style: italic;
     font-weight: 400;
-    src: url('../fonts/LatoLatin-Italic.woff2') format('woff2'),
-         url('../fonts/LatoLatin-Italic.ttf') format('ttf');
-  }  
-  @font-face {
-    font-family: 'Lato';
-    font-style: italic;
-    font-weight: 500;
-    src: url('../fonts/LatoLatin-MediumItalic.woff2') format('woff2'),
-         url('../fonts/LatoLatin-MediumItalic.ttf') format('ttf');
-  }
-*/
+    font-display: swap;
+    src: url('/fonts/LatoLatin-Italic.woff2') format('woff2');
+}
 
 
 /* UNIVERSAL */
@@ -183,17 +158,31 @@ table tbody td {
 
 
 
+/* CLS fix: reserve space for nav before hydration */
+arm-top-navigation:not(:defined) {
+    display: block;
+    min-height: 80px;
+}
+@media (max-width: 1024px) {
+    arm-top-navigation:not(:defined) {
+        min-height: 60px;
+    }
+}
+
 /* Fix global nav height */
+/* The arm-global-web-components script renders a position:fixed nav (0 flow space)
+   and may inject a 50px sub-navigation bar in flow */
 /*************************************/
 #global-nav-height-fixer {
     max-width: 100vw;
-    min-height: 80px;
+    height: 80px;
+    overflow: hidden;
     position: relative;
     top: 0;
 }
 @media (max-width: 1024px) { /* smaller screens than LG */
         #global-nav-height-fixer {
-            min-height: 60px;
+            height: 60px;
         }
 }
 .nav-transparent {
@@ -453,3 +442,11 @@ html[theme='light'] body {
         ads-masthead { --ads-masthead-horizontal-padding: 5px; }
 }
 
+/* CLS fix: reserve space for arm-footer before hydration */
+arm-footer-navigation:not(:defined) {
+    display: block;
+    min-height: 300px;
+}
+#arm-footer {
+    contain: layout;
+}

assets/css/home.css

@@ -1,6 +1,32 @@
 
 
 
+/* CLS fix: reserve space for web components before hydration */
+ads-search:not(:defined) {
+    display: block;
+    min-height: 45px;
+}
+ads-cta-button:not(:defined) {
+    display: inline-block;
+    min-height: 40px;
+    min-width: 200px;
+}
+ads-breadcrumbs:not(:defined) {
+    display: block;
+    min-height: 32px;
+}
+
+/* CLS fix: lock the breadcrumb masthead height so hydration doesn't shift content below */
+#only-breadcrumb-masthead {
+    height: 40px;
+    overflow: hidden;
+}
+
+/* CLS fix: lock the description+button area height to prevent shift when ads-cta-button hydrates */
+.homepage-top-desc {
+    min-height: 110px;
+}
+
 /*********************************************************************            
 
         Main Topic Cards

assets/css/list-pages.css

@@ -7,6 +7,25 @@ Covers the following pages:
 
 
 
+/* CLS fix: reserve space for web components before hydration
+*******************************************************************/
+ads-card:not(:defined) {
+    display: block;
+    min-height: 180px;
+}
+ads-search:not(:defined) {
+    display: block;
+    min-height: 45px;
+}
+ads-expansion-panel:not(:defined) {
+    display: block;
+    min-height: 48px;
+}
+ads-masthead:not(:defined) {
+    display: block;
+    min-height: 100px;
+}
+
 /* Search / Status bar for active filters, # displayed, and sorting 
 *******************************************************************/ 
 #result-sort-div {
@@ -313,7 +332,7 @@ html[theme="light"] .learning-path-title, html[theme="light"] .basics-title {
     /*font-weight: bold;
     font-size:1.25rem;
     */
-    font-weight: 500;
+    font-weight: 400;
 
     margin-top: 0px;
     margin-bottom: 4px;