From 722b35e1a4c38a6591e2991183fc3ce6e3afc048 Mon Sep 17 00:00:00 2001
From: Aramis Sennyey <159921952+aramissennyeydd@users.noreply.github.com>
Date: Mon, 13 Apr 2026 10:23:44 -0400
Subject: [PATCH] docs: use accordions for common issues in golden-path
 (#33840)

* fix: use accordions for common issues

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

* fix code block

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>

---------

Signed-off-by: aramissennyeydd <aramis.sennyey@doordash.com>
---
 docs/contribute/doc-style-guide.md            | 31 ++++++++++++++++++
 .../plugins/frontend/001-first-steps.md       | 32 +++++++++++++------
 2 files changed, 54 insertions(+), 9 deletions(-)

diff --git a/docs/contribute/doc-style-guide.md b/docs/contribute/doc-style-guide.md
index 901df0c55c..3aa56b336f 100644
--- a/docs/contribute/doc-style-guide.md
+++ b/docs/contribute/doc-style-guide.md
@@ -157,6 +157,37 @@ dilute their impact and make the content harder to read. If a section has
 more than two admonitions, restructure the content so that most of the
 information is in regular paragraphs.
 
+## Accordions
+
+Use HTML `<details>` and `<summary>` elements to create collapsible sections.
+These are useful for "Common issues" sections, lengthy reference tables, or
+supplementary content that would otherwise break the reading flow.
+
+```markdown
+<details>
+  <summary>Summary text visible when collapsed</summary>
+
+Content inside the accordion. You can use **Markdown** here, including code
+blocks, lists, and other formatting.
+
+</details>
+```
+
+<details>
+  <summary>Summary text visible when collapsed</summary>
+
+Content inside the accordion. You can use **Markdown** here, including code
+blocks, lists, and other formatting.
+
+</details>
+
+Leave a blank line after the `<summary>` tag and before the closing
+`</details>` tag so that Markdown content inside renders correctly.
+
+Use backticks for inline code inside `<summary>` elements instead of HTML
+`<code>` tags. Backticks render correctly inside summary elements and keep
+the source consistent with the rest of the Markdown content.
+
 ## Markdown elements
 
 ### Line breaks
diff --git a/docs/golden-path/plugins/frontend/001-first-steps.md b/docs/golden-path/plugins/frontend/001-first-steps.md
index 5ece316d9f..d229933cf0 100644
--- a/docs/golden-path/plugins/frontend/001-first-steps.md
+++ b/docs/golden-path/plugins/frontend/001-first-steps.md
@@ -88,12 +88,26 @@ yarn workspace @internal/plugin-todo start
 
 ## Common issues
 
-- **Plugin page not showing up.** Verify that `app.packages` is set to `all`
-  in your `app-config.yaml`. If you use include/exclude filters, make sure your
-  plugin package is not excluded.
-- **`yarn new --select frontend-plugin --option pluginId=todo --option owner=` fails during installation.** Make sure
-  you have run `yarn install` in the repository root first and that your
-  Node.js version matches the one required by the project.
-- **TypeScript errors after scaffolding.** Run `yarn tsc` from the repository
-  root to check for type errors. A fresh scaffold should compile cleanly — if
-  not, try running `yarn install` again.
+<details>
+  <summary>Plugin page not showing up</summary>
+
+Verify that `app.packages` is set to `all` in your `app-config.yaml`. If you
+use include/exclude filters, make sure your plugin package is not excluded.
+
+</details>
+
+<details>
+  <summary>`yarn new` fails during installation</summary>
+
+Make sure you have run `yarn install` in the repository root first and that
+your Node.js version matches the one required by the project.
+
+</details>
+
+<details>
+  <summary>TypeScript errors after scaffolding</summary>
+
+Run `yarn tsc` from the repository root to check for type errors. A fresh
+scaffold should compile cleanly — if not, try running `yarn install` again.
+
+</details>