Creating a new post

Where posts live

Directorysrc/content/docs/
- Directorykubernetes/ top-level section
  - Directorynetworking/ nested group (auto-created from folder)
    services-explained.md
  - Directorysecurity/
    rbac-basics.mdx use .mdx when you need JSX components
- Directoryazure/az305/ two levels of nesting is fine
  - …
- Directoryreference/ non-topic pages (guides, showcases)
  - …
- Directoryworkflow/ this section
  - …

The path becomes the URL — kubernetes/networking/services-explained.md is served at /kubernetes/networking/services-explained/.

The ten-second version

In Obsidian, Ctrl+N to create a new note inside the right folder.
Paste the frontmatter template below.
Write.
Ctrl+Shift+S — obsidian-git commits and pushes. Vercel deploys.

Use plain .md for anything that is just prose + code blocks + images.

Works fully in Obsidian preview. No import line at the top. Asides use Starlight’s directive syntax:

:::note
Directive-syntax asides work in `.md` — no import needed.
:::

:::tip[Optional title]
Text.
:::

:::caution
:::

:::danger
:::

Switch to .mdx when you want Tabs, Cards, Steps, Badge, FileTree, LinkCard, or any JSX component.

Obsidian will show the import line as raw text — that’s cosmetic only. Save and it renders correctly on the site.

---
title: My post
---

import { Aside, Tabs, TabItem, Badge } from '@astrojs/starlight/components';

<Badge text="Lab" variant="tip" />

<Tabs>
  <TabItem label="One">Content</TabItem>
  <TabItem label="Two">More content</TabItem>
</Tabs>

Copy-paste starter template (`.md`)

---
title: Your post title
description: One sentence for search and social previews (≤160 chars).
date: 2026-07-30
tags: [kubernetes, networking]
# showDate: true       # uncomment to reveal the date in Recent posts + page header
# draft: true          # hide from Recent posts while writing
---

Opening paragraph — the *why* and what the reader will walk away with.

## Section heading

Body content. Code blocks, images, callouts.

:::tip[Optional title]
Directive-syntax asides render as Starlight `<Aside>` blocks.
:::

## Related

- [Sibling post](/kubernetes/networking/services-explained/)

Copy-paste starter template (`.mdx`)

---
title: Your post title
description: One sentence for search and social previews (≤160 chars).
date: 2026-07-30
tags: [kubernetes, networking]
---

import { Aside, Tabs, TabItem, Steps, Card, CardGrid, LinkCard, Badge, FileTree } from '@astrojs/starlight/components';

<Badge text="Lab" variant="tip" />

Opening paragraph.

<Aside type="tip" title="Optional title">
  Rich JSX asides.
</Aside>

<Steps>
1. First
2. Second
3. Third
</Steps>

Publishing checklist

Title in frontmatter — Starlight refuses to build without it.
Description ≤ 160 chars — used for SEO and social preview.
Date in ISO format (2026-07-30) — only needed if showDate: true.
Tags kebab-case ([kubernetes, saa-c03]) — lowercase, no spaces.
Draft? Set draft: true to hide from Recent posts while writing.
Preview locally — pnpm dev if you want to double-check components.
Push — Ctrl+Shift+S in Obsidian or git push in the terminal.