using components

This site includes several reusable components you can use in your content. Here’s how to use them effectively.

Icons

The site uses the Astro Icon component with Tabler and Simple Icons sets:

import { Icon } from 'astro-icon/components';

<Icon name="tabler:home" class="w-6 h-6" />
<Icon name="simple-icons:github" class="w-6 h-6" />

Example icons:

Code Blocks

In MDX Files

In MDX files, use standard markdown code blocks with optional features:

```javascript filename="utils.js" {2,4}
function greet(name) {
console.log(`Hello, ${name}!`); // This line is highlighted

return `Welcome, ${name}`; // This line is also highlighted
}
```

In Astro Files

When working in .astro files, import and use the CodeBlock component directly:

---
import PageLayout from '@layouts/PageLayout.astro';
import CodeBlock from '@components/ui/CodeBlock.astro';

const exampleCode = `function fibonacci(n) {
if (n <= 1) return n;
return fibonacci(n - 1) + fibonacci(n - 2);
}`;

---

<CodeBlock
code={exampleCode}
lang="javascript"
filename="fibonacci.js"
showLineNumbers={true}
highlightLines={[2, 3]}
/>

Code Block Features

• Syntax highlighting for multiple languages
• Line numbers (automatic for code > 3 lines)
• Line highlighting with {1,3-5} syntax
• Filename display with filename="example.js"
• Copy button for easy code copying

Blog Components

BlogTag

Used for displaying tags:

import BlogTag from '@components/atoms/BlogTag.astro';

<BlogTag tag="astro" href="/blog/tag/astro" />
;

BlogPostCard

For displaying blog post previews in listings.

UI Components

ThemeToggle

The dark/light mode switcher in the header.

Search

Site-wide search functionality (press ⌘K or Ctrl+K).

TableOfContents

Automatically generated for wiki and blog pages with multiple sections.

ContentContainer & ContentSection

Layout components for consistent spacing and styling:

<ContentContainer class="max-w-4xl mx-auto" staggerDelay={50}>
<ContentSection>
  <h2>Section Title</h2>
  <p>Content goes here...</p>
</ContentSection>
</ContentContainer>

Figure

For displaying images with captions in a semantic, accessible way:

import Figure from '@components/ui/Figure.astro';
import myImage from '@assets/images/example-image.png';

// With local image and simple caption

<Figure
src={myImage}
alt="Description of the image"
caption="Optional caption text that appears below the image"
width={800}
/>

// With remote image

<Figure
src="https://example.com/image.jpg"
alt="Remote image description"
caption="Remote images are also supported"
width={1200}
height={600}
/>

// With rich HTML caption using slot

<Figure src={myImage} alt="Description of the image" width={800}>
<Fragment slot="caption">
  Caption with <a href="/link">links</a>, <strong>bold</strong>, or any HTML content
</Fragment>
</Figure>

The Figure component:

• Uses semantic <figure> and <figcaption> HTML elements
• Automatically optimizes local images with multiple formats (AVIF, WebP)
• Provides consistent styling with proper spacing and typography
• Centers images and captions by default
• Applies subtle hover effects
• Supports both simple text captions (via caption prop) and rich HTML captions (via caption slot)

Wiki Components

WikiTag

For displaying wiki tags with links:

import WikiTag from '@components/atoms/WikiTag.astro';

<WikiTag tag="documentation" href="/wiki/tag/documentation" />
;

Example: example

SimpleGraph

For visualizing relationships between wiki pages (used in graph view).

Component Organization

src/components/
├── atoms/        # Small, single-purpose components
├── molecules/    # Combinations of atoms
├── organisms/    # Complex, self-contained sections
├── ui/          # General interface components
├── wiki/        # Wiki-specific components
├── mdx/         # MDX-specific components
├── layout/      # Page layout components
└── SEO/         # SEO and meta components

Best Practices

1. Import only what you need - Don’t import components you’re not using
2. Check existing examples - Look at other pages for usage patterns
3. Use semantic HTML - Components enhance, not replace, good HTML
4. Follow the design system - Use existing utility classes
5. Test responsiveness - Ensure components work on all screen sizes

Creating Custom Components

When creating new components:

1. Place in the appropriate directory based on complexity
2. Use TypeScript interfaces for props
3. Follow the existing naming conventions
4. Include proper ARIA attributes for accessibility
5. Test in both light and dark modes