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

[k8s-triage-robot]

The Kubernetes project currently lacks enough contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle stale
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle stale

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues.

This bot triages un-triaged issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Mark this issue as fresh with /remove-lifecycle rotten
• Close this issue with /close
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/lifecycle rotten

[k8s-triage-robot]

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

[k8s-ci-robot]

@k8s-triage-robot: Closing this issue, marking it as "Not Planned".

In response to this:

The Kubernetes project currently lacks enough active contributors to adequately respond to all issues and PRs.

This bot triages issues according to the following rules:

• After 90d of inactivity, lifecycle/stale is applied
• After 30d of inactivity since lifecycle/stale was applied, lifecycle/rotten is applied
• After 30d of inactivity since lifecycle/rotten was applied, the issue is closed

You can:

• Reopen this issue with /reopen
• Mark this issue as fresh with /remove-lifecycle rotten
• Offer to help out with Issue Triage

Please send feedback to sig-contributor-experience at kubernetes/community.

/close not-planned

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.

[mboukhalfa]

/reopen
/remove-lifecycle rotten

[k8s-ci-robot]

@mboukhalfa: Reopened this issue.

In response to this:

/reopen
/remove-lifecycle rotten

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.