Using Pages CMS

This guide explains how to edit SOP documentation using Pages CMS and all available Starlight components.

Accessing Pages CMS

1. Go to https://app.pagescms.org
2. Sign in with your GitHub account
3. Navigate to elliotmegdal/EMA_SOP
4. Select the file you want to edit

Auto-Save

Pages CMS automatically saves your changes and commits them to GitHub. Your edits go live when the site rebuilds.

Editing MDX Files

In Pages CMS, documentation files appear with Content as a code editor. You’ll edit MDX (Markdown with components) directly with syntax highlighting.

Basic Markdown

Code	Preview
# Heading 1	Heading 1
## Heading 2	Heading 2
### Heading 3	Heading 3
**Bold text**	Bold text
_Italic text_	Italic text
~~Strikethrough~~	Strikethrough
[Link text](/path/to/page/)	Link text
- Bullet item	Bullet item
1. Numbered item	Numbered item

Adding Images

Code	Notes
	Images go in img/ and use relative paths /img/

Adding Tables

Tables use pipes (|) and hyphens (-) to create rows and columns.

Code	Notes
| Header 1 | Header 2 |	First row defines column headers
|------|------|	Second row separates header from content (required)
| Cell 1 | Cell 2 |	Data rows follow the same pipe structure

Alignment Options

Syntax	Result
|:------|	Left-aligned (default)
|------:|	Right-aligned
|:------:|	Centered

Example Table

| Task | Owner | Status |
|:-----|:-----:|-------:|
| Review invoices | Jane | Complete |
| Update records | Mike | Pending |

Renders as:

Task	Owner	Status
Review invoices	Jane	Complete
Update records	Mike	Pending

Tip

Keep tables simple. For complex data, consider using Cards or structured lists instead.

Starlight Components

Components make documentation interactive and visually clear. All components must be imported at the top of your MDX file.

Aside (Callouts)

Use asides for supplementary information. Four types available with customizable icons.

Code

import { Aside } from '@astrojs/starlight/components';

<Aside>
Default note aside with information.
</Aside>

<Aside type="tip" title="Pro Tip">
Helpful tips and best practices go here.
</Aside>

<Aside type="caution" title="Watch Out">
Warnings about potential issues.
</Aside>

<Aside type="danger" title="Critical">
Serious warnings or breaking changes.
</Aside>

Custom Icons

Override the default icon using any Starlight icon:

:::note{icon="rocket"}
Custom icon aside using Markdown syntax.
:::

Or with the component:

<Aside type="tip" title="Did you know?" icon="star">
Custom icon in component form.
</Aside>

Properties:

• type: note (default), tip, caution, danger
• title: Custom title text (optional)
• icon: Custom icon name from Starlight icons (optional)

Preview

Note

Default note aside with information.

Pro Tip

Helpful tips and best practices go here.

Watch Out

Warnings about potential issues.

Critical

Serious warnings or breaking changes.

Steps

Perfect for numbered procedures and workflows.

Code

import { Steps } from '@astrojs/starlight/components';

<Steps>
1. Open the application
2. Click the **Settings** button
3. Choose **Save**
</Steps>

Tip

Use Markdown formatting inside steps for emphasis, links, and code.

Preview

1. Open the application
2. Click the Settings button
3. Choose Save

Tabs

Organize alternative content or show platform-specific instructions.

Code

import { Tabs, TabItem } from '@astrojs/starlight/components';

<Tabs>
<TabItem label="Windows">
Instructions for Windows users.
</TabItem>

<TabItem label="macOS">
Instructions for Mac users.
</TabItem>

<TabItem label="Linux">
Instructions for Linux users.
</TabItem>
</Tabs>

Properties:

• syncKey: Synchronize multiple tab groups (optional)

TabItem Properties:

• label: Tab title (required)
• icon: Add icon before label (optional)

Preview

Windows

Instructions for Windows users.

macOS

Instructions for Mac users.

Linux

Instructions for Linux users.

Card

Display highlighted content in visually distinct boxes.

Code

import { Card } from '@astrojs/starlight/components';

<Card title="Feature Name" icon="star">
Description of the feature or important information.
</Card>

Properties:

• title: Card heading (required)
• icon: Icon name from Starlight icons (optional)

Preview

Feature Name

Description of the feature or important information.

CardGrid

Display multiple cards side-by-side.

Code

import { Card, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <Card title="First Feature" icon="pencil">
    Content for first card.
  </Card>

  <Card title="Second Feature" icon="rocket">
    Content for second card.
  </Card>

  <Card title="Third Feature" icon="star">
    Content for third card.
  </Card>
</CardGrid>

Properties:

• stagger: Offset second column vertically (optional)

Preview

First Feature

Content for first card.

Second Feature

Content for second card.

Third Feature

Content for third card.

LinkCard

Cards that link to other pages.

Code

import { LinkCard, CardGrid } from '@astrojs/starlight/components';

<CardGrid>
  <LinkCard
    title="Naming Convention"
    description="File naming standards for the organization"
    href="/introduction/naming-convention/"
  />

  <LinkCard
    title="Server Directory"
    description="Understanding the server folder structure"
    href="/guides/server-directory/"
  />
</CardGrid>

Properties:

• title: Card title (required)
• description: Brief description (optional)
• href: Link destination (required)

Preview

Naming Convention File naming standards for the organization

Server Directory Understanding the server folder structure

Badge

Small inline labels for tagging or highlighting content.

Standard Variants

Code	Preview	Usage
<Badge text="New" variant="tip" />	New	New features or positive highlights
<Badge text="Warning" variant="caution" />	Warning	Warnings or things to watch
<Badge text="Required" variant="danger" />	Required	Critical requirements or errors
<Badge text="Updated" variant="success" />	Updated	Completed or successful states
<Badge text="Default" />	Default	Default gray appearance

Size Options

Code	Preview
<Badge text="Small" size="small" />	Small
<Badge text="Medium" size="medium" />	Medium
<Badge text="Large" size="large" />	Large

Custom Colors

Code	Preview
<Badge text="Purple" variant="note" style={{ backgroundColor: '#8b5cf6', color: 'white' }} />	Purple
<Badge text="Pink" variant="note" style={{ backgroundColor: '#ec4899', color: 'white' }} />	Pink
<Badge text="Teal" variant="note" style={{ backgroundColor: '#14b8a6', color: 'white' }} />	Teal
<Badge text="Orange" variant="note" style={{ backgroundColor: '#f97316', color: 'white' }} />	Orange

In Context

Code	Preview
This feature is <Badge text="Required" variant="danger" /> for all users.	This feature is Required for all users.
Status: <Badge text="Active" variant="success" /> | <Badge text="Beta" variant="caution" size="small" />	Status: Active | Beta

Properties:

• text: Badge label text (required)
• variant: Predefined color - note, tip, caution, danger, success (optional)
• size: Badge size - small, medium, large (optional)
• style: Custom CSS object for colors and styling (optional)

Badge Best Practices

• Keep text short (1-2 words)
• Use consistent variants for similar meanings
• Custom colors should have sufficient contrast
• Don’t overuse - badges lose impact when everywhere

LinkButton

Call-to-action buttons with links.

Button Variants

Code	Preview
<LinkButton href="/getting-started/">Get Started</LinkButton>	Get Started
<LinkButton href="/reference/configuration/" variant="secondary">Configuration</LinkButton>	Configuration
<LinkButton href="https://example.com" variant="minimal">Minimal Style</LinkButton>	Minimal Style

With Icons

Code	Preview
<LinkButton href="#" icon="rocket">Launch</LinkButton>	Launch
<LinkButton href="#" icon="external" iconPlacement="end">External Link</LinkButton>	External Link
<LinkButton href="#" variant="secondary" icon="setting">Settings</LinkButton>	Settings

Properties:

• href: Link destination (required)
• variant: Style - primary (default), secondary, minimal
• icon: Icon name from Starlight icons (optional)
• iconPlacement: start (default) or end

FileTree

Display file and folder structures.

Code

import { FileTree } from '@astrojs/starlight/components';

<FileTree>
- src/
  - content/
    - docs/
      - introduction/
        - naming-convention.mdx
        - sharing-files.mdx
      - index.mdx
  - styles/
    - custom.css
- astro.config.mjs
- package.json
</FileTree>

Formatting Rules:

• Use - for list items
• Add / after folder names
• Include file extensions
• Indent with spaces (2 spaces per level)

Preview

• Directorysrc/

  • Directorycontent/

    • Directorydocs/

      • Directoryintroduction/

        • naming-convention.mdx
        • sharing-files.mdx
      • index.mdx
  • Directorystyles/

    • custom.css
• astro.config.mjs
• package.json

Icon

Add visual indicators using Starlight’s icon library.

Basic Icons

Code	Preview	Usage
<Icon name="star" />		Favorites, highlights
<Icon name="rocket" />		Quick start, launch
<Icon name="pencil" />		Edit, write

Custom Sizes

Code	Preview
<Icon name="star" size="1rem" />
<Icon name="star" size="1.5rem" />
<Icon name="star" size="2rem" />
<Icon name="star" size="3rem" />

Custom Colors

Code	Preview
<Icon name="star" color="gold" />
<Icon name="rocket" color="var(--sl-color-text-accent)" />
<Icon name="warning" color="orange" />
<Icon name="error" color="red" />
<Icon name="setting" color="blue" />

In Context

Code	Preview
Click the <Icon name="setting" /> icon to open settings.	Click the icon to open settings.
<Icon name="rocket" /> Getting Started	Getting Started

Properties:

• name: Icon identifier from Starlight icons (required)
• size: CSS size value (optional, default: 1em)
• color: CSS color value (optional)
• label: Screen reader text (optional)

Browse all icons: Starlight Icon Reference

Code Blocks

Examples

```javascript
function example() {
  console.log("Hello world");
}
```
```bash
npm install package-name
```
```yaml
key: value
nested:
  item: data
```

Preview

function example() {
  console.log("Hello world");
}

npm install package-name

key: value
nested:
  item: data

Complex Example

Code

import { Steps, Aside, Tabs, TabItem, Card, CardGrid, Badge } from '@astrojs/starlight/components';

## Processing Workflow <Badge text="Updated" variant="tip" />

<Aside type="tip" title="Before You Start">
Review the prerequisites before beginning this process.
</Aside>

<Steps>
1. **Upload Files**

   Select your files for processing.

2. **Configure Settings**

   <Tabs>
   <TabItem label="Basic">
   Use default settings for standard processing.
   </TabItem>

   <TabItem label="Advanced">
   Customize advanced options for specific needs.
   </TabItem>
   </Tabs>

3. **Review Results**

   Check the output before finalizing.
</Steps>

<CardGrid>
  <Card title="Success Metrics" icon="star">
    Track completion rates and accuracy.
  </Card>

  <Card title="Error Handling" icon="warning">
    Review logs for any processing errors.
  </Card>
</CardGrid>

<Aside type="caution">
Always save your work before closing the application.
</Aside>

Preview

Before You Start

Review the prerequisites before beginning this process.

1. Upload Files

   Select your files for processing.

2. Configure Settings

   Choose your processing mode.

3. Review Results

   Check the output before finalizing.

Success Metrics

Track completion rates and accuracy.

Error Handling

Review logs for any processing errors.

Caution

Always save your work before closing the application.

Best Practices

Use Asides Sparingly

Reserve asides for truly important or supplementary information. Overuse diminishes their impact.

Break Up Long Content

Use Steps, Tabs, or Cards to organize complex information into digestible chunks.

Add Visual Hierarchy

Combine components to create clear visual flow - Steps for process, Cards for features, Asides for warnings.

Test Your Links

Always verify LinkCard and LinkButton destinations work correctly.

Troubleshooting

Component Issues

Import Statement Missing

Every component must be imported at the top:

import { ComponentName } from '@astrojs/starlight/components';

Closing Tags

All components need closing tags:

<Aside>Content here</Aside>

Self-Closing Components

Some components are self-closing:

<Badge text="Label" />
<Icon name="star" />

Saving Issues

Check Your Connection

Pages CMS requires an active GitHub connection. Verify you’re signed in and have repository access.

Common Solutions:

• Refresh the browser page
• Sign out and sign back in
• Check GitHub repository permissions
• Verify network connection

Image Issues

Image Path Problems

Images must use relative paths from the file location:

• Correct /img/screenshot.png
• Incorrect /img/screenshot.png

Image Not Displaying:

1. Verify file exists in img/
2. Check file name matches exactly (case-sensitive)
3. Ensure relative path is correct for file location
4. Rebuild site after adding new images

Quick Reference

Import Statement

import {
  Aside,
  Badge,
  Card,
  CardGrid,
  LinkCard,
  Steps,
  Tabs,
  TabItem,
  FileTree,
  Icon,
  LinkButton
} from '@astrojs/starlight/components';

Component Cheat Sheet

Component	Usage	Key Props
<Aside>	Callouts/admonitions	type, title, icon
<Badge>	Inline labels	text, variant, size
<Card>	Content boxes	title, icon
<LinkCard>	Linked cards	title, href, description
<Steps>	Numbered lists	None
<Tabs>	Tabbed content	syncKey
<TabItem>	Tab panels	label, icon
<FileTree>	File structures	None
<Icon>	Inline icons	name, size, color
<LinkButton>	CTA buttons	href, variant, icon

Additional Resources

Starlight Components Official Starlight component documentation

Starlight Icons Browse all available icons

Need Help?

Contact the data team if you have questions or need assistance editing documentation.