docs: embeded best practices in page (#62173)

JeanMeche · AndrewKushnir · commit 286f9f573ec9 · 2025-06-20T15:29:24.000-07:00
PR Close #62173
diff --git a/adev/shared-docs/pipeline/guides/extensions/docs-code/docs-code.mts b/adev/shared-docs/pipeline/guides/extensions/docs-code/docs-code.mts
@@ -22,6 +22,7 @@ const singleFileCodeRule =
   /^\s*<docs-code((?:\s+[\w-]+(?:="[^"]*"|='[^']*'|=[^\s>]*)?)*)\s*(?:\/>|>(.*?)<\/docs-code>)/s;
 
 const pathRule = /path="([^"]*)"/;
+const classRule = /class="([^"]*)"/;
 const headerRule = /header="([^"]*)"/;
 const linenumsRule = /linenums/;
 const highlightRule = /highlight="([^"]*)"/;
@@ -51,6 +52,7 @@ export const docsCodeExtension = {
       const visibleLines = visibleLinesRule.exec(attr);
       const visibleRegion = visibleRegionRule.exec(attr);
       const preview = previewRule.exec(attr) ? true : false;
+      const classes = classRule.exec(attr);
 
       let code = match[2]?.trim() ?? '';
       if (path && path[1]) {
@@ -73,6 +75,7 @@ export const docsCodeExtension = {
         visibleLines: visibleLines?.[1],
         visibleRegion: visibleRegion?.[1],
         preview: preview,
+        classes: classes?.[1]?.split(' '),
       };
       return token;
     }
diff --git a/adev/shared-docs/pipeline/guides/extensions/docs-code/format/index.mts b/adev/shared-docs/pipeline/guides/extensions/docs-code/format/index.mts
@@ -39,6 +39,9 @@ export interface CodeToken extends Tokens.Generic {
 
   /** The generated diff metadata if created in the code formating process. */
   diffMetadata?: DiffMetadata;
+
+  // additional classes for the element
+  classes?: string[];
 }
 
 export function formatCode(token: CodeToken) {
@@ -97,4 +100,8 @@ function applyContainerAttributesAndClasses(el: Element, token: CodeToken) {
   if (token.language === 'shell') {
     el.classList.add('shell');
   }
+
+  if (token.classes) {
+    el.classList.add(...token.classes);
+  }
 }
diff --git a/adev/shared-docs/styles/docs/_code.scss b/adev/shared-docs/styles/docs/_code.scss
@@ -111,6 +111,12 @@ $code-font-size: 0.875rem;
       font-size: $code-font-size;
       counter-reset: line;
     }
+
+    &.compact {
+      pre {
+        max-height: 300px;
+      }
+    }
   }
 
   // shell doesn't have a header, for commands only
diff --git a/adev/src/content/ai/BUILD.bazel b/adev/src/content/ai/BUILD.bazel
@@ -7,6 +7,7 @@ generate_guides(
     ]),
     data = [
         "//adev/src/assets/images:what_is_angular.svg",
+        "//adev/src/context",
     ],
     visibility = ["//adev:__subpackages__"],
 )
diff --git a/adev/src/content/ai/develop-with-ai.md b/adev/src/content/ai/develop-with-ai.md
@@ -8,7 +8,12 @@ Improve your experience generating code with LLMs by using one of the following
 
 NOTE: These files will be updated on a regular basis staying up to date with Angular's conventions.
 
-* <a href="/context/best-practices.md" target="_blank">best-practices.md</a> - a set of instructions to help LLMs generate correct code that follows Angular best practices. This file can be included as system instructions to your AI tooling or included along with your prompt as context.
+Here is a set of instructions to help LLMs generate correct code that follows Angular best practices. This file can be included as system instructions to your AI tooling or included along with your prompt as context.
+
+<docs-code language="md" path="adev/src/context/best-practices.md" class="compact"/>
+
+<!-- Note: download doesnt work in devmode but is fine when deployed -->
+<a download href="/context/best-practices.md" target="_blank">Click here to download the best-practices.md file.</a> 
 
 ## Rules Files
 Several editors, such as <a href="https://studio.firebase.google.com?utm_source=adev&utm_medium=website&utm_campaign=BUILD_WITH_AI_ANGULAR&utm_term=angular_devrel&utm_content=build_with_ai_angular_firebase_studio">Firebase Studio</a> have rules files useful for providing critical context to LLMs.
diff --git a/adev/src/context/BUILD.bazel b/adev/src/context/BUILD.bazel
@@ -0,0 +1,7 @@
+package(default_visibility = ["//adev:__subpackages__"])
+
+filegroup(
+    name = "context",
+    srcs = glob(["**"]),
+    visibility = ["//visibility:public"],
+)

Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,9 @@ export interface CodeToken extends Tokens.Generic {`
`39`	`39`
`40`	`40`	`/** The generated diff metadata if created in the code formating process. */`
`41`	`41`	`diffMetadata?: DiffMetadata;`
	`42`	`+`
	`43`	`+ // additional classes for the element`
	`44`	`+ classes?: string[];`
`42`	`45`	`}`
`43`	`46`
`44`	`47`	`export function formatCode(token: CodeToken) {`
`@@ -97,4 +100,8 @@ function applyContainerAttributesAndClasses(el: Element, token: CodeToken) {`
`97`	`100`	`if (token.language === 'shell') {`
`98`	`101`	`el.classList.add('shell');`
`99`	`102`	`}`
	`103`	`+`
	`104`	`+ if (token.classes) {`
	`105`	`+ el.classList.add(...token.classes);`
	`106`	`+ }`
`100`	`107`	`}`
Original file line number	Diff line number	Diff line change
`@@ -111,6 +111,12 @@ $code-font-size: 0.875rem;`
`111`	`111`	`font-size: $code-font-size;`
`112`	`112`	`counter-reset: line;`
`113`	`113`	`}`
	`114`	`+`
	`115`	`+ &.compact {`
	`116`	`+ pre {`
	`117`	`+ max-height: 300px;`
	`118`	`+ }`
	`119`	`+ }`
`114`	`120`	`}`
`115`	`121`
`116`	`122`	`// shell doesn't have a header, for commands only`
Original file line number	Diff line number	Diff line change
`@@ -7,6 +7,7 @@ generate_guides(`
`7`	`7`	`]),`
`8`	`8`	`data = [`
`9`	`9`	`"//adev/src/assets/images:what_is_angular.svg",`
	`10`	`+ "//adev/src/context",`
`10`	`11`	`],`
`11`	`12`	`visibility = ["//adev:__subpackages__"],`
`12`	`13`	`)`