Merge pull request #14 from PureStackStudio/update-guides

Add new categories to the guides.

Author: koculu

README.md

@@ -45,7 +45,7 @@ stays in Markdown; components, style builders, and scripts live in TypeScript.
 The aim is a source model that remains understandable as the product grows.
 
 `.mdx` and `.rmdx` pages use Regor components and expressions. Plain `.md`
-files work for prose pages. See the [Regor guide](https://purestack.studio/guides/regor/)
+files work for prose pages. See the [Regor guide](https://purestack.studio/guides/extending/regor/)
 for the markup and browser app model.
 
 ## Get your first page running
@@ -128,10 +128,10 @@ has a complete example.
 
 | I want to… | Start here |
 | :--- | :--- |
-| Configure a site | [Site configuration](https://purestack.studio/guides/site-config/) |
+| Configure a site | [Site configuration](https://purestack.studio/guides/getting-started/site-config/) |
 | Build a richer page | [Component catalog](https://purestack.studio/components/) |
 | Add browser behavior | [PageScript and RegorApp examples](packages/purestack/README.md) |
-| Understand the CLI | [CLI guide](https://purestack.studio/guides/purestack-cli/) |
+| Understand the CLI | [CLI guide](https://purestack.studio/guides/getting-started/purestack-cli/) |
 | Explore a complete project | [Sample content](packages/ts-ssg/sample-content) · [Website source](frontend) |
 | Work on PureStack itself | [Contribution guide](CONTRIBUTING.md) |
 
@@ -146,8 +146,8 @@ has a complete example.
 | `PageScript` and `RegorApp` | Bundle TypeScript and add browser behavior where requested. |
 | Static assets | Copies files from the content directory into the site output. |
 
-The [CLI guide](https://purestack.studio/guides/purestack-cli/) covers the
-commands and options. [Site configuration](https://purestack.studio/guides/site-config/)
+The [CLI guide](https://purestack.studio/guides/getting-started/purestack-cli/) covers the
+commands and options. [Site configuration](https://purestack.studio/guides/getting-started/site-config/)
 covers navigation, themes, search, sitemap, localization, and output paths.
 
 </details>

frontend/purestack.studio/components/_nav.json

@@ -1,6 +1,6 @@
 {
   "pageLinks": true,
-  "sequence": ["index.mdx", "guides"],
+  "sequence": ["guides", "index.mdx"],
   "items": [
     {
       "id": "guides",

frontend/purestack.studio/components/actions/alert-box/alert-box.mdx

@@ -18,14 +18,14 @@ nav:
 ## In context
 
 <ComponentExample label="A complete message" caption="Every content feature is visible: eyebrow, title, badge, icon, body, metadata, and the actions slot.">
-<div class="component-recipe"><AlertBox tone="info" variant="spotlight" eyebrow="DESIGN SYSTEM" title="Make feedback useful" badge="Tip" icon="lucide:check" meta="Semantic tones adapt to light and dark themes."><p>Explain what happened, why it matters, and what the reader can do next.</p><template #actions><BtnLink href="/guides/semantic-tones/" tone="info" variant="outline">Explore semantic tones</BtnLink></template></AlertBox></div>
+<div class="component-recipe"><AlertBox tone="info" variant="spotlight" eyebrow="DESIGN SYSTEM" title="Make feedback useful" badge="Tip" icon="lucide:check" meta="Semantic tones adapt to light and dark themes."><p>Explain what happened, why it matters, and what the reader can do next.</p><template #actions><BtnLink href="/guides/styling/semantic-tones/" tone="info" variant="outline">Explore semantic tones</BtnLink></template></AlertBox></div>
 </ComponentExample>
 
 ```html
 <AlertBox tone="info" variant="spotlight" eyebrow="DESIGN SYSTEM" title="Make feedback useful" badge="Tip" icon="lucide:check" meta="Semantic tones adapt to light and dark themes.">
 <p>Explain what happened, why it matters, and what the reader can do next.</p>
 <template #actions>
-<BtnLink href="/guides/semantic-tones/" tone="info" variant="outline">Explore semantic tones</BtnLink>
+<BtnLink href="/guides/styling/semantic-tones/" tone="info" variant="outline">Explore semantic tones</BtnLink>
 </template>
 </AlertBox>
 ```

frontend/purestack.studio/components/actions/btn-link/btn-link.mdx

@@ -20,15 +20,15 @@ Use BtnLink to navigate to a page, a section, or an external destination. For an
 ## In context
 
 <ComponentExample label="A useful destination" caption="These are real links. Use the keyboard or your browser’s open-in-new-tab action to follow them.">
-<div class="component-recipe"><Badge tone="feature">START HERE</Badge><h3>Build your first interface</h3><p>Learn how static content and interactive components fit together.</p><BtnGroup :wrap="true"><BtnLink href="/guides/regor/" tone="accent">Explore Regor</BtnLink><BtnLink href="/components/" variant="outline">Browse components</BtnLink></BtnGroup></div>
+<div class="component-recipe"><Badge tone="feature">START HERE</Badge><h3>Build your first interface</h3><p>Learn how static content and interactive components fit together.</p><BtnGroup :wrap="true"><BtnLink href="/guides/extending/regor/" tone="accent">Explore Regor</BtnLink><BtnLink href="/components/" variant="outline">Browse components</BtnLink></BtnGroup></div>
 </ComponentExample>
 
 ```html
 <Badge tone="feature">START HERE</Badge>
 <h3>Build your first interface</h3>
 <p>Learn how static content and interactive components fit together.</p>
 <BtnGroup :wrap="true">
-<BtnLink href="/guides/regor/" tone="accent">Explore Regor</BtnLink>
+<BtnLink href="/guides/extending/regor/" tone="accent">Explore Regor</BtnLink>
 <BtnLink href="/components/" variant="outline">Browse components</BtnLink>
 </BtnGroup>
 ```

frontend/purestack.studio/components/site/nav-menu/nav-menu-playground.ts

@@ -89,7 +89,7 @@ const TREES: Record<TreeName, NavItem[]> = {
       title: 'Guides',
       icon: 'tabler:book',
       children: [
-        { title: 'Themes', url: '/guides/themes/', icon: 'tabler:palette' },
+        { title: 'Themes', url: '/guides/styling/themes/', icon: 'tabler:palette' },
         {
           title: 'Components',
           icon: 'tabler:components',
@@ -143,7 +143,7 @@ const TREES: Record<TreeName, NavItem[]> = {
 
 const DEFAULTS = {
   treeName: 'docs' as TreeName,
-  currentUrl: '/guides/themes/',
+  currentUrl: '/guides/styling/themes/',
   showIcons: true,
   tone: 'neutral' as SemanticTone,
   variant: 'flat' as ComponentVariant,

frontend/purestack.studio/guides/_nav.json

@@ -3,19 +3,11 @@
   "sequence": [
     "index.mdx",
     "components",
-    "purestack-cli.mdx",
-    "site-config.mdx",
-    "links.mdx",
-    "code-blocks.mdx",
-    "shared-content.mdx",
-    "vscode-extension.mdx",
-    "regor.mdx",
-    "typography.mdx",
-    "utility-css-classes.mdx",
-    "semantic-tones.mdx",
-    "icons.mdx",
-    "themes.mdx",
-    "plugins.mdx"
+    "getting-started/",
+    "content/",
+    "styling/",
+    "extending/",
+    "publishing/"
   ],
   "items": [
     {

frontend/purestack.studio/guides/content/_nav.json

@@ -0,0 +1,9 @@
+{
+  "sequence": [
+    "index.mdx",
+    "links.mdx",
+    "code-blocks.mdx",
+    "shared-content.mdx",
+    "localization.mdx"
+  ]
+}

…/purestack.studio/guides/code-blocks.mdx …ck.studio/guides/content/code-blocks.mdxfrontend/purestack.studio/guides/code-blocks.mdx renamed to frontend/purestack.studio/guides/content/code-blocks.mdx frontend/purestack.studio/guides/code-blocks.mdx renamed to frontend/purestack.studio/guides/content/code-blocks.mdx

@@ -25,7 +25,7 @@ const answer = 42
 ```
 ````
 
-The language selects the highlighting. The [site configuration](./site-config#markdown-and-code-blocks) chooses the highlighter.
+The language selects the highlighting. The [site configuration](../getting-started/site-config#markdown-and-code-blocks) chooses the highlighter.
 
 ## Show a file's code
 

frontend/purestack.studio/guides/content/index.mdx

@@ -0,0 +1,18 @@
+---
+title: Content
+description: Write links and code examples, share content, and organize translations.
+template: doc
+nav:
+  icon: tabler:files
+layout:
+  showToc: true
+---
+
+# Content
+
+Write links and code examples, share content, and organize translations.
+
+- [Links](./links)
+- [Code blocks](./code-blocks)
+- [Shared content](./shared-content)
+- [Localization](./localization)

…ontend/purestack.studio/guides/links.mdx …urestack.studio/guides/content/links.mdxfrontend/purestack.studio/guides/links.mdx renamed to frontend/purestack.studio/guides/content/links.mdx frontend/purestack.studio/guides/links.mdx renamed to frontend/purestack.studio/guides/content/links.mdx

@@ -13,7 +13,7 @@ nav:
 
 # Links
 
-Write a link the way you see your files. PureStack turns it into the right address and checks it every time the site builds, so a renamed or deleted page or image never leaves a broken link behind.
+Write local links relative to the source file. PureStack resolves them to public URLs and fails the build when the target page or asset is missing. Root-relative public URLs, external destinations, and fragment IDs have different validation rules, described below.
 
 ## Link to another page
 
@@ -53,7 +53,7 @@ Add `#` and the section name after the page:
 [Back to the top](#links)
 ```
 
-A section name is its heading in lowercase, with hyphens between the words. The heading "Create a skin" becomes `#create-a-skin`. Try it: [create a skin](./themes#create-a-skin).
+A section name is its heading in lowercase, with hyphens between the words. The heading "Create a skin" becomes `#create-a-skin`. Try it: [create a skin](../styling/themes#create-a-skin).
 
 PureStack checks that the page exists, not the section, so double-check section names after you rename a heading.
 
@@ -103,9 +103,9 @@ Anything that starts with `/` or a protocol is used as written:
 
 PureStack doesn't check these links, because the pages behind them aren't part of your content folder.
 
-You can link your own pages this way too, as in `/guides/themes/`, but a relative link is the better habit: if that page moves, the build tells you.
+You can link your own pages this way too, as in `/guides/styling/themes/`, but a relative link is the better habit: if that page moves, the build tells you.
 
-If the site lives under a base path, such as `/docs`, PureStack adds it to every link for you. Set it once in the [site configuration](./site-config).
+If the site lives under a base path, such as `/docs`, PureStack adds it to every link for you. Set it once in the [site configuration](../getting-started/site-config).
 
 ## When a link is broken