Why Kubernetes Website CSS Needs Improvement: What Should be Done and How it Should be Done

[mboukhalfa]

This is an Enhancement Request

During my recent work on issue #45077 and pull request #46042, I've noticed several issues with the CSS and styling on the Kubernetes website. This issue aims to outline these concerns, propose a clear plan for improvement and initiate a discussion to gather experienced and interested individuals to collaborate on enhancing the website's CSS and styling.

Why Kubernetes Website CSS Needs Improvement:

1. Outdated Docsy Version: Kubernetes is currently using the oldest available version of Docsy (v0.2.0) among 12 releases. Being so outdated, it lacks maintainer support and misses out on newer features and fixes. Updating to a newer Docsy version (e.g., v0.10.0) would guarantees support.
   

   website/.gitmodules

   Lines 1 to 4 in 9484b67

   	[submodule "themes/docsy"]
   	path = themes/docsy
   	url = https://github.com/google/docsy.git
   	branch = v0.2.0

2. Bootstrap Dependency: While Docsy is intended to package Bootstrap, Kubernetes also relies on a local Bootstrap version, introducing complexity and leading to potential conflicts and maintenance issues.
   https://github.com/kubernetes/website/blob/release-1.29/static/css/bootstrap-4.3.1.min.css
   https://github.com/kubernetes/website/blob/release-1.29/static/css/bootstrap-5.3.2.min.css

3. Excessive Custom CSS: There is a significant amount of custom CSS, which goes against the intended purpose of using Docsy and issues with styling end up being addressed within Kubernetes repositories instead of upstream in Docsy. For instance, We initially wanted to report an issue with Right-to-Left (RTL) support directly to Docsy Docsy RTL issue #1442, and focus on localizing content. However, extensive debugging revealed the issue stemmed from our custom styling. Consequently, I opened related styling issues in both Kubernetes k8s RTL issue and Google repositories Docsy RTL issue #1442, resulting in multiple hard-to-track issues.

4. Custom CSS Practices: Some custom CSS practices, such as adding the logo as a background to a <a> element, deviate from best practices and may pose maintenance challenges. For instance, in pull request #46042, when I modified some Bootstrap classes, the logo's position deviated from the expected outcome, necessitating further adjustments.
   

   website/layouts/partials/navbar.html

   Line 3 in 1873414

   <a class="navbar-brand img-fluid" href="{{ .Site.Home.RelPermalink }}"></a>

   
   

   website/assets/scss/_custom.scss

   Lines 132 to 139 in 1873414

   	.navbar-brand {
   	position: absolute;
   	width: 45px;
   	height: 44px;
   	background-repeat: no-repeat;
   	background-size: contain;
   	background-image: url("/images/favicon.png");
   	}

5. Lack of Dedicated Web Development Team: While attempting to address issues like RTL support, limited support and review were available. For example, when seeking assistance through channels like Kubernetes Slack channel, we received no positive reactions. Establishing a dedicated team responsible for web development aspects, with periodic meetings and clear responsibilities, could greatly improve collaboration and support and prevent the introduction of bad CSS and JS code.

What Should be Done
TBD

How it Should be Done
TBD

[k8s-ci-robot]

This issue is currently awaiting triage.

SIG Docs takes a lead on issue triage for this website, but any Kubernetes member can accept issues by applying the triage/accepted label.

The triage/accepted label can be added by org members by writing /triage accepted in a comment.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

[Aaina26]

/area web-development