Contributing to Documentation

Thank you for your interest in contributing to the MooseStack documentation! This guide will help you get started with writing clear, consistent documentation.

Getting Started

The documentation is built using MDX files located in the content/ directory. Each section corresponds to a folder structure that matches the navigation.

Making Changes

1. Find the relevant file - Navigate to the appropriate folder in content/
2. Edit the MDX file - Make your changes using standard Markdown and MDX syntax
3. Test locally - Run the documentation site locally to verify your changes
4. Submit a PR - Create a pull request with your improvements

Documentation Structure

• All content files are in the content/ directory
• Each MDX file has frontmatter with title, description, order, and category
• Code examples should support both TypeScript and Python when applicable using LanguageTabs

Code Snippets

Basic Code Block

To add a code block with a filename displayed, use the filename or attribute:

This will automatically:

• Display the filename at the top of the code block
• Show a copy button
• Render with syntax highlighting
• Remain static (no animation by default)

Animated Code Editor (opt-in)

To create an animated code editor that types out the code, add the animate attribute:

Rules for animated editors:

• ✅ Code blocks with animate attribute → Animated IDE/terminal
• ❌ Code blocks without animate → Always static (default)
• ❌ Config files (toml, yaml, json) → Always static (animation disabled)

Key attributes:

• filename="..." or title="..." → Static code block with filename display
• animate → Enables typing animation (opt-in)

Static Code Block (default)

All code blocks are static by default. Use filename or title to show a filename:

Terminal Commands

For terminal commands, simply use bash, sh, or shell as the language:

Static terminal snippet (default):

Static terminal with filename:

Animated terminal (opt-in with animate):

Config Files

Config files (TOML, YAML, JSON, etc.) always render as static code blocks, animation is disabled:

Config file languages: toml, yaml, yml, json, jsonc, ini, properties, config

Code Block Types Summary

Multi-Language Support

LanguageTabs Component

Use LanguageTabs to show code examples in multiple languages side-by-side:

Important:

• The value prop must match the lowercase language name (typescript or python)
• LanguageTabs typically use simple code blocks without title or filename attributes - they render as static, copyable code blocks
• Use title or filename attributes only when you need to show a filename or create animations in standalone code blocks (not within LanguageTabs)

Language-Specific Notes

When documenting language-specific features, use Callout components within language tabs:

Components Reference

Callout

Display important information, warnings, or tips:

Props:

• type: "info" | "warning" | "danger" | "success" (required)
• title: Custom title text (optional, uses default if not provided)
• href: Link URL (optional)
• ctaLabel: Button label text (default: "Learn more")
• compact: Use compact layout (default: false)
• icon: Icon component or true/false to show/hide (default: true)

Example with link:

CTACard and CTACards

Create call-to-action cards for linking to related documentation:

CTACard Props:

• title: Card title (required)
• description: Card description (required)
• ctaLink: Link URL (required)
• ctaLabel: Button text (default: "Learn more")
• Icon: Lucide icon name (string) or icon component (optional)
• badge: Badge object with variant and text (optional)
• variant: "default" | "gradient" | "sloan" (default: "default")
• orientation: "vertical" | "horizontal" (default: "vertical")
• isMooseModule: Prefix title with "Moose " (default: false)

CTACards Props:

• columns: Number of columns (1-4, default: 2)
• rows: Number of rows (default: 1)

Horizontal CTACard:

StaggeredCard

Create alternating left-right layouts for showcasing features:

StaggeredCard Props:

• stagger: "left" | "right" - Controls which side content appears on (default: "left")
• className: Additional CSS classes

StaggeredContent Props:

• isMooseModule: Prefix title with "Moose " (default: false)
• title: Section title (required)
• description: Section description (required)
• cta: Call-to-action object with label, href, and variant (optional)

StaggeredCode Props:

• children: Code component (typically CodeEditorWrapper)
• language: Language for syntax highlighting (default: "ts")

IconBadge

Small badges for highlighting features or technologies:

Props:

• Icon: Lucide icon name (string) or icon component (optional)
• label: Badge text (required)
• variant: "moose" | "boreal" | "sloan" | "default" (default: "moose")
• rounded: "md" | "full" (default: "md")

CodeEditorWrapper

For advanced use cases, you can use CodeEditorWrapper directly to create animated code editors:

Props:

• code: Code as string (alternatively, use children)
• children: Code content (alternative to code prop)
• language: Programming language (required)
• filename: Display filename (optional)
• variant: "ide" | "terminal" (default: "ide")
• writing: Enable typing animation (default: true)
• duration: Animation duration in seconds (default: 5 for IDE, 3 for terminal)
• delay: Initial delay in seconds (default: 0.5 for IDE, for terminal)

Note: In most cases, you don't need to use CodeEditorWrapper directly. Use code blocks with filename and animate attributes instead.

Style Guidelines

Writing Style

• Use clear, concise language
• Write in second person ("you") when giving instructions
• Use active voice when possible
• Keep sentences short and focused

Code Examples

• Always include working code examples
• Show both TypeScript and Python when applicable
• Include necessary imports
• Use descriptive variable names
• Add comments to explain complex logic

Formatting

• Use consistent heading levels (H1 for page title, H2 for main sections, H3 for subsections)
• Include code examples where helpful
• Link to related documentation using CTACard components
• Use Callout components for important notes, warnings, or tips
• Keep formatting consistent with existing pages

Code Block Best Practices

1. Use filename to show a filename in code blocks
2. Use animate for demonstrations when you want the code to type out (opt-in)
3. Always include filenames when showing file contents
4. Use appropriate language tags (ts, py, bash, toml, etc.)
5. Use LanguageTabs for multi-language examples
6. Keep code examples focused - show only what's necessary
7. Add context with callouts when code needs explanation

File Structure Best Practices

Complete Example

Here's a complete example combining multiple components. This shows the structure of a typical documentation page:

Frontmatter:

Imports:

Page Content:

Reference cards:

Questions?

If you have questions about contributing, please open an issue or reach out to the maintainers.