{
  "$type": "site.standard.document",
  "canonicalUrl": "https://notes.juergen.social/blog/getting-started-v2",
  "coverImage": {
    "$type": "blob",
    "ref": {
      "$link": "bafkreieqhfhjpsr2icq2ft6jt4xccbd6gyqqtt5edsukdvxpnz25a5umwi"
    },
    "mimeType": "image/jpeg",
    "size": 390207
  },
  "description": "Clone, edit one config file, write one real post, deploy. The shortest path through the starter.",
  "path": "/blog/getting-started-v2",
  "publishedAt": "2026-04-15T00:00:00.000Z",
  "site": "at://did:plc:2n2ukq3osdu3k37ncpn6hwiy/site.standard.publication/3mn57dpj54425",
  "tags": "Getting Started",
  "textContent": "The starter is a small Astro site. By the end of this post you will have your name on the home page, one real post, and a deploy that points to your domain.\n\nSkip any step that does not apply.\n\nInstall\n\nThe dev server runs at http://localhost:4321. If the port is taken, Astro picks the next free one and prints it.\n\nEdit one config file\n\nOpen astro-theme-config.ts. This is the only file you need to touch for site-wide settings.\n\nThree rules:\n\n1. url is the production origin. Set base only when deploying under a subpath, such as GitHub Pages project sites.\n2. title shows in the browser tab and in social previews.\n3. logoLabel is the text in the header next to the home link. Keep it short — it sits in a 52px bar.\n\nThe other fields can wait.\n\nKnow where things live\n\nThe starter keeps the public surface small. Most changes happen in one of these places:\n\nUse astro-theme-config.ts first. Reach into src/styles/ for site-level styles, prose, page layouts, and shared behavior. Reach into src/components/ when component structure or component-owned styles need to change.\n\nDecide what the header shows\n\nnav is empty by default. The logo links home, the theme toggle sits on the right, and that is it.\n\nIf you want header links:\n\nFooter links live in footerNav and stay visible regardless. A quiet header with a useful footer is a fine combination.\n\nWrite the first post\n\nPosts live in src/content/blog/. The filename becomes the URL slug.\n\nCreate src/content/blog/hello.md:\n\nRequired: title, description, pubDate. Everything else is optional.\n\n- draft: true keeps the post out of the build, the RSS feed, and the search index.\n- category powers the filter row on /blog. Pick from config.content.categoryOrder or add a new one.\n- heroImage is a relative path to a file inside src/assets/. It feeds cards, social metadata, and structured data; place the image in the Markdown body too when the post should show it inline.\n- homeHeroOrder: 1 pins a post into one of the two compact links at the top of the home page. Lower numbers appear first; unpinned posts fill any empty slots by publish date.\n- homeFeatured: true pins one post to the large feature card on the home page.\n- homeOrder: 1 pins a post into the home page grid. Lower numbers appear first; unpinned posts fill any empty slots by publish date.\n- focusEffect: 'scroll-dark' enables the optional scroll dark effect for that post. It turns on after the reader passes roughly the first 20% of the article body and restores the previous theme near the top. The trigger point is set by the theme; it is not section-specific.\n\nReplace the samples\n\nThe starter ships with sample posts to exercise the layout. Replace or delete them before you publish.\n\nThe fastest path:\n\n1. Keep this guide if you find it useful.\n2. Delete the others from src/content/blog/.\n3. Add three or four of your own.\n\nThe blog index, RSS, related posts, and search update on the next build.\n\nRun the checks\n\nBefore deploying:\n\ncheck runs Astro's type checks. build writes the static site and the Pagefind search index to dist/. preview serves the built output so you can click through it once.\n\nIf check fails, fix it before deploying. Type errors in the starter usually point at a missing field in astro-theme-config.ts.\n\nDeploy\n\nTone builds to dist/. Most hosts only need:\n\n| Setting          | Value           |\n| ---------------- | --------------- |\n| Build command    | npm run build |\n| Output directory | dist          |\n| Node             | 22.12 or newer  |\n\nVercel, Netlify, and Cloudflare Pages all detect Astro automatically. Import the repository, accept the defaults, deploy.\n\nAfter the first live deploy, set site.url in astro-theme-config.ts to the real domain and redeploy. Canonical links, RSS, sitemap, and social previews all depend on it.\n\nIf you deploy under a subpath such as username.github.io/repo, set site.base in astro-theme-config.ts before publishing. The Astro config reads that value for you.\n\nThe bundled GitHub Pages workflow sets ASTRO_SITE_URL and ASTRO_SITE_BASE automatically for project pages. For example, a repository named my-blog deploys with /my-blog; a user site repository named username.github.io deploys at the domain root.\n\nEnable comments (optional)\n\nComments are off by default. To turn on giscus:\n\n1. Visit https://giscus.app and pick a repository with Discussions enabled.\n2. Copy the four values it generates (repo, repoId, category, categoryId) into config.comments.giscus.\n3. Set config.comments.mode to giscus for the original widget, or giscus-custom for the Tone-styled widget.\n\nThe component renders nothing until all four values are present. There is no half-enabled state.\n\nWhat to read next\n\n- Markdown You Will Actually Use — the prose styles in one page.\n- Change the Look in One File — color, spacing, type.\n- When to Reach for MDX — using an Astro component inside a post.",
  "title": "Set Up Astro Tone in Ten Minutes"
}