# Aither > An AI-native Astro theme that believes text itself is beautiful. --- ## ✨ Why Astro-Theme-Aither URL: https://astro-theme-aither.pages.dev/posts/why-astro-theme-aither/ Date: 2026-01-03 Category: Design Tags: Design, Astro Description: An AI-native Astro theme that believes text itself is beautiful. An AI-native Astro theme that believes text itself is beautiful. ## Design Philosophy Minimal design, not minimal engineering. When there are no flashy visuals to hide problems, every flaw gets amplified. Minimal design demands higher engineering quality, not lower. Typography parameters follow Apple Human Interface Guidelines: 17px / 1.47 / -0.022em. A unified sans-serif system font stack across all pages. The typeface is the visual identity. ## AI-Native Built for the age of AI agents. Every page is machine-readable by design: - **llms.txt** — AI agent content index at `/llms.txt` - **llms-full.txt** — full-text output at `/llms-full.txt` - **Markdown endpoints** — append `.md` to any post URL for the raw source file - **JSON-LD** — Article structured data on every post - **robots.txt** — explicitly welcomes GPTBot, ClaudeBot, PerplexityBot Your content is not just published — it is AI-discoverable. ## Built on Astro Astro's islands architecture means only interactive components load JavaScript. Everything else is static HTML and CSS, loaded instantly. Interactive islands: theme switcher (View Transitions API circular reveal), language switcher, browser locale detection, mobile navigation. ## Features - **Tailwind CSS v4** — `@theme` design tokens, full light/dark customization - **i18n** — multi-language support with automatic browser language detection - **Post pinning** — pin important posts to the top - **Dark mode** — Light / Dark / System with View Transitions API animation - **Content Collections** — type-safe Markdown with build-time validation - **SEO** — Open Graph, canonical URLs, Twitter Cards - **RSS + Sitemap** — auto-generated, zero config - **Google Analytics / Crisp Chat / Giscus** — optional, via `.env` - **Vitest + Playwright** — unit + E2E tests in CI - **Deploy** — GitHub Pages (default) + Cloudflare Pages (optional) ## Who Is This For If you believe good writing speaks for itself: - **Bloggers** who want words front and center - **Technical writers** who need clean code blocks and prose - **Multilingual authors** who need i18n with locale detection - **Developers** who appreciate solid engineering they can extend Write about anything — the typography will make it look good. --- ## 📝 Markdown Style Guide URL: https://astro-theme-aither.pages.dev/posts/markdown-guide/ Date: 2026-01-02 Category: Tutorial Tags: Markdown, Guide Description: A comprehensive guide to all supported Markdown features in Astro-Theme-Aither This post demonstrates every Markdown feature supported by Astro-Theme-Aither. Use it as a reference when writing your own posts. Bookmark this page — it covers the full range of formatting options available to you. ## Headings Use `##` for section headings, `###` for subsections, and `####` for sub-subsections. Avoid `#` in post content — the post title is already rendered as the top-level heading. ### Third-Level Heading Third-level headings are ideal for breaking a section into distinct topics. They create visual hierarchy without being too prominent. #### Fourth-Level Heading Fourth-level headings work for fine-grained subsections. Use them sparingly — if your outline goes deeper than four levels, consider restructuring your content. ### Heading Best Practices A few guidelines for effective heading use: - **Do not skip levels** — go from `##` to `###`, never from `##` directly to `####`. Skipping levels breaks the document outline and can confuse screen readers. - **Keep headings descriptive** — "Configuration" is better than "Setup Stuff." Readers scan headings before deciding whether to read a section. - **Use sentence case** — capitalize the first word and proper nouns only. Title Case Feels Like Shouting In Long Documents. ## Paragraphs and Line Breaks Regular paragraph text flows naturally. Leave a blank line between paragraphs to separate them. This is a second paragraph. Keep paragraphs focused on one idea for the best reading experience. When writing for the web, shorter paragraphs tend to work better than long blocks of text. A paragraph of three to five sentences is a comfortable reading unit on screens. If a paragraph runs beyond six or seven sentences, consider splitting it. Single line breaks within a paragraph (without a blank line) will be treated as a space, not a new line. If you need a hard line break without starting a new paragraph, end the line with two spaces or use a `
` tag — though this is rarely needed in practice. ## Emphasis - **Bold text** with `**double asterisks**` - *Italic text* with `*single asterisks*` - ***Bold and italic*** with `***triple asterisks***` - ~~Strikethrough~~ with `~~double tildes~~` ### When to Use Each Style **Bold** works best for key terms, important warnings, or definitions — anything the reader should not miss even when scanning. Use it for the most important phrase in a paragraph, not for entire sentences. *Italics* are for emphasis within a sentence, book and publication titles, technical terms on first use, and foreign phrases. They provide a lighter emphasis than bold. ~~Strikethrough~~ is useful for showing corrections, deprecated information, or completed items in a changelog. It has a narrower set of use cases but is valuable when you need it. ## Links [Inline link](https://astro.build) with `[text](url)` syntax. Links can also reference other posts on your site using relative paths. Use descriptive link text — "read the markdown guide" is better than "click here." Good link text helps both readers and search engines understand where the link leads. You can also create links that open in context by writing descriptive anchor text that reads naturally within the sentence. For example: the [Astro documentation](https://docs.astro.build) covers every feature in detail. ## Lists Unordered list: - First item - Second item - Nested item - Another nested item - Third item Ordered list: 1. First step 2. Second step 1. Sub-step one 2. Sub-step two 3. Third step Task list: - [x] Set up the project - [x] Write your first post - [ ] Deploy to production ### List Formatting Tips Lists are one of the most effective tools in web writing. They break up dense text, make information scannable, and clearly communicate sequences or collections of items. **Use unordered lists** when the items have no inherent sequence — features, requirements, options, or examples. **Use ordered lists** when sequence matters — steps in a process, ranked items, or instructions that must be followed in order. **Use task lists** for tracking progress, project checklists, or to-do items. They render as interactive checkboxes in many Markdown viewers, though in a static blog they appear as visual indicators. Keep list items parallel in structure. If the first item starts with a verb, all items should start with a verb. If the first item is a noun phrase, maintain that pattern throughout. ## Blockquotes > The purpose of abstraction is not to be vague, but to create a new semantic level in which one can be absolutely precise. > > — Edsger W. Dijkstra Nested blockquotes: > First level > > > Second level > > > > > Third level ### Blockquote Usage Blockquotes serve several purposes beyond quoting famous people: - **Citing sources** — when referencing another article, book, or document - **Callouts** — highlighting important information or warnings - **Email-style quoting** — showing what someone said in a conversation you are responding to - **Pull quotes** — drawing attention to a key passage from your own article When using blockquotes for attribution, place the author name on a separate line preceded by an em dash, as shown in the Dijkstra example above. ## Code Inline `code` with backticks. Use inline code for function names like `getPublishedPosts()`, file paths like `src/content/posts/`, command-line instructions like `pnpm dev`, and any literal values that appear in running text. Code block with syntax highlighting: ```typescript interface Post { title: string; date: Date; description?: string; tags?: string[]; draft?: boolean; } function getPublishedPosts(posts: Post[]): Post[] { return posts .filter((post) => !post.draft) .sort((a, b) => b.date.getTime() - a.date.getTime()); } ``` ```css @theme { --font-sans: 'system-ui', sans-serif; --font-serif: 'ui-serif', 'Georgia', serif; } ``` ### Code Block Tips Always specify the language identifier after the opening triple backticks. This enables syntax highlighting, which dramatically improves readability. Common identifiers include `typescript`, `javascript`, `css`, `html`, `bash`, `json`, `python`, and `markdown`. For shell commands, use `bash` or `sh`: ```bash # Install dependencies pnpm install # Start the development server pnpm dev # Build for production pnpm build ``` For JSON configuration files: ```json { "name": "my-blog", "version": "1.0.0", "scripts": { "dev": "astro dev", "build": "astro build" } } ``` Keep code blocks focused. Show only the relevant lines rather than pasting an entire file. If context is needed, add a comment indicating where the code lives. ## Tables | Feature | Status | Notes | |---|---|---| | Dark mode | Supported | Light / Dark / System | | RSS feed | Built-in | `/rss.xml` | | Sitemap | Auto-generated | Via `@astrojs/sitemap` | | SEO | Built-in | Open Graph + canonical | Right-aligned and centered columns: | Left | Center | Right | |:---|:---:|---:| | Text | Text | Text | | Longer text | Longer text | Longer text | ### Table Guidelines Tables work best for structured data with clear columns and rows. They are ideal for feature comparisons, configuration options, API parameters, and reference data. Keep tables simple. If a table has more than five or six columns, it becomes difficult to read on mobile devices. Consider breaking complex tables into multiple smaller ones, or use a list format instead. Column alignment is controlled with colons in the separator row: - `:---` for left alignment (default) - `:---:` for center alignment - `---:` for right alignment Use right alignment for numeric data so decimal points line up visually. ## Horizontal Rule Use `---` to create a horizontal rule: --- Content after the rule. Horizontal rules are useful for separating major sections of a post, indicating a shift in topic, or visually breaking up very long articles. Use them judiciously — if you need frequent separators, headings might be a better structural choice. ## Images Images are supported with standard Markdown syntax: ```markdown ![Alt text](./image.jpg) ``` This theme is typography-focused, but images work when you need them. ### Image Best Practices - **Always include alt text** — it is essential for accessibility and also appears when images fail to load - **Use descriptive file names** — `dashboard-error-state.png` is better than `screenshot-2.png` - **Optimize file sizes** — compress images before adding them to your repository; large images slow down page loads - **Consider the reading flow** — place images near the text that references them, not paragraphs away ## Putting It All Together The Markdown features described in this guide cover the vast majority of what you will need for blog writing. The key to good Markdown is using the right element for the right purpose: headings for structure, emphasis for importance, lists for collections, code blocks for technical content, and paragraphs for everything else. Write clearly, format consistently, and let the typography do its work. --- ## 👋 Hello World URL: https://astro-theme-aither.pages.dev/posts/hello-world/ Date: 2026-01-01 Category: Tutorial Tags: Hello, Astro Description: Welcome to Astro-Theme-Aither — an AI-native Astro theme that believes text itself is beautiful. Welcome to Astro-Theme-Aither. This is an AI-native blog theme built on one belief: text itself is beautiful. A unified sans-serif system font stack, Apple HIG typography parameters, and a layout that stays out of your way. Everything here serves a single goal — making your words look and feel beautiful. ## Why Another Blog Theme The web is full of blog themes, so a fair question is: why build another one? The answer comes down to priorities. Most themes optimize for visual impact — large hero images, complex layouts, animated transitions. These look stunning in a demo but get in the way when someone actually sits down to read a 2,000-word article. Astro-Theme-Aither starts from a different premise. The content is the product. The theme's job is to present that content with the care it deserves: Apple HIG body text parameters (17px / 1.47 / -0.022em), generous whitespace, and a vertical rhythm that makes long-form reading comfortable rather than exhausting. This philosophy extends to the technical decisions too. The theme uses Astro's islands architecture — only interactive components (theme switcher, language switcher, locale detection, mobile nav) load JavaScript. Everything else is static HTML and CSS. No layout shifts, no loading spinners. The page loads, and you read. ## Get Started Getting up and running takes just a few minutes: 1. **Clone the repository** — use the GitHub template button or clone directly with `git clone` 2. **Install dependencies** — run `pnpm install` to pull in all packages 3. **Configure your site** — edit `src/config/site.ts` to set your site title, description, and nav links 4. **Set up services** — copy `.env.example` to `.env` and fill in your API keys (GA, Crisp, Giscus) 5. **Replace sample content** — swap the posts in `src/content/posts/` with your own Markdown files 6. **Start developing** — run `pnpm dev` to launch the local dev server with hot reloading 7. **Deploy** — push to GitHub and let the included CI workflow handle deployment to Cloudflare Pages ### Project Structure ``` src/ ├── components/ # Reusable Astro & React components ├── config/ # Site configuration (site.ts) ├── content/ # Your Markdown posts (organized by locale) ├── i18n/ # Translations and locale utilities ├── layouts/ # Page layouts (Layout.astro) ├── lib/ # Shared utilities (posts, formatter, markdown-endpoint) ├── pages/ # Route pages (per locale) └── styles/ # Global CSS with Tailwind v4 @theme tokens ``` Each directory has a clear responsibility. Components are small and composable. Layouts handle the document shell. Pages define routes. Content holds your writing organized by locale. ### Writing Your First Post Create a new `.md` file in `src/content/posts/en/` with the following frontmatter: ```markdown --- title: Your Post Title date: 2026-01-15 category: General description: A brief summary for SEO and social previews tags: [Topic, Another] pinned: false --- Your content starts here. ``` The `title`, `date`, and `category` fields are required. The `description` field is strongly recommended because it populates the meta description tag and Open Graph previews. Tags are optional. Set `pinned: true` to pin a post to the top of the list. For multilingual content, create the same file in each locale directory (`zh-hans/`, `ko/`, `fr/`, etc.) with translated content. ## What You Get Out of the box, you have a production-ready blogging platform with every feature you need and none of the bloat you don't. ### Content Features - **RSS feed** — automatically generated at `/rss.xml` - **Sitemap** — auto-generated via `@astrojs/sitemap` - **SEO meta tags** — Open Graph, Twitter cards, and canonical URLs on every page - **JSON-LD** — Article structured data for AI and search engines - **Dark mode** — Light / Dark / System toggle with circular reveal animation via View Transitions API - **i18n** — multi-language support with automatic browser language detection - **Post pinning** — pin important posts to the top of the list - **Pagination** — file-based SSG pagination with page number navigation ### AI-Native Features - **llms.txt** — AI agent content index at `/llms.txt` - **llms-full.txt** — full-text content for AI consumption at `/llms-full.txt` - **Markdown endpoints** — append `.md` to any post URL for clean Markdown output - **robots.txt** — explicitly welcomes AI crawlers (GPTBot, ClaudeBot, PerplexityBot) ### Developer Features - **TypeScript throughout** — strict mode, fully typed components and utilities - **Content Collections** — type-safe Markdown with frontmatter validation at build time - **Tailwind CSS v4** — `@theme` design tokens for easy customization - **Vitest + Playwright** — unit tests and end-to-end tests in CI - **Deploy** — GitHub Pages (default) + Cloudflare Pages (optional) - **Google Analytics** — optional, via environment variable - **Crisp Chat** — optional live chat, via environment variable - **Giscus Comments** — optional GitHub Discussions powered comments ### Performance Because the theme outputs static HTML with minimal JavaScript islands, performance is excellent by default. You should expect Lighthouse scores of 100 across the board — Performance, Accessibility, Best Practices, and SEO. ## Customization - **Colors** — edit CSS custom properties in `src/styles/global.css` - **Fonts** — swap font-family values in the Tailwind theme configuration - **Navigation** — update nav links in `src/config/site.ts` - **Services** — set environment variables in `.env` for GA, Crisp, and Giscus - **Languages** — add new locales in `src/i18n/` and create corresponding page routes For deeper changes, the component architecture is deliberately simple. Each component does one thing, reads its props, and renders HTML. ## A Note on Design Philosophy The visual simplicity of this theme is intentional, but it is not the same as engineering simplicity. Under the hood, the theme handles a surprising number of concerns: Apple HIG typography parameters, accessible color contrast ratios in both light and dark modes, View Transitions API animations, automatic browser language detection, proper semantic HTML structure, AI-friendly content endpoints, and careful attention to the reading experience on screens ranging from phones to ultrawide monitors. Good design is invisible. When you read an article on this theme and simply enjoy the writing without noticing the theme at all — that is the design working exactly as intended. Happy writing. --- ## AI Agents and Tool Use (Sample) URL: https://astro-theme-aither.pages.dev/posts/ai-agents-and-tool-use/ Date: 2026-01-09 Category: AI Tags: AI, Agents Description: How AI models go beyond chat by executing actions in the real world An AI agent is a language model that can take actions — not just generate text. It can search the web, run code, call APIs, read files, and make decisions about what to do next. This shift from passive text generation to active problem-solving represents one of the most significant developments in applied AI. ## From Chat to Action A chatbot answers questions. An agent solves problems. The difference is autonomy: agents decide which tools to use, in what order, and how to handle errors. Consider the difference in practice. You ask a chatbot: "What's the weather in Tokyo?" It might tell you based on its training data — which is months or years old and almost certainly wrong. You ask an agent the same question, and it calls a weather API, retrieves the current data, and returns an accurate, up-to-date answer. The chatbot generates plausible text. The agent interacts with the world. ### The Spectrum of Autonomy Not all agents are equally autonomous. There is a spectrum: 1. **Tool-assisted chat** — the model can call tools, but only in direct response to user requests. One tool call per turn. 2. **Multi-step agents** — the model can chain multiple tool calls together to accomplish a task, deciding the sequence on its own. 3. **Fully autonomous agents** — the model operates independently over extended periods, making decisions, handling errors, and pursuing goals with minimal human oversight. Most production systems today sit at levels 1-2. Fully autonomous agents are an active area of research with significant safety challenges still to solve. ## Tool Use Tool use lets an AI model call external functions. The model decides when a tool is needed, generates the right parameters, and incorporates the result into its response. This turns a text generator into a capable assistant. ### How Tool Use Works The mechanics are straightforward: 1. **Tool definition** — you describe the available tools to the model, including their names, parameters, and what they do. This is typically provided as structured JSON in the system prompt or via a dedicated API field. 2. **Decision** — when processing a user request, the model decides whether a tool would be helpful. If so, it generates a tool call with the appropriate parameters. 3. **Execution** — your application executes the tool call (the model does not execute it directly) and returns the result. 4. **Integration** — the model incorporates the tool result into its response to the user. ### Example Tool Definition ```json { "name": "search_documentation", "description": "Search the product documentation for relevant articles", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query" }, "max_results": { "type": "integer", "description": "Maximum number of results to return", "default": 5 } }, "required": ["query"] } } ``` The model sees this definition and knows it can search documentation. When a user asks a product question, the model generates a call like `search_documentation(query="how to reset password")`, your system executes the search, and the model uses the results to compose an accurate answer. ### Common Tool Categories Production agent systems typically offer tools in several categories: - **Information retrieval** — web search, database queries, file reading, API calls - **Code execution** — running Python, JavaScript, or shell commands in a sandboxed environment - **Communication** — sending emails, posting messages, creating tickets - **File manipulation** — creating, editing, and organizing files - **System operations** — deploying code, managing infrastructure, running CI pipelines The tools you provide define the boundaries of what the agent can do. A well-designed tool set gives the agent enough capability to be useful without enough power to be dangerous. ## Agentic Loops The most powerful pattern is the agentic loop: the model plans a step, executes it, observes the result, and decides the next step. This loop continues until the task is complete or the model determines it cannot proceed. ### The Loop in Practice Consider an agent tasked with debugging a failing test: 1. **Plan** — "I should first read the test file to understand what it's testing" 2. **Execute** — calls `read_file("tests/auth.test.ts")` 3. **Observe** — sees the test expects a 200 status but gets a 401 4. **Plan** — "I should check the auth middleware to see what's returning 401" 5. **Execute** — calls `read_file("src/middleware/auth.ts")` 6. **Observe** — finds that the token validation logic has a bug in the expiration check 7. **Plan** — "I should fix the expiration comparison" 8. **Execute** — calls `edit_file(...)` with the fix 9. **Observe** — confirms the edit was made 10. **Plan** — "I should run the test to verify the fix" 11. **Execute** — calls `run_command("pnpm test tests/auth.test.ts")` 12. **Observe** — test passes 13. **Complete** — reports the fix to the user Each step involves the model reasoning about the current state, deciding what to do next, and adapting based on what it discovers. This is fundamentally different from a linear script — the agent handles unexpected findings and changes course when needed. ### Handling Errors in the Loop Robust agents must handle failures gracefully. A tool might return an error, a file might not exist, or an API might be rate-limited. Good agent design includes: - **Retry logic** — retry transient failures with backoff - **Alternative strategies** — if one approach fails, try another - **Graceful degradation** — if the task cannot be completed fully, complete as much as possible and explain what remains - **Loop limits** — set a maximum number of iterations to prevent infinite loops when the agent gets stuck ## Designing Effective Tools The quality of an agent system depends heavily on the quality of its tools. Poorly designed tools lead to confused agents and incorrect results. ### Tool Design Principles - **Clear names** — `search_users` is better than `query_db_1`. The model uses the name to decide when to call the tool. - **Descriptive parameters** — include descriptions for every parameter. The model reads these descriptions to determine what values to pass. - **Focused scope** — each tool should do one thing well. A `read_file` tool and a `write_file` tool are better than a `file_operations` tool with a mode parameter. - **Useful errors** — return clear error messages that help the model understand what went wrong and what to try instead. - **Idempotent when possible** — tools that can be safely retried simplify error handling. ## Risks Agents that can take actions can take wrong actions. Sandboxing, confirmation steps, and human-in-the-loop reviews are essential safety measures for any production agent system. ### Categories of Risk - **Destructive actions** — an agent with file system access could delete important files. An agent with database access could drop tables. Sandbox environments and permission boundaries are essential. - **Data exfiltration** — an agent that can both read sensitive data and make network requests could inadvertently (or through prompt injection) leak information. - **Runaway costs** — an agent in a loop calling expensive APIs can rack up significant costs quickly. Budget limits and rate limiting are practical necessities. - **Incorrect actions taken confidently** — the agent might misunderstand a request and take an irreversible action. For high-stakes operations, always require human confirmation. ### Safety Patterns Production agent systems should implement several safety patterns: 1. **Least privilege** — give the agent only the tools it needs for its specific task, nothing more 2. **Sandboxing** — execute code and file operations in isolated environments 3. **Confirmation gates** — require human approval for destructive or irreversible actions 4. **Audit logging** — record every tool call and its result for review 5. **Kill switches** — provide mechanisms to immediately halt a running agent 6. **Budget limits** — set hard caps on API calls, token usage, and compute time The goal is not to prevent agents from being useful — it is to ensure they are useful within well-defined boundaries.