Project Documentation

Hisnulmuslim Astro Starlight Docs

🧞 Commands

All commands are run from the root of the project, from a terminal:

Command	Action
pnpm install	Installs dependencies
pnpm run dev	Starts local dev server at localhost:4321
pnpm run build	Build your production site to ./dist/
pnpm run preview	Preview your build locally, before deploying
pnpm run astro ...	Run CLI commands like astro add, astro check
pnpm run astro --help	Get help using the Astro CLI

📁 Custom Sidebar Formatting

This project includes custom formatting for sidebar directory labels. The following changes were implemented:

1. Custom Formatter Utility (src/components/sidebar/formatSidebarLabels.js)

• Created a utility function to transform hyphenated directory names into Title Case with spaces
• Added recursive processing for the entire sidebar structure
• Targets only directories (type: "group") while preserving page entries

2. Custom Sidebar Component (src/components/sidebar/CustomSidebar.astro)

• Implements a custom sidebar component that enhances Starlight’s core functionality
• Applies formatting logic to transform directory labels at render time
• Preserves all original sidebar functionality while adding label formatting

3. Astro Configuration Update (astro.config.mjs)

• Uses Starlight’s component override system to replace the default sidebar:

  components: {
    Sidebar: './src/components/sidebar/CustomSidebar.astro',
  },

This implementation transforms directory names like “blessings-rewards” to “Blessings Rewards” in the sidebar, making navigation more reader-friendly while maintaining the original file structure.

🔄 How to Update the Sidebar

To update the sidebar structure in this project:

1. Edit the sidebar configuration file:

   • Open src/config/sidebar.js
   • Modify the sidebar array to add, remove, or reorganize sections
   • Example:

     export const sidebar = [
       {
         label: 'New Section',
         translations: {},
         autogenerate: {
           directory: 'new-section',
         },
       },
       // Other sections...
     ];

2. The configuration flow:

   • sidebar.js exports the sidebar structure
   • astro.config.mjs imports this structure with: import sidebar from './src/config/sidebar.js'
   • The sidebar structure is passed to Starlight configuration
   • Our custom CustomSidebar.astro component formats the directory labels at render time

3. No additional steps needed:

   • The Title Case formatting with spaces is automatically applied to all directories
   • There’s no need to manually format directory labels in the sidebar configuration
   • Just restart the development server after making changes to see them reflected

Note: When adding new sections, ensure the corresponding directories exist in your project structure under src/content/docs/.

🧩 Custom Components

Aside Component (src/components/Aside.astro)

The project includes a custom Aside component used throughout the documentation for highlighting content in stylized boxes:

• Purpose: Creates callout boxes for quotes, references, notes, and special content

• Usage in MDX:

  <Aside type="quran" title="Surah Al-Fatiha">
    بِسْمِ اللَّهِ الرَّحْمَٰنِ الرَّحِيمِ
  </Aside>
  
  <Aside type="reference" title="Source">
    Sahih Bukhari, Book 1, Hadith 1
  </Aside>

• Available Types:

  • quran: For Quranic verses
  • hadith: For hadith content
  • reference: For source references
  • note: For general notes
  • tip: For useful tips
  • caution: For warnings
  • danger: For critical warnings

• Properties:

  • type: The style of the aside (required)
  • title: Optional heading/title for the aside
  • icon: Optional custom icon (defaults based on type)

Asides Styling (src/styles/asides.css)

This stylesheet provides custom styling for the Aside component:

• Features:

  • Custom colors for different aside types
  • Responsive design for different screen sizes
  • RTL (right-to-left) support for Arabic content
  • Styled icons for each aside type

• Import in MDX: All MDX files requiring the Aside component should include:

  import Aside from '~/components/Aside.astro';
  import '~/styles/asides.css';

• Note: The batch script update-mdx-imports.ps1 can be used to automatically add these imports to all MDX files in the hisnulmuslim directory.

🎨 Theme Customization

Starlight provides a default blue theme, but you can customize it to match your brand or personal preferences.

Default Theme Colors

The default theme colors are defined in:

packages/starlight/style/props.css

Key accent color variables (blue theme by default):

/* Dark mode accent colors */
--sl-color-accent-low: hsl(224, 54%, 20%);
--sl-color-accent: hsl(224, 100%, 60%);
--sl-color-accent-high: hsl(224, 100%, 85%);

/* Light mode accent colors */
--sl-color-accent-high: hsl(234, 80%, 30%);
--sl-color-accent: hsl(234, 90%, 60%);
--sl-color-accent-low: hsl(234, 88%, 90%);

The hue value (224/234) is what determines the color family (blue = ~234, purple = ~270, green = ~120, etc.).

How to Customize Theme Colors

There are three ways to customize Starlight’s theme colors:

1. Using CSS File (Recommended)

Create or modify a CSS file (e.g., src/styles/custom-theme.css):

src/styles/custom-theme.css

:root {
  /* Dark mode - change 234 to your preferred hue */
  --sl-hue: 270; /* Purple theme example */
  --sl-color-accent-low: hsl(var(--sl-hue), 54%, 20%);
  --sl-color-accent: hsl(var(--sl-hue), 100%, 60%);
  --sl-color-accent-high: hsl(var(--sl-hue), 100%, 85%);
}

:root[data-theme='light'] {
  /* Light mode - change 234 to your preferred hue */
  --sl-color-accent-high: hsl(var(--sl-hue), 80%, 30%);
  --sl-color-accent: hsl(var(--sl-hue), 90%, 60%);
  --sl-color-accent-low: hsl(var(--sl-hue), 88%, 90%);
}

Then add this file to your Starlight configuration in astro.config.mjs:

starlight({
  // Other config options...
  customCss: ['./src/styles/custom-theme.css'],
})

2. Using the Theme Designer

Starlight includes a built-in theme designer that you can access at:

/style-guide/theme-designer/

Steps to use it:

1. Run your development server (pnpm run dev)
2. Navigate to /style-guide/theme-designer/
3. Choose colors visually using the interface
4. Copy the generated CSS code
5. Paste it into a custom CSS file and include that file in your Starlight configuration as shown above

3. Using Component Overrides (Advanced)

For more advanced customization, you can override Starlight’s ThemeProvider component:

1. Create a custom theme provider component in your project
2. Override the default component in your Starlight configuration:

starlight({
  // Other config options...
  components: {
    ThemeProvider: './src/components/CustomThemeProvider.astro',
  }
})

Important Notes

• If your global.css or other custom CSS files redefine the --sl-color-accent-* variables, they will override Starlight’s defaults
• Using HSL colors makes it easier to maintain a consistent color scheme across light and dark modes
• For consistency, apply the same hue value across all accent variables
• The Starlight theme system styles interactive elements like buttons and links automatically based on your accent colors