Libx Sample Documentation

Customization

Learn how to customize and extend the documentation system to fit your specific requirements, from basic styling to advanced configuration.

Theme Customization

CSS Custom Properties

The documentation system uses CSS custom properties for theming. Override these in your custom CSS:

/* Custom theme colors */
:root {
  --color-primary: #your-brand-color;
  --color-secondary: #your-secondary-color;
  --color-accent: #your-accent-color;
  
  /* Typography */
  --font-family-sans: 'Your Font', system-ui, sans-serif;
  --font-family-mono: 'Your Mono Font', 'Fira Code', monospace;
  
  /* Spacing */
  --space-unit: 0.25rem;
  --space-xs: calc(var(--space-unit) * 1);
  --space-sm: calc(var(--space-unit) * 2);
  --space-md: calc(var(--space-unit) * 4);
  --space-lg: calc(var(--space-unit) * 6);
  --space-xl: calc(var(--space-unit) * 8);
}

Dark Mode Support

Customize dark mode appearance:

[data-theme="dark"] {
  --color-background: #1a1a1a;
  --color-text: #e1e1e1;
  --color-border: #333333;
  --color-sidebar-bg: #242424;
}

Component Styling

Override component styles with specific selectors:

/* Custom sidebar styling */
.sidebar {
  background: linear-gradient(180deg, #f8f9fa 0%, #e9ecef 100%);
  border-right: 2px solid var(--color-primary);
}

/* Custom button styling */
.btn-primary {
  background: linear-gradient(45deg, #ff6b6b, #4ecdc4);
  border: none;
  box-shadow: 0 4px 15px rgba(0, 0, 0, 0.2);
}

/* Custom code block styling */
.astro-code {
  border-radius: 12px;
  padding: 1.5rem;
  border: 1px solid var(--color-border);
}

Configuration Customization

Project Configuration

Extend project.config.ts with custom settings:

const projectConfig = {
  // Standard settings
  name: 'Your Project Name',
  description: 'Your project description',
  baseUrl: '/docs/your-project',
  
  // Custom features
  features: {
    search: true,
    analytics: true,
    feedback: true,
    editOnGitHub: true
  },
  
  // Custom navigation
  customNav: [
    { label: 'API', href: 'https://api.yourproject.com' },
    { label: 'GitHub', href: 'https://github.com/your/repo' },
    { label: 'Discord', href: 'https://discord.gg/your-server' }
  ],
  
  // SEO configuration
  seo: {
    siteName: 'Your Project Docs',
    twitterHandle: '@yourhandle',
    ogImage: '/images/og-image.png'
  }
};

Astro Configuration

Customize the Astro configuration for advanced needs:

// astro.config.mjs
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  integrations: [mdx()],
  
  // Custom routing
  routing: {
    prefixDefaultLocale: false
  },
  
  // Build optimization
  build: {
    inlineStylesheets: 'auto'
  },
  
  // Custom markdown configuration
  markdown: {
    shikiConfig: {
      theme: 'github-dark',
      langs: ['javascript', 'typescript', 'bash', 'yaml']
    }
  }
});

Custom Components

Creating Custom Components

Create project-specific components:

// src/components/CustomAlert.astro
---
interface Props {
  type: 'info' | 'warning' | 'error' | 'success';
  title?: string;
  icon?: string;
}

const { type, title, icon } = Astro.props;
---

<div class={`custom-alert custom-alert--${type}`}>
  {icon && <span class="custom-alert__icon">{icon}</span>}
  {title && <h4 class="custom-alert__title">{title}</h4>}
  <div class="custom-alert__content">
    <slot />
  </div>
</div>

<style>
.custom-alert {
  padding: 1rem;
  border-radius: 8px;
  border-left: 4px solid;
  margin: 1rem 0;
}

.custom-alert--info {
  background: #e3f2fd;
  border-color: #2196f3;
  color: #0d47a1;
}

.custom-alert--warning {
  background: #fff3e0;
  border-color: #ff9800;
  color: #e65100;
}

.custom-alert--error {
  background: #ffebee;
  border-color: #f44336;
  color: #c62828;
}

.custom-alert--success {
  background: #e8f5e8;
  border-color: #4caf50;
  color: #2e7d32;
}
</style>

Using Custom Components

Import and use in your documentation:

---
title: "My Document"
---

import CustomAlert from '../../components/CustomAlert.astro';

# My Document

<CustomAlert type="info" title="Important Note" icon="ℹ️">
  This is custom alert component with enhanced styling.
</CustomAlert>

Layout Customization

Custom Page Layouts

Create specialized layouts for different content types:

---
// src/layouts/APILayout.astro
import BaseLayout from './BaseLayout.astro';

interface Props {
  title: string;
  description?: string;
  apiVersion?: string;
}

const { title, description, apiVersion } = Astro.props;
---

<BaseLayout title={title} description={description}>
  <div class="api-layout">
    <header class="api-header">
      <h1>{title}</h1>
      {apiVersion && <span class="api-version">v{apiVersion}</span>}
      {description && <p class="api-description">{description}</p>}
    </header>
    
    <nav class="api-nav">
      <!-- API-specific navigation -->
    </nav>
    
    <main class="api-content">
      <slot />
    </main>
    
    <aside class="api-sidebar">
      <!-- API reference sidebar -->
    </aside>
  </div>
</BaseLayout>

Custom Homepage

Create a custom landing page:

---
// src/pages/index.astro
import MainLayout from '../layouts/MainLayout.astro';
import { Button, Card, Icon } from '@docs/ui';
---

<MainLayout title="Welcome to Your Documentation">
  <section class="hero">
    <h1>Your Project Documentation</h1>
    <p>Everything you need to get started and master our platform.</p>
    <div class="hero-actions">
      <Button href="/en/v2/guide/getting-started" size="large">
        Get Started
      </Button>
      <Button href="/en/v2/components/overview" variant="outline" size="large">
        Browse Components
      </Button>
    </div>
  </section>
  
  <section class="features">
    <div class="feature-grid">
      <Card title="Quick Start" icon="rocket">
        Get up and running in minutes with our step-by-step guide.
      </Card>
      <Card title="Components" icon="puzzle">
        Rich UI components to enhance your documentation.
      </Card>
      <Card title="Customizable" icon="paint-brush">
        Fully customizable to match your brand and needs.
      </Card>
    </div>
  </section>
</MainLayout>

Advanced Features

Search Integration

Add custom search functionality:

// src/utils/search.ts
export interface SearchResult {
  title: string;
  url: string;
  excerpt: string;
  category: string;
}

export async function searchDocuments(query: string): Promise<SearchResult[]> {
  // Implementation depends on your search backend
  // Could be Algolia, Elasticsearch, or local search
  
  const response = await fetch(`/api/search?q=${encodeURIComponent(query)}`);
  return response.json();
}

Analytics Integration

Track documentation usage:

// src/utils/analytics.ts
export function trackPageView(url: string, title: string) {
  // Google Analytics
  if (typeof gtag !== 'undefined') {
    gtag('config', 'GA_MEASUREMENT_ID', {
      page_title: title,
      page_location: url
    });
  }
  
  // Custom analytics
  fetch('/api/analytics/pageview', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ url, title, timestamp: Date.now() })
  });
}

Custom Build Process

Extend the build process with custom scripts:

// scripts/custom-build.js
import { execSync } from 'child_process';
import fs from 'fs';
import path from 'path';

// Generate custom metadata
function generateMetadata() {
  const metadata = {
    buildTime: new Date().toISOString(),
    version: process.env.npm_package_version,
    commit: execSync('git rev-parse HEAD').toString().trim()
  };
  
  fs.writeFileSync(
    path.join('dist', 'metadata.json'),
    JSON.stringify(metadata, null, 2)
  );
}

// Custom post-build optimizations
function optimizeAssets() {
  // Compress images, optimize CSS, etc.
  execSync('imagemin dist/images/** --out-dir=dist/images-optimized');
}

// Run custom build steps
generateMetadata();
optimizeAssets();

Performance Optimization

Bundle Optimization

Optimize JavaScript bundles:

// astro.config.mjs
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          'vendor': ['react', 'react-dom'],
          'ui': ['@docs/ui'],
          'utils': ['@docs/utils']
        }
      }
    }
  }
});

Image Optimization

Optimize images automatically:

---
// src/components/OptimizedImage.astro
import { Image } from '@astrojs/image/components';

interface Props {
  src: string;
  alt: string;
  width?: number;
  height?: number;
  loading?: 'lazy' | 'eager';
}

const { src, alt, width = 800, height, loading = 'lazy' } = Astro.props;
---

<Image
  src={src}
  alt={alt}
  width={width}
  height={height}
  loading={loading}
  format="webp"
  quality={80}
/>

Next Steps

Ready to implement advanced features?