Separate content from repeated page structure
Article prose uses Markdown. Frontmatter holds the title, summary, dates, tags and Open Graph image. Shared Astro layouts render the header, footer, article heading and related links, separating content edits from changes to common UI.
MDX can insert Astro components within prose. Our diagrams combine HTML labels with SVG connections, adding interaction or motion where it helps understanding. Short explanations can remain text.
Content architecture
From sources to published Japanese and English pages
Keep language-specific content, share layouts and metadata, and turn only published entries into static HTML.
Give each language its own source and URL
Japanese and English use the same article identifier with separate MDX sources. Japanese pages live under the root; English pages under /en/. Missing published counterparts and inconsistent dates stop the build.
The language menu opens the corresponding article. There is no browser-language redirect, and content and language links work without JavaScript. English retains the original conditions and cautions while using natural word order, rather than matching Japanese character counts.
Reuse article metadata for discovery and SEO
Frontmatter supplies titles and summaries for the listing, page title and description, and structured data. Published entries populate the sitemap; drafts appear in neither the listing nor deployment files.
Each language has its own canonical URL, with hreflang links between counterparts. The same Open Graph image appears at the top of the article and in the listing, helping readers connect a shared preview with its content. Metadata does not guarantee indexing or ranking.
Keep search in the browser
Readers can search titles, summaries and tags, then narrow results by tag. No external search API receives the query. Both languages support filtering, and switching language preserves filter state.
All article links are present in the initial HTML, so the listing remains readable without search. We avoid creating empty pages for search and tag combinations. More articles or a need for full-text search would be reasons to revisit the index design.
Check the public boundary before deployment
We package only public routes and approved assets from Astro output. Sources, internal documents, configuration and credentials are excluded. Built links, images, languages and metadata are checked before the preview is inspected.
Git lets content and code be reviewed together but requires a development environment to edit. If multiple editors need browser-based updates, a CMS would merit another look. The cloud infrastructure article explains where the files are delivered.
