Contributing to Kubestellar Docs

Thank you for your interest in contributing to our documentation repository! We welcome contributions from everyone. Please follow these guidelines to help maintain a high-quality, consistent, and collaborative project.

Prerequisites

Before contributing, ensure you have:

Node.js (version 18 or higher) installed
npm installed
A GitHub account
Basic knowledge of Markdown and Git

How to Contribute

1. Fork the Repository

Click the Fork button at the top-right corner of this page to create your own copy of the repository.

2. Clone Your Fork

Clone the repository to your local machine:

git clone https://github.com/your-username/docs.git

3. Install Dependencies

Navigate into the project directory and install dependencies:

cd docs
npm install

4. Create a Branch

Create a new branch for your work:

git checkout -b my-feature-branch

5. Make Your Changes

Edit or create documentation files as needed.
Please follow the existing structure, tone, and formatting style.

6. Preview / Test Your Changes

Start the development environment to verify rendering:

npm run dev

Tip: During active documentation contributions, regularly run npm run dev to preview updates in real time.

7. Commit and Push

Commit your changes with a clear and meaningful message:

git add .
git commit -m "Describe your changes"
git push origin my-feature-branch

8. Open a Pull Request

Open a Pull Request (PR) from your branch to the main repository.

PR Description

Provide a summary of what you changed (maximum 2 lines).
Reference related issues, e.g.:
```
Fixes #123
```

8. Open a Pull Request

Open a Pull Request (PR) from your branch to the main repository.

PR Description

Provide a summary of what you changed (maximum 2 lines).
Reference related issues, e.g.:
```
Fixes #123
```

Contribution Guidelines

Write Clearly: Use concise language and proper formatting.
Stay Consistent: Maintain the existing structure and style.
Respect Internationalization Standards: Avoid pushing raw UI strings directly; always use i18n references.
Be Respectful: Review our Code of Conduct before contributing.

Caution With AI-Generated Code

AI tools (like GitHub Copilot or ChatGPT) are helpful but not always context-aware.
Please DO NOT blindly copy-paste AI-generated code.

Before committing:

Double-check if the code aligns with our project’s architecture.
Test thoroughly to ensure it doesn’t break existing functionality.
Refactor and adapt it as per the codebase standards.

Contribution Guidelines

Write Clearly: Use concise language and proper formatting.
Stay Consistent: Maintain the existing structure and style.
Respect Internationalization Standards: Avoid pushing raw UI strings directly; always use i18n references.
Be Respectful: Review our Code of Conduct before contributing.

Caution With AI-Generated Code

AI tools (like GitHub Copilot or ChatGPT) are helpful but not always context-aware.
Please DO NOT blindly copy-paste AI-generated code.

Before committing:

Double-check if the code aligns with our project’s architecture.
Test thoroughly to ensure it doesn’t break existing functionality.
Refactor and adapt it as per the codebase standards.

CI Workflow Notes

OSSF Scorecard

The OSSF Scorecard workflow requires permissions to be defined at the job level. Workflow-level permissions are not supported and may cause CI failures due to OSSF Scorecard web application requirements.

Image Scanning

The image scanning workflow supports repositories with multiple Dockerfiles using a matrix strategy. Dockerfile paths must be correctly configured to ensure all container images are scanned successfully.

Contribution Commands Guide

This guide helps contributors manage issue assignments and request helpful labels via GitHub comments. These commands are supported through GitHub Actions or bots configured in the repository.

Issue Assignment

To assign yourself to an issue, comment:
```
/assign
```
To remove yourself from an issue, comment:
```
/unassign
```

Label Requests via Comments

You can also request labels to be automatically added to issues using the following commands:

To request the help wanted label, comment:
```
/help-wanted
```
To request the good first issue label, comment:
```
/good-first-issue
```

These commands help maintainers manage community contributions effectively and allow newcomers to find suitable issues to work on.

Understanding the Documentation Architecture

Overview

This documentation website is a separate repository from the main KubeStellar codebase. Here’s the key architecture:

┌─────────────────────────────────────────────────────────────┐
│  Main KubeStellar Repository                                 │
│  github.com/kubestellar/kubestellar                          │
│                                                               │
│  📁 docs/content/                                            │
│     ├── readme.md                                            │
│     ├── architecture.md                                      │
│     ├── direct/                                              │
│     │   ├── binding.md                                       │
│     │   └── wds.md                                           │
│     └── ... (all documentation content)                      │
└─────────────────────────────────────────────────────────────┘
                          ↓
                    (Fetched via GitHub API)
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Docs Website Repository (THIS REPO)                         │
│  github.com/kubestellar/docs                                 │
│                                                               │
│  📁 src/app/docs/                                            │
│     ├── page-map.ts     ← Defines navigation structure      │
│     ├── layout.tsx       ← Nextra theme integration         │
│     └── [...slug]/page.tsx  ← Renders fetched content       │
│                                                               │
│  📁 next.config.ts      ← Nextra configuration              │
│  📁 mdx-components.js   ← MDX component mappings            │
└─────────────────────────────────────────────────────────────┘
                          ↓
                    (Built & Deployed)
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Live Documentation Website                                  │
│  https://kubestellar.io                                      │
└─────────────────────────────────────────────────────────────┘

Important Concepts:

✅ Content lives in the main KubeStellar repo (docs/content/)
✅ This repo contains the website framework (Next.js + Nextra)
✅ Content is fetched dynamically via GitHub API at build time
✅ Navigation is defined in page-map.ts (not auto-generated from files)

How Nextra Integration Works

This documentation site is built using Nextra, a powerful Next.js-based documentation framework that provides:

Static Site Generation (SSG) for fast loading
MDX Support for rich, interactive documentation
Built-in Search functionality
Theme Customization with dark/light modes
Automatic Navigation generation

Key Files and Their Roles

next.config.ts - Main configuration file that:
- Imports and configures Nextra with nextra() function
- Enables LaTeX support for mathematical expressions
- Configures search settings
- Integrates with next-intl for internationalization
- Sets up redirects for various KubeStellar links
src/app/docs/layout.tsx - Docs layout component that:
- Imports Layout from nextra-theme-docs
- Imports the Nextra theme styles
- Configures custom navbar, footer, and banner components
- Sets up the sidebar with page map and repository links
- Enables dark mode and collapsible sidebar sections
src/app/docs/page-map.ts - Navigation structure builder that:
- Defines the documentation navigation structure in NAV_STRUCTURE
- Reads documentation files from the local /docs/content/ directory
- Constructs hierarchical navigation from the defined structure
- Generates routes for each documentation page
- Creates a mapping between file paths and URL routes
src/app/docs/[...slug]/page.tsx - Dynamic page renderer that:
- Reads MDX content from the local /docs/content/ directory
- Compiles and evaluates MDX with custom components
- Processes Jekyll-style includes and template variables
- Supports Mermaid diagrams and custom components
- Handles image path resolution and markdown transformations
mdx-components.js - Component mapping file that:
- Exports MDX components from Nextra theme
- Allows customization of how markdown elements render
- Enables adding custom React components to MDX files

How to Add Documentation

The documentation content is stored directly in this repository in the /docs/content/ directory.

Content Location

All documentation content lives in this repository:

Repository: https://github.com/kubestellar/docs
Content Path: /docs/content/
Format: Markdown (.md) files with support for MDX features

The navigation is defined in src/app/docs/page-map.ts in the NAV_STRUCTURE constant. This defines how documentation pages are organized and displayed in the sidebar.

Adding New Content

To add new documentation pages:

Create Your Documentation File:
- Add your .md file to the appropriate subdirectory in /docs/content/
- Use standard Markdown syntax
- You can use Jekyll-style includes: {% include "path/to/file.md" %}
- You can use template variables: “
Update the Navigation:
- Edit src/app/docs/page-map.ts
- Find the appropriate section in NAV_STRUCTURE
- Add an entry for your new file:
```
{ 'Page Title': 'path/to/your-file.md' }
```
- The file path is relative to /docs/content/
Preview Your Changes:
```
npm run dev
```
Navigate to http://localhost:3000/docs/your-route to see your page

Example: Adding a New Getting Started Guide

// In src/app/docs/page-map.ts, within NAV_STRUCTURE
{
  title: 'User Guide',
  items: [
    { 'Quick Start': 'direct/get-started.md' },
    { 'Your New Guide': 'direct/new-guide.md' }, // Add this line
    // ... rest of the entries
  ]
}

Adding Nested Sections

For hierarchical navigation:

{
  'Parent Section': [
    { 'Subsection 1': 'path/to/file1.md' },
    { 'Subsection 2': 'path/to/file2.md' },
    {
      'Nested Section': [
        { 'Deep Page': 'path/to/deep/file.md' }
      ]
    }
  ]
}

‘Nested Section’: [ { ‘Deep File’: ‘path/to/nested/file.md’ ] } ] }


#### External Links

You can also add external documentation links:

```typescript
&#123; 'API Reference (new tab)': 'https://pkg.go.dev/github.com/kubestellar/kubestellar/api/control/v1alpha1' &#125;

Version Management

The documentation supports multiple versions through the versions.ts config:

Default Version: Set in getDefaultVersion()
Branch Mapping: Map versions to Git branches in getBranchForVersion()
Version Switching: Users can switch versions via query parameter: ?version=0.23.0

Testing Your Changes

Local Development:
```
npm run dev
```
- Test navigation and page rendering
- Verify new pages appear in the correct location
- Check that links work properly
Build Test:
```
npm run build
```
- Ensure no build errors
- Verify static generation works
- Check that all pages are accessible
Content Verification:
- Ensure the content file exists in the main KubeStellar repo
- Verify the file path in page-map.ts matches exactly
- Check that the category structure makes logical sense

Common Issues

Page Not Appearing:
- Verify file exists in main KubeStellar repo
- Check file path spelling and case sensitivity
- Ensure file has .md or .mdx extension
- Rebuild the page map
Navigation Issues:
- Check CATEGORY_MAPPINGS structure syntax
- Ensure proper nesting of arrays and objects
- Verify route generation logic
Content Not Updating:
- Clear Next.js cache: npm run clean
- Rebuild: npm run build
- Check GitHub API rate limits
- Verify GITHUB_TOKEN environment variable if needed

Working with MDX

MDX allows you to use React components in Markdown:

# My Documentation
 
<Callout type="info">This is an info callout!</Callout>
 
<Tabs items=&#123;["npm", "yarn", "pnpm"]&#125;>
  <Tabs.Tab>npm install kubestellar</Tabs.Tab>
  <Tabs.Tab>yarn add kubestellar</Tabs.Tab>
  <Tabs.Tab>pnpm add kubestellar</Tabs.Tab>
</Tabs>

Available components:

Callout - For notes, warnings, and tips
Tabs - For tabbed content
Mermaid - For diagrams (custom component)

Quick Reference: Common Workflows

Workflow 1: Adding a New Documentation Page

# Step 1: Add content to main KubeStellar repo
cd /path/to/kubestellar
echo "# My New Page" > docs/content/my-new-page.md
git add docs/content/my-new-page.md
git commit -m "Add new documentation page"
git push
 
# Step 2: Update navigation in docs repo
cd /path/to/docs
# Edit src/app/docs/page-map.ts to add your page
# Add: &#123; file: 'my-new-page.md' &#125; in appropriate category
 
# Step 3: Test locally
npm run dev
# Visit http://localhost:3000/docs to verify
 
# Step 4: Commit and push
git add src/app/docs/page-map.ts
git commit -m "Add my-new-page to navigation"
git push

# Edit src/app/docs/page-map.ts
# Modify CATEGORY_MAPPINGS array
# Example: Move a page to different category
npm run dev  # Test changes
npm run build  # Verify build succeeds
git commit -am "Reorganize documentation navigation"

Workflow 3: Updating Nextra Configuration

# Edit next.config.ts for Nextra settings
# Example: Enable/disable features
npm run dev  # Test configuration
npm run build  # Verify no errors
git commit -am "Update Nextra configuration"

Workflow 4: Adding Custom MDX Components

# Step 1: Create your component
echo 'export function MyComponent() &#123; return <div>Hello</div> &#125;' > src/components/MyComponent.tsx
 
# Step 2: Export from mdx-components.js
# Add: import &#123; MyComponent &#125; from './src/components/MyComponent'
# Add to export: MyComponent
 
# Step 3: Use in documentation (main repo)
# In any .mdx file: <MyComponent />
 
npm run dev  # Test component

Environment Variables

For development and production, you may need these environment variables:

# .env.local (optional)
GITHUB_TOKEN=ghp_your_token_here  # For higher GitHub API rate limits
GH_TOKEN=ghp_your_token_here      # Alternative name
GITHUB_PAT=ghp_your_token_here    # Alternative name

When is GITHUB_TOKEN needed?

When fetching content frequently during development
To avoid GitHub API rate limiting (60 requests/hour without token, 5000 with token)
Not required for basic local development

Key Files Summary

File	Purpose	When to Edit
`src/app/docs/page-map.ts`	Navigation structure	Adding/removing/reorganizing pages
`next.config.ts`	Nextra & Next.js config	Changing Nextra settings, redirects
`src/app/docs/layout.tsx`	Docs page layout	Modifying sidebar, theme, or layout
`mdx-components.js`	MDX component mappings	Adding custom React components to MDX
`src/config/versions.ts`	Version management	Adding new documentation versions
`src/middleware.ts`	Route handling	Changing i18n behavior, route matching
`package.json`	Dependencies & scripts	Adding new packages or commands

Debugging Tips

Problem: Page not showing up

# Check if file exists in main repo
curl https://api.github.com/repos/kubestellar/kubestellar/contents/docs/content/your-file.md
 
# Verify page-map.ts entry
grep -r "your-file.md" src/app/docs/page-map.ts
 
# Clear Next.js cache
npm run clean
npm run dev

Problem: Build fails

# Check TypeScript errors
npm run type-check
 
# Check linting
npm run lint
 
# View detailed build output
npm run build 2>&1 | tee build.log

Problem: Styling issues

# Check Tailwind classes
npm run build
 
# Inspect global CSS
cat src/app/globals.css
 
# Check theme styles
cat node_modules/nextra-theme-docs/style.css

Contributing Checklist

Before submitting your PR, ensure:

Code follows existing style and conventions
All links work correctly
Navigation structure is logical
Local build succeeds (npm run build)
No TypeScript errors (npm run type-check)
No linting errors (npm run lint)
Changes are documented in PR description
Related issue is referenced (if applicable)
Screenshots included for UI changes (if applicable)

Need Help?

If you have questions, open an issue or ask in the community channels:

Slack: #kubestellar-dev
GitHub Issues: kubestellar/docs
Community Meetings: Check the community calendar

Additional Resources

Nextra Documentation: https://nextra.site
Next.js Documentation: https://nextjs.org/docs
MDX Documentation: https://mdxjs.com
Main KubeStellar Repo: https://github.com/kubestellar/kubestellar

Thank you for contributing to our documentation! 🚀

Contributing to Kubestellar Docs

Prerequisites

How to Contribute

1. Fork the Repository

2. Clone Your Fork

3. Install Dependencies

4. Create a Branch

5. Make Your Changes

6. Preview / Test Your Changes

7. Commit and Push

8. Open a Pull Request

PR Description

8. Open a Pull Request

PR Description

Contribution Guidelines

Caution With AI-Generated Code

Contribution Guidelines

Caution With AI-Generated Code

CI Workflow Notes

OSSF Scorecard

Image Scanning

Contribution Commands Guide

Issue Assignment

Label Requests via Comments

Understanding the Documentation Architecture

Overview

How Nextra Integration Works

Key Files and Their Roles

How to Add Documentation

Content Location

Navigation Structure

Adding New Content

Example: Adding a New Getting Started Guide

Adding Nested Sections

Version Management

Testing Your Changes

Common Issues

Working with MDX

Quick Reference: Common Workflows

Workflow 1: Adding a New Documentation Page

Workflow 2: Reorganizing Navigation

Workflow 3: Updating Nextra Configuration

Workflow 4: Adding Custom MDX Components

Environment Variables

Key Files Summary

Debugging Tips

Contributing Checklist

Need Help?

Additional Resources