Planning the future development of the KubeStellar website and documentation

[KPRoche]

Introduction: How we got here and what this discussion board is for.

A huge amount of effort went into the launch of the new Nextra-based kubestellar.io site, first in developing its visual language and components, and then in implementing that new design as an operational website.

Problems with the current version

Like many major projects, the site is exhibiting growing pains.

Most significantly, the original design called for pulling docs files for the individual component repos of the KubeStellar system from those repos dynamically, and rendering that into a unified site. The performance of pulling those files on the fly from GitHub was extremely poor, with some pages taking 30-60 seconds to load.

We therefore pulled copies of the current release documentation into this kubestellar/docs repository and that eased the performance issue, but severed the connection between the original repo docs structure and their representation on the website.

Most significantly, it broke the ability to render multiple versions of the docs for the extant releases of KubeStellar as well as the under-development branch. It also makes it harder for contributors to understand how to update the docs to match their contributions, and for reviewers to properly assess PRs.

This discussion is intended as a place where the KubeStellar community can map out how the site and docs and their management processes can be improved to make the site more useful and maintainable.

It is expected that points made in this discussion will be used to create issues on the kubestellar/docs repository and subsequent PRs to address the issues.

[KPRoche]

January 9 2026 Docs Kickoff Call

Today we had a brief (45 minute) virtual meeting to discuss the status of the site, where we saw problems and what our initial focus might be. The very rough agenda of topics we started with was:

1. How do we manage multiple versions of documentation for the multiple KubeStellar component repos?
   a. Which versions/releases are old enough that we can elide/ignore them
   b. Which versions are highest priority to add to the site ASAP?
2. Reexamining our semantic structure (map) to better organize the docs (with versions) of the different components
3. Documenting key Nextra techniques for our site designers:
   a) how menu structure is generated by Nextra?
   i) How much is automated via file tree now? vs How much is custom routes?
   ii) Could we start using _meta.js files instead of our custom pagemap now that we have consolidated?
   b) Can we automate site generation for a branch (version) from a file tree of MDX files?
   c) How do we accomplish the tricks with version names in bash code that were done with variables in the mkdocs version
   d) Document where key files are for contributors (message files for language support, etc)
   e) Document any key "don't touch" files for new contributors
4. Document basic doc writing process to help coders make updates.
5. What does someone reviewing PRs need to know what to do, starting right now, about PRs that affect documentation?

As a starting focus, the meeting attendees agreed on the following areas to begin work on:

Multiversion: add key kubestellar docs

1.b The versions with highest priority to add to the new docs are unreleased-development (from the main branch) and release-0.29.0 (aka latest). The current website docs are based on 0.29.0 but are not fully up-to-date.

Document Nextra navigation process

3.a Understanding and documenting how the website navigation is generated by Nextra to ease future development

Additional items

3.b Examining/experimenting with file trees of MDX files... @KPRoche will do some experimentation when he returns later in January
4 and 5 as soon as we start decoding the menuing logic of the Nextra build engine, we can start working on the "how to write/review KubeStellar docs with an eye to the Nextra site" instructions.

There was also some consensus that Slack discussions of the site and documentation content would best take place in the more general kubestellar-dev channel while Nextra-specific tweaks and maintenance go in the private kubestellar-docs channel.

Useful reference links

The active Nextra based site is at https://kubestellar.io
The legacy mkdocs-driven site is at https://kubestellar.github.io/kubestellar
The KubeStellar github organization (with all its repos) is at https://github.com/kubestellar

[KPRoche]

Considering Website/docs layout (topic 2)

(Pulling this into a separate comment so it can have its own thread)

During the meeting I suggested this sort of structure for the documentation site in general. (This is painted with a broad brush, not intended as an exact map.)

• Landing Page
  • [assorted community/market pages]
  • Docs
    • [Architecture pages]
    • [Roadmap, etc pages]
    • User Guide
      • "Global" Intro Section might include the Getting Started using latest stable version)
      • KubeStellar
        • [release picker]
        • [latest]
        • [unreleased-development]
        • [previous release]
        • [previous release]
        • ⋮
      • KubeStellar UI
        • [release picker]
        • [latest]
        • [unreleased-development]
        • [previous release]
        • [previous release]
        • ⋮
      • KubeFlex
        • [release picker]
        • [latest]
        • [unreleased-development]
        • [previous release]
        • [previous release]
        • ⋮
        • [etc. etc.]
  • Contributing
    • General guidelines
    • Docs specific guidelines
    • ⋮
  • (The other high level topics)

---

This is a very crude map, but as I am traveling soon I wanted to record it here before I go offline.

[MikeSpreitzer]

I am not sure whether or where this fits into the existing taxonomy, but I think that there should be some basic principles about how things hang together. Following is what I suggest.

• Every page should be reachable from the navigation tree.
• Every page should be reachable by following links from one page to another, starting from the root page.
• Every non-leaf vertex V in the navigation tree should have an overview page that gives an overview of V, including links to each direct child of V (other than itself).

[MikeSpreitzer]

Regarding item 2, there is content from the mkdocs site that got lost in creating the new site. In particular, https://kubestellar.github.io/kubestellar/unreleased-development/contribution-guidelines/contributing-inc/ got lost. You might think that it is at the following page, but (as you can see) that page actually has different content (it is about contributing to the docs, not the lost content).

[aaradhychinche-alt]

#786
Could you please suggest what change you’d like for this issue and where it should be applied? I’ll update the docs accordingly.

[aaradhychinche-alt]

@MikeSpreitzer That makes sense.To be sure I do this the right way: should I copy the full content into a single new page, or expand the existing page to include the complete explanation? Please let me know which approach you prefer.

[KPRoche]

@aaradhychinche-alt I would recommend looking at the old mkdocs source to see exactly what (and where in the page) it was importing, and add that into the new site page's source file. If there are not already headers they should be added for the sections (or they may be part of the imported sections). The mkdocs-include directive allowed one to specify start and stop markers for importing from the remote file, so it is possible it was importing from more than one file, or multiple sections from one file.

[aaradhychinche-alt]

@KPRoche Got it I’ll check the old MkDocs sources to see exactly what was being included and where, and then mirror that content in the new page with proper section headers.

[KPRoche]

@aaradhychinche-alt and @MikeSpreitzer we have a PR from another contributor that may be able to re-enable that include directive. It's worth it to take a look at #704 and see if it is a quicker path for us.
preview deploy of the PR at https://deploy-preview-704--kubestellar-docs.netlify.app/

[KPRoche]

Update: PR 704 was approved. See if this fixes the page in question (it may not for latest, only for dev)

[MikeSpreitzer]

We need to talk about the hierarchy within one version of the documentation. I think this is part of item 2.

I have a link to an old design: https://www.figma.com/board/IHLBwlFC6i4Ibh2DVIzBxX/KubeStellar%E2%80%AFv0.27.2-Documentation--UI--and-Design-System-Audit?node-id=235-1320&p=f . That is the latest design document that I have.

FYI, the mkdocs site is at https://kubestellar.github.io/kubestellar/unreleased-development/readme/

In that Figma outline, I see docs/install & configure and then there is also docs/use & integrate --- and the only real "integrate" content is about ArgoCD. To me, "integrate" seems like part of "install & configure". Note also that now the KubeStellar core Helm chart has an option for installing ArgoCD and doing some integration.

More importantly, there is not a single strong clear division between "install" and "use". For a picture, see https://kubestellar.github.io/kubestellar/unreleased-development/direct/user-guide-intro/#the-full-story . KubeStellar is intended to be enterprise software, not demo-ware. Enterprise software needs to fit a variety of use cases. They differ in what is determined and when and by whom. Following are some degrees of variation envisaged.

• The Kubernetes cluster used to host KubeFlex might be a special cluster used only for this purpose, or might be a cluster that has other purposes too and existed long before KubeFlex gets installed there. In production use it will not be a kind or k3d cluster, rather it will be a cluster that the enterprise creates in its own way.
• There may be a fixed collection of ITSes and WDSes created by the enterprise at KubeStellar setup time, or the collection might vary over time. Individual WDSes might be owned/used by different sub-units of the enterprise.
• Possibly different WDSes will distribute software to the same WECs. Imagine, for example an enterprise with a layer cake of software to distribute. Each WDS is for a distinct box in the layer cake.
• There might be one ITS and several WDSes that use it, or ITS and WDS might come and go in pairs.
• There might be a fixed collection of WECs that get created at setup time, or WECs might come and go over time.

[KPRoche]

I agree, cleaning up this hierarchy is one of the top things on my list.

I think there is a case to be made for a direct "get started" link to run the demo but it should pop you into a point in the overall manual, not be pulled out as a separate section of the site. We had a similar structural disagreement with some contributors back when I redesigned the mkdocs based site.

[KPRoche]

IMPORTANT: Modification coming to kubestellar/kubestellar repository doc files

After a small swarm of PRs in the last week to modify the copies of the documentation files remaining in the kubestellar/kubestellar repository, instead of the active version in the kubestellar/docs repository, I am preparing to remove the redundant files from the repo and replace them with a readme saying "edit docs files in the doc repo"

I don't want contributors wasting their energy editing the wrong files nor our reviewers time and energy dealing with PRs on the wrong files.