MyST Awesome Theme Documentation

A comprehensive guide to using the MyST Awesome Theme with Web Awesome components and Astro.

Overview

The MyST Awesome Theme is a modern, responsive documentation theme built with Astro and Web Awesome components. It provides a clean, professional interface for technical documentation with excellent typography, accessibility, and user experience.

Note: This theme is designed to work seamlessly with MyST Markdown and provides enhanced features for technical documentation.

Features

The theme includes a comprehensive set of features designed for modern documentation:

  • Responsive Design: Works perfectly on desktop, tablet, and mobile devices
  • Dark Mode Support: Automatic and manual theme switching
  • Multiple Themes: Choose from various Web Awesome themes
  • Accessible: WCAG 2.1 AA compliant with keyboard navigation
  • Fast Performance: Optimized for speed with Astro's static generation
  • Search Integration: Built-in search functionality

Layout System

The theme uses a flexible layout system inspired by Web Awesome's page component, providing multiple slots for content organization:

Header & Navigation

Customizable header with branding, navigation, and theme controls.
Sidebar Navigation

Collapsible navigation menu with search and hierarchical organization.
Content Area

Main content area optimized for readability and technical documentation.
Table of Contents

Automatic table of contents generation with active section highlighting.

Theme Support

The theme leverages Web Awesome's comprehensive theming system, allowing you to choose from multiple pre-built themes or create your own custom theme:

Default Awesome Shoelace Custom

The default theme provides a clean, professional appearance suitable for most documentation needs.

The awesome theme features vibrant colors and modern styling for a more dynamic look.

The shoelace theme offers a familiar interface inspired by the Shoelace design system.

Create your own custom theme by overriding CSS custom properties and Web Awesome design tokens.

Getting Started

Follow these steps to set up the MyST Awesome Theme in your project:

Installation

Install the theme and its dependencies using your preferred package manager:

npm install myst-awesome @awesome.me/webawesome
Requirements: This theme requires Astro 4.0+ and Node.js 18+.

Basic Usage

Import and use the layout components in your Astro pages:

---
import DocsLayout from 'myst-awesome/layouts/DocsLayout.astro';
---

<DocsLayout title="My Documentation">
  <h1>Welcome to my docs!</h1>
  <p>This is the main content area.</p>
</DocsLayout>

Examples

Here are some examples of the theme components in action:

Alert Components

Success: Your changes have been saved successfully. Warning: This action cannot be undone. Error: Failed to process your request.

Interactive Elements

Primary Action Secondary Outlined Plain

Form Elements

General Technical Feedback