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 title attribute:

```typescript filename="MyFile.ts"const example = "Hello, World!"; ```

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:

```typescript filename="example.ts" animateimport { OlapTable } from "@514labs/moose-lib"; const table = new OlapTable<MyModel>("my_table"); ```

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:

```typescript filename="example.ts"const example = "Static code block with filename"; ``` ```typescriptconst example = "Static code block without filename"; ```

Terminal Commands

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

Static terminal snippet (default):

```bashnpm install @514labs/moose-lib ```

Static terminal with filename:

```bash filename="Terminal"# This command sets up the projectnpm install @514labs/moose-lib ```

Animated terminal (opt-in with animate):

```bash filename="Terminal" animatemoose init my-projectcd my-projectmoose dev ```

Config Files

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

```toml filename="moose.config.toml"[features]olap = truestreaming = true ```

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:

import { OlapTable } from "@514labs/moose-lib"; const table = new OlapTable<MyModel>("my_table");

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:

export const myTable = new OlapTable("my_table");

Components Reference

Callout

Display important information, warnings, or tips:

<Callout type="info" title="Custom Title">  This is an informational callout with a custom title.</Callout> <Callout type="warning">  This warning uses the default title "Warning:".</Callout> <Callout type="success">  Success message with party popper icon!</Callout>

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:

<Callout   type="info"   title="Review the full guide"   href="/moosestack/getting-started/from-clickhouse"   ctaLabel="Get started"   compact={true}>  Review the full guide to learn more about how to bootstrap a new Moose OLAP project.</Callout>

CTACard and CTACards

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

<CTACards columns={2}>  <CTACard    title="OLAP Tables"    description="Define and create ClickHouse tables with type-safe schemas"    ctaLink="/moosestack/olap/model-table"    ctaLabel="Learn More →"    badge={{ variant: "moose", text: "Tables" }}  />  <CTACard    title="Materialized Views"    description="Pre-compute and store query results for faster analytics"    ctaLink="/moosestack/olap/model-materialized-view"    ctaLabel="Learn More →"    badge={{ variant: "moose", text: "Materialized Views" }}  /></CTACards>

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:

<CTACards columns={1}>  <CTACard    title="Read Data"    description="Write type-safe SQL queries with automatic interpolation"    ctaLink="/moosestack/olap/read-data"    ctaLabel="Learn More →"    orientation="horizontal"    Icon="Database"  /></CTACards>

StaggeredCard

Create alternating left-right layouts for showcasing features:

<StaggeredCards>  <StaggeredCard>    <StaggeredContent      title="Data Modeling"      description="Model all of your infrastructure in native TypeScript or Python."      cta={{        label: "Learn more",        href: "/moosestack/data-modeling",        variant: "outline",      }}    />    <StaggeredCode>      <CodeEditorWrapper        language="ts"        filename="models.ts"        variant="ide"      >{`interface Event {  id: Key<string>;  name: string;}`}      </CodeEditorWrapper>    </StaggeredCode>  </StaggeredCard></StaggeredCards>

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:

import { IconBadge } from "@/components/mdx/icon-badge"; <div className="flex items-center gap-4 my-8 flex-wrap">  <IconBadge Icon="Rocket" label="5 minute setup" variant="moose" />  <IconBadge Icon="Database" label="Pre-integrated ClickHouse" variant="moose" /></div>

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:

<CodeEditorWrapper  language="ts"  filename="example.ts"  variant="ide"  writing={true}  duration={5}  delay={0.5}>{`const example = "Hello, World!";`}</CodeEditorWrapper>

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, 0.3 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

content/  moosestack/    getting-started/      quickstart.mdx       # H1: Quickstart    olap/      index.mdx            # H1: Moose OLAP      model-table.mdx      # H1: Model a Table

Complete Example

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

Frontmatter:

---title: Example Pagedescription: An example documentation pageorder: 1---

Imports:

import { Callout, CTACards, CTACard, LanguageTabs, LanguageTabContent } from "@/components/mdx";

Page Content:

import { OlapTable, Key } from "@514labs/moose-lib"; interface MyTable {  id: Key<string>;  name: string;} export const myTable = new OlapTable<MyTable>("my_table");

Reference cards:

Questions?

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