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:

example.mdx jsx

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:

code-example.md markdown

```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:

MyComponent.astro astro

---
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:

tag-example.mdx jsx

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).

ContentContainer & ContentSection

Layout components for consistent spacing and styling:

layout-example.astro astro

<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:

figure-example.mdx jsx

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

// With local image

<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}
/>

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

Wiki Components

WikiTag

For displaying wiki tags with links:

wiki-tag.mdx jsx

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

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

Creating Custom Components

When creating new components:

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