Kubestellar Website Overview

Websites

We have two web sites:

kubestellar.io - Hosted by GoDaddy and administered by Andy Anderson. The main redirect goes from kubestellar.io to docs.kubestellar.io.
docs.kubestellar.io - A GitHub Pages website based on the kubestellar/kubestellar repository.

Contributors can have their own copy of the documentation website at https://{repo_owner}.github.io/{fork_name} if they set up their fork properly. This is useful for previewing changes before merging. PRs that modify the website should include a preview link.

Dual-use Documentation Sources

The documentation is designed to be viewed both on the website and directly on GitHub. When the two interpret sources differently, website rendering takes precedence.

Style Guide

We have a Style Guide to ensure consistent documentation style and voice.

GitHub Pages

Our documentation uses mike and MkDocs . Key configurations include:

Theme: Material for MkDocs
Plugin: awesome-pages for navigation control
Plugin: macros
Plugin: include-markdown for reusable content
Extension: SuperFences for fenced code blocks
Extension: Highlight for syntax highlighting
Pygments for code highlighting
Plugin: mkdocs-static-i18n for multi-language support

Note on include-markdown Wrapper Files

Pages generated by including root repository files should use -inc or -include in their filename to prevent editing the wrong file.

Rendering and Previewing Website Modifications

Preview changes either locally or via GitHub Pages from your fork (recommended for PRs).

Serving Documents from a Fork via GitHub

Use the “Generate and Push Docs” GitHub Actions workflow to create shareable website renderings. Requirements:

Branch names should contain alphanumerics, dashes, and dots
Your fork needs a gh-pages branch
GitHub must be configured to publish from that branch

The branch name becomes the website “version” name.

Automatically Render the Website

Branches starting with doc- automatically trigger the rendering workflow. For example, branch doc-holliday creates version doc-holliday on your fork’s GitHub Pages.

Include a preview URL in your PR comments.

Creating a Fork for GitHub Pages

Log into GitHub
Go to github.com/kubestellar/kubestellar
Click the Forks dropdown and create a new fork
Important: Uncheck “copy the main branch” to include the gh-pages branch
In fork Settings, go to Pages and configure publishing from the gh-pages branch

If you already have a fork without gh-pages, run:


git checkout upstream/gh-pages
git push -f origin gh-pages

Manually Generate Website from Fork Branch

Commit changes to your branch
Push to your fork
Go to Actions tab
Select “Generate and Push Docs”
Click “Run Workflow”
Select your branch and run
Wait for completion (green checkmark)
Access at https://{repo_owner}.github.io/{fork_name}/{branch_name}

Informational Errors

The broken links crawler may fail even when docs generation succeeds. This is informational.

Switching Between Versions

Each branch renders as its own version. Use the version dropdown to switch.

Note: The main branch renders as main, not “unreleased-development”.

Removing Outdated Versions

Method 1: Using mike


git checkout gh-pages
git pull
mike delete doc-mybranch
git commit -m "Remove outdated doc-mybranch version"
git push origin gh-pages

Or with immediate push:


git checkout gh-pages
git pull
mike delete --push doc-mybranch

Method 2: Reset gh-pages


git checkout upstream/gh-pages
git push -f origin gh-pages

Warning: This removes ALL custom versions.

Best Practices

Clean up after PR merges
Use descriptive branch names
Run mike list before deleting
Coordinate with team members

Serving Documents Locally

Clone and serve locally:


git clone git@github.com:kubestellar/kubestellar.git
cd kubestellar/docs

Install requirements:


pip install -r requirements.txt

Or use the virtual environment:


cd .. && make venv
. venv/bin/activate

Serve documents:


mkdocs serve

Open browser to http://localhost:8000/

Supported Aliases

We maintain alias: latest for the latest regular release.

Publishing from Main Branch

The main branch publishes as “unreleased-development”.

Shortcut URLs

Join our mailing list for access to some links.

kubestellar.io/agenda - Community meeting agenda
kubestellar.io/blog - Medium reading list
kubestellar.io/code - GitHub repo
kubestellar.io/community - Community page
kubestellar.io/drive - Google drive
kubestellar.io/joinus - Dev mailing list
kubestellar.io/linkedin - LinkedIn
kubestellar.io/tv - YouTube channel
kubestellar.io/quickstart - Getting Started guide

Jinja Templating

Our stack includes Jinja for templating in markdown sources.

File Structure

Documentation lives in docs/:

Path	Description
config/language/mkdocs.yml	Language-specific mkdocs configuration
content/language	Language-specific website content
generated/branch	Generated content for current version
overrides	Global content
Dockerfile	Builds kubestellar-docs image
mkdocs.yml	Minimal mkdocs configuration for mike
requirements.txt	Python modules list

Global Variables

Common variables in docs/mkdocs.yml:

site_name
repo_url
site_url
docs_url
ks_branch
ks_tag
ks_latest_release

Navigation is configured in docs/mkdocs.yml under the nav: section.

Page Variables

Define page variables in frontmatter:


---
short_name: example1
manifest_name: docs/content/example.md
---

Including External Markdown

Use include-markdown blocks to include content from other files. See the mkdocs-include-markdown-plugin documentation.

Codeblocks

Use different codeblock styles:

Seen and executed - Use shell:


mkdocs serve

Executed but not seen - Use .bash .hide-me

Seen but not executed - Use .bash without hide-me

With title - Add a title parameter to the codeblock

Testing Documentation

We use docs-ecutable to test documented examples in CI.

How it works:

Create .md files with codeblocks
Use shell for tested code
Use .bash .hide-me for tested but hidden code
Use plain codeblocks for sample output

Running tests:


make MANIFEST="docs/content/Getting-Started/quickstart.md" docs-ecutable

Important gh-pages Files

index.html and home.html - Redirect to latest version

CNAME - Required for domain recognition. Contains: docs.kubestellar.io

versions.json - Maintained by mike, do not edit manually

Emergency Recovery

If pages are not showing:

Check index.html, home.html, CNAME, and versions.json exist in gh-pages
Verify GitHub Pages settings point to docs.kubestellar.io with HTTPS enforced

Recreating gh-pages Branch


git clone -b gh-pages https://github.com/kubestellar/kubestellar KubeStellar
cd KubeStellar
rm -rf *
git add . && git commit -m "removing all gh-pages files" && git push -u origin gh-pages
git checkout release-0.22
git pull
mike deploy --push --rebase --update-aliases release-0.22 latest
cd ..
git checkout gh-pages
git pull

Then recreate index.html, home.html, CNAME files and push. Configure GitHub Pages in repository settings.

Deleting a Branch Rendering

Use mike delete $branch_name with --remote and --push flags.

Publishing Workflow

The .github/workflows/docs-gen-and-push.yml workflow:

Triggers on push to main, release-*, or doc-* branches
Works on kubestellar/kubestellar or contributor forks
Creates website version matching branch name
Updates mike aliases as needed

The “pages build and deployment” workflow (GitHub-provided) copies content from gh-pages to the web server.