diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index a7f0157d7..18ebe8ce1 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -147,6 +147,14 @@ export default defineConfig({ collapsed: true, items: [ { label: "Contributor Guide", slug: "contributing" }, + { + label: "Architecture (internals)", + slug: "contributing/architecture", + }, + { + label: "Documentation Style Guide", + slug: "contributing/docs-style-guide", + }, { label: "Translating EmDash", slug: "contributing/translating" }, ], }, diff --git a/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx b/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx index a2ff96094..c4d23991f 100644 --- a/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx +++ b/docs/src/content/docs/coming-from/astro-for-wp-devs.mdx @@ -41,7 +41,7 @@ WordPress themes have a flat structure with magic filenames. Astro uses explicit | `style.css` | `src/styles/` | Global CSS | | `functions.php` | `astro.config.mjs` | Site configuration | -A typical Astro project: +The following tree shows a typical Astro project layout: ``` src/ @@ -64,6 +64,8 @@ src/ 1. **Frontmatter** (between `---` fences) — Server-side code, like PHP at the top of a template 2. **Template** — HTML with expressions, like the rest of a PHP template +The following component declares typed props in the frontmatter and renders them in the template: + ```astro title="src/components/PostCard.astro" --- // Frontmatter: runs on server, never sent to browser @@ -183,7 +185,7 @@ const { title, featured = false } = Astro.props; ``` -Usage: +The following markup uses that component, passing the default slot and a named `footer` slot: ```astro @@ -249,7 +251,7 @@ The difference: slots receive child elements at the call site, while WordPress h ## Layouts -Layouts wrap pages with common HTML structure—the ``, header, footer, and anything shared across pages. This replaces `header.php` + `footer.php`. +Layouts wrap pages with common HTML structure—the ``, header, footer, and anything shared across pages. This replaces `header.php` + `footer.php`. The following layout defines that shared shell and exposes a slot for page content: ```astro title="src/layouts/Base.astro" --- @@ -329,7 +331,7 @@ Styles in a ` ``` -The generated HTML includes unique class names to prevent style leakage. No more specificity wars. +The generated HTML includes unique class names to prevent style leakage, so component styles stay contained without escalating selector specificity. ### Global Styles @@ -402,9 +404,9 @@ For simple interactions, add a `