Contributing to Kubestellar

Thank you for your interest in contributing to KubeStellar’s code and/or documentation repositories! 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

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. All the active documentation is now located in this repository. For safety reasons, copies of the docs source may remain in a to-be-deleted folder in the component repositories during a transition period

CODE is in the component repositories
┌─────────────────────────────────────────────────────────────┐
│  Main KubeStellar Repository                                │
│  github.com/kubestellar/kubestellar                         │
│  🗄️kubestellar/                                             │
│   ├📁 docs/   ← NOT THE ACTIVE DOCS                         |
|     ├──README.md                                            |
|     └──content/to-be-deleted                                │
│           ├── readme.md                                     │
│           ├── architecture.md                               │
│           ├── direct/                                       │
│           ├── binding.md                                    │
│           ├── wds.md                                        │
│           └── ... (all previous documentation content)      │
│    └── ...(all the active components of the component repo) |
└─────────────────────────────────────────────────────────────┘

DOCUMENTATION/WEBSITE is in the docs repository                       
┌────────────────────────────────────────────────────────────────|
│  Docs Website Repository (THIS REPO)                           │
│  github.com/kubestellar/docs                                   |
|                                                                │  
│  🗄️docs/ ← this repository root folder                        │
|   ├ 📁 docs/ ← raw MD content source moved from repos         |
|   |   📁content/                                              |
|   |     📁 a2a/                                               |
|   |     📁 dommon-subs/                                       |
|   |     📁 Community/                                         |
|   |     📁 console/                                           |
|   |     📁 contribution-guidelines/                           |
|   |     📁 icons/                                             |
|   |     📁 images/                                            |
|   |     📁 klaude/                                            |
|   |     📁 kubeflex/                                          |
|   |     📁 kubestellar/                                       |
|   |     📁 multi-plugin/                                      |
|   |     📁 ui-docs/                                           |
|   |   📁images/ ← image folder for some of the MD files       |
|   |  📁overrides/ ← master mkdocs layouts (legacy ref only)   |
|   ├📁 messages      ← alternate language files for NEW pages  | 
|   ├📁 src/  ← Source for NEW pages, site nav and layout       |    
|   | ├📁 app/                                                  |
|   | |  ├📁 docs/  ← layouts to apply to component docs pages  |
|   | |  ├── 📄page-map.ts     ← Defines navigation structure   │
│   | |  ├── 📄layout.tsx      ← Nextra theme integration       │
|   | |  └── 📄page.mdx      ← Nextra page master               │
|   | ├📁 components/                                           │
|   | ├📁 config/                                               │
|   | ├📁 hooks/                                                │
|   | ├📁 i18n/ ← configures language support                   |
|   | ├📁 lib/                                                  │
|   ├📄CONTRIBUTING.md    <----- this file                      |
|   ├📄GOVERNANCE.md                                            |
|   ├📄 next.config.ts      ← Nextra configuration              │
|   ├📄 mdx-components.js   ← MDX component mappings            |
|   └── ... (various node.js and next.js etc files)              │
└────────────────────────────────────────────────────────────────┘
                          ↓
                    (Built & Deployed)
                          ↓
┌─────────────────────────────────────────────────────────────┐
│  Live Documentation Website                                  │
│  https://kubestellar.io                                      │
└─────────────────────────────────────────────────────────────┘

Important Concepts:

  • ✅ Content is contained in docs/content filetree (this does not generate the navigation)
  • ✅ 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

  1. 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

  2. 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

  3. 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
    • Note: The file tree structure in /docs/content roughly parallels the navigation created in pagemap.ts but is not identical. As the new site matures many of the differences will be smoothed out
    • Using the page-map rather than file structure to generate the NAV_STRUCTURE simplifies changing menus for different locales (languages)

  4. src/app/docs/[...slug]/page.tsx - Dynamic page renderer that:

    • Reads MDX and MD 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

  5. 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

Working Effectively on the KubeStellar Docs

How to Modify An Existing Page in the site

The Easy Way

For edits to a single page, we have enabled a suggest edits function in the site itself:

  1. Sign into Github in your browser.
  2. Open a second tab and visit the page in the website you wish to modify. (Make sure have selected the specific version of the docs with the dropdown in the masthead)
  3. Find and click on the Edit This Page (Pencil) icon near the upper right page
  4. A Github editor session will open for you and when you commit your changes, you will be presented with the option to create a corresponding PR.
  5. You may have to make some adjustments to the PR title, etc to fulfil some requirements for a PR.
  6. When your PR is created, it will automatically generate a site preview via Netlify to make reviewing the proposed changes easier

The Complicated Way

For less simple edits, for edits across multiple files, or for editing the docs site structure/navigation, you will have to go the more traditional GitHub route of:

  1. creating a fork of the docs repository
  2. configuring your editing system properly with node.js and Nextra
  3. editing the files
  4. committing changes to the branch be sure to both sign off (-s option) for DCO and sign (-S option) your commits
  5. pushing those changes up to your fork
  6. and then doing a standard Pull Request. The PR will create a website preview via Netlify for reviewers

Some of the most common tasks are detailed below.

Common Tasks for modifying the KubeStellar Site

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:

  1. 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: “

  2. 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/

  3. 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': 'kubestellar/get-started.md' },
    { 'Your New Guide': 'kubestellar/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

  1. Local Development:

    npm run dev
    • Test navigation and page rendering
    • Verify new pages appear in the correct location
    • Check that links work properly

  2. Build Test:

    npm run build
    • Ensure no build errors
    • Verify static generation works
    • Check that all pages are accessible

  3. 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

  1. 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

  2. Navigation Issues:

    • Check CATEGORY_MAPPINGS structure syntax
    • Ensure proper nesting of arrays and objects
    • Verify route generation logic

  3. 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

Workflow 2: Reorganizing Navigation

# 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

FilePurposeWhen to Edit
src/app/docs/page-map.tsNavigation structureAdding/removing/reorganizing pages
next.config.tsNextra & Next.js configChanging Nextra settings, redirects
src/app/docs/layout.tsxDocs page layoutModifying sidebar, theme, or layout
mdx-components.jsMDX component mappingsAdding custom React components to MDX
src/config/versions.tsVersion managementAdding new documentation versions
src/middleware.tsRoute handlingChanging i18n behavior, route matching
package.jsonDependencies & scriptsAdding 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:

Additional Resources

Thank you for contributing to our documentation! 🚀