diff --git a/config/mkdocs-overrides/stylesheets/skupper-overrides.css b/config/mkdocs-overrides/stylesheets/skupper-overrides.css new file mode 100644 index 0000000..2e2722a --- /dev/null +++ b/config/mkdocs-overrides/stylesheets/skupper-overrides.css @@ -0,0 +1,334 @@ +/* + * Skupper MkDocs Material Theme Overrides + * + * This file bridges Material Design theme with Skupper's existing CSS. + * It hides Material's header/footer and adjusts layout for Skupper's custom header/footer. + */ + +/* Reset Material's large font sizes to match homepage */ +html { + font-size: 16px; /* Browser default, not Material's 20px */ +} + +.md-typeset { + font-size: 1rem; /* Reset from Material's 1.25rem */ + line-height: 1.5; /* Match homepage line-height */ +} + +.md-typeset h1 { + font-size: 2em; /* Reset from Material's larger size */ + line-height: 1.2; +} + +.md-typeset h2 { + font-size: 1.5em; /* Reset from Material's larger size */ + line-height: 1.3; +} + +.md-typeset h3 { + font-size: 1.25em; /* Reset from Material's larger size */ + line-height: 1.4; +} + +.md-typeset h4 { + font-size: 1.1em; + line-height: 1.4; +} + +.md-typeset p, .md-typeset li { + font-size: 1rem; /* Match body text */ +} + +/* Hide Material's default header and footer visually but keep in DOM for JS */ +.md-header { + visibility: hidden !important; + height: 0 !important; + min-height: 0 !important; + overflow: hidden !important; + position: absolute !important; +} + +.md-footer { + visibility: hidden !important; + height: 0 !important; + min-height: 0 !important; + overflow: hidden !important; + position: absolute !important; +} + +/* Adjust main content area to account for Skupper header */ +.md-main { + margin-top: 0; +} + +.md-container { + padding-top: 0; +} + +/* Ensure Skupper header is at the top */ +body > header { + position: sticky; + top: 0; + z-index: 1000; +} + +/* Ensure Skupper footer is at the bottom */ +body > footer { + margin-top: auto; +} + +/* Make body a flex container for sticky footer */ +body { + display: flex; + flex-direction: column; + min-height: 100vh; +} + +/* Ensure main content grows to push footer down */ +.md-container { + flex: 1; +} + +/* Adjust sidebar positioning to account for Skupper header */ +.md-sidebar { + top: 0; + padding-top: 1em; +} + +.md-sidebar--primary { + top: 0; +} + +.md-sidebar--secondary { + top: 0; +} + +/* Match Skupper's link colors in content */ +.md-content a { + color: #306b8f; +} + +.md-content a:hover { + color: #5eba7d; +} + +/* Match Skupper's code block styling */ +.md-typeset code { + background-color: hsl(0, 0%, 97%); +} + +.md-typeset pre { + background-color: hsl(0, 0%, 97%); +} + +/* Adjust content width and layout to match Skupper's layout */ +.md-grid { + max-width: 1200px; + margin: 0 auto; +} + +.md-content__inner { + max-width: none; + margin: 0; + padding: 2.4em 1em; +} + +/* Ensure proper spacing for main content area */ +.md-main__inner { + margin-top: 0; +} + +/* Ensure header uses flexbox layout - Font 1.5x, Other params 1.3x */ +header { + display: flex !important; + justify-content: flex-start; + align-items: center; + width: 100%; + padding: 1.3em 0; /* Remove horizontal padding */ + position: sticky; + top: 0; +} + +/* Logo on the left - Fixed to left edge */ +header > a#-logo { + display: flex; + align-items: center; + gap: 0.65em; + text-decoration: none; + color: var(--text-color); + font-size: 1.8em; + font-weight: 700; + font-family: var(--heading-font-family); + margin-left: 2em; /* Fixed distance from left edge */ +} + +header > a#-logo img { + height: 3.9em; /* 20% bigger than original 3.25em (3.25 * 1.2 = 3.9) */ +} + +/* Center section with nav and GitHub */ +header > div { + display: flex; + flex: 1; + justify-content: center; + align-items: center; + margin: 0 2em; +} + +/* Navigation tabs in center - Font 1.5x, Gap 1.3x */ +header nav#-tabs { + display: flex; + gap: 2.1em; /* 1.3x from 2em */ + font-size: 1.9em; /* 1.5x scaling - KEEP */ +} + +header nav#-tabs a { + text-decoration: none; + color: var(--text-color); + padding: 0.65em 0; /* 1.3x from 0.5em 0 */ + border-bottom: 3.9px solid transparent; /* 1.3x from 3px */ +} + +header nav#-tabs a:hover { + border-bottom-color: var(--accent-color-1); +} + +header nav#-tabs a.selected { + border-bottom-color: var(--accent-color-2); + font-weight: 700; +} + +/* GitHub link - Positioned at right edge */ +header > div > a[href*="github"] { + text-decoration: none; + color: var(--text-color); + display: flex; + align-items: center; + gap: 0.39em; + font-size: 1.5em; + position: absolute; + right: 2em; +} + +/* Hide "GitHub" text, show only icon */ +header > div > a[href*="github"] div { + font-size: 0; +} + +header > div > a[href*="github"] span { + font-size: 1.5rem; /* Restore icon size */ +} + +/* Center the footer content and match home page styling */ +footer { + border: 0 !important; + background-color: var(--footer-background-color) !important; + color: white !important; + padding: 3em 1em !important; + display: flex !important; + justify-content: center !important; + font-size: 1rem !important; + line-height: 1.5 !important; + margin: 0 !important; +} + +footer a { + color: white !important; +} + +footer h4 { + font-size: 1.1rem !important; + margin: 0.5em 0 !important; +} + +footer p { + font-size: 1rem !important; + margin: 0.5em 0 !important; +} + +footer > div { + max-width: 1200px !important; + width: var(--page-width) !important; + padding: 2em !important; + display: flex !important; + gap: 2em !important; +} + +footer > div > div { + flex: 1; +} + +footer > div > div:first-child { + flex: 0; + min-width: 10em; +} + +/* Ensure sidebar navigation matches Skupper styling */ +.md-nav__link { + color: hsl(0, 0%, 20%); +} + +.md-nav__link:hover { + color: #306b8f; +} + +.md-nav__link--active { + color: #306b8f; + font-weight: 700; +} + +/* Match Skupper's heading styles */ +.md-typeset h1 { + color: hsl(0, 0%, 20%); +} + +.md-typeset h2 { + color: hsl(0, 0%, 20%); +} + +.md-typeset h3 { + color: hsl(0, 0%, 20%); +} + +/* Responsive adjustments */ +@media screen and (max-width: 76.1875em) { + .md-sidebar--primary { + transform: translateX(-100%); + } + + [data-md-toggle="drawer"]:checked ~ .md-container .md-sidebar--primary { + transform: translateX(0); + } +} + +/* Ensure proper spacing around content */ +.md-content { + padding: 2em 1em; +} + +/* Match Skupper's table styling */ +.md-typeset table:not([class]) { + border-collapse: collapse; +} + +.md-typeset table:not([class]) th, +.md-typeset table:not([class]) td { + border: 1px solid hsl(0, 0%, 90%); + padding: 0.5em 1em; +} + +/* Adjust search box styling to match Skupper */ +.md-search__input { + background-color: hsl(0, 0%, 97%); +} + +/* Fix any z-index issues between Skupper header and Material sidebar */ +.md-sidebar { + z-index: 999; +} + +body > header { + z-index: 1000; +} + +/* Made with Bob */ diff --git a/config/mkdocs_macros.py b/config/mkdocs_macros.py new file mode 100644 index 0000000..f7eb6a8 --- /dev/null +++ b/config/mkdocs_macros.py @@ -0,0 +1,88 @@ +""" +MkDocs Macros Plugin Configuration + +This module defines variables and macros for MkDocs that mirror +the Transom template variables used in the main site. + +Variables are read from the same data sources as Transom to ensure consistency. +""" + +import json +from pathlib import Path +from datetime import datetime + + +def define_env(env): + """ + Define variables and macros for MkDocs. + + This function is called by the mkdocs-macros-plugin and provides + access to the same variables that Transom uses. + + Args: + env: The MkDocs macros environment object + """ + + # Read release data from the same source as Transom + releases_file = Path("input/data/releases.json") + + if releases_file.exists(): + try: + releases = json.loads(releases_file.read_text()) + latest = releases.get("latest", {}) + + # Set version variables from releases.json + env.variables['skupper_version'] = latest.get("version", "2.1.1") + env.variables['skupper_cli_version'] = latest.get("version", "2.1.1") + env.variables['latest_release_version'] = latest.get("version", "2.1.1") + env.variables['latest_release_date'] = latest.get("date", "") + + # Format the date if available + if env.variables['latest_release_date']: + try: + date_obj = datetime.fromisoformat(env.variables['latest_release_date'].replace('Z', '+00:00')) + env.variables['latest_release_date'] = date_obj.strftime("%Y-%m-%d") + except: + pass # Keep original format if parsing fails + + except Exception as e: + print(f"Warning: Could not read releases.json: {e}") + # Fall back to default values + env.variables['skupper_version'] = "2.1.1" + env.variables['skupper_cli_version'] = "2.1.1" + env.variables['latest_release_version'] = "2.1.1" + env.variables['latest_release_date'] = "" + else: + print(f"Warning: {releases_file} not found, using default values") + env.variables['skupper_version'] = "2.1.1" + env.variables['skupper_cli_version'] = "2.1.1" + env.variables['latest_release_version'] = "2.1.1" + env.variables['latest_release_date'] = "" + + # Set other variables + env.variables['skupper_version_v1'] = "1.9.2" + + # Site prefix for navigation links + # Empty for production (https://skupper.io), can be set for local dev or staging + # Example: env.variables['site_prefix'] = "http://localhost:8000" + env.variables['site_prefix'] = env.conf.get('extra', {}).get('site_prefix', '') + + # Define helper macros if needed + @env.macro + def get_download_url(version): + """Generate a download URL for a specific Skupper version""" + return f"https://github.com/skupperproject/skupper/releases/download/{version}" + + @env.macro + def get_helm_chart_url(chart_name, version): + """Generate a Helm chart URL""" + return f"oci://quay.io/skupper/helm/{chart_name}" + + # Print variables for debugging (only during build) + if env.conf.get('verbose', False): + print("MkDocs Variables:") + print(f" skupper_version: {env.variables['skupper_version']}") + print(f" skupper_cli_version: {env.variables['skupper_cli_version']}") + print(f" skupper_version_v1: {env.variables['skupper_version_v1']}") + +# Made with Bob diff --git a/input/index.html.in b/input/index.html.in index e662cf8..d5e175e 100644 --- a/input/index.html.in +++ b/input/index.html.in @@ -70,3 +70,9 @@ title: Documentation + +

Troubleshooting

+

Learn how to diagnose common application network problems.

+ diff --git a/input/kube-cli/index.md b/input/kube-cli/index.md index 38b911b..f401eb0 100644 --- a/input/kube-cli/index.md +++ b/input/kube-cli/index.md @@ -1,5 +1,6 @@ # Overview of Skupper CLI on Kubernetes + You can use the `skupper` CLI on Kubernetes after installing the Skupper controller to configure sites, links and services. @@ -11,4 +12,4 @@ The Skupper CLI is designed to generate and consume standard resources, ensuring [site-configuration]: ./site-configuration.html [site-linking]: ./site-linking.html -[service-exposure]: ./service-exposure.html \ No newline at end of file +[service-exposure]: ./service-exposure.html diff --git a/input/kube-cli/service-exposure.md b/input/kube-cli/service-exposure.md index 72b8f85..caa348a 100644 --- a/input/kube-cli/service-exposure.md +++ b/input/kube-cli/service-exposure.md @@ -1,5 +1,8 @@ # Exposing services on the application network using the CLI + + +Create connectors and listeners to expose services across the application network. After creating an application network by linking sites, you can expose services from one site using connectors and consume those services on other sites using listeners. A *routing key* is a string that matches one or more connectors with one or more listeners. @@ -10,6 +13,7 @@ This section assumes you have created and linked at least two sites. ## Creating a connector using the CLI + A connector binds a local workload to listeners in remote sites. Listeners and connectors are matched using routing keys. @@ -36,14 +40,14 @@ For more information about connectors, see [Connector concept][connector]. ```bash skupper connector status ``` - For example: - - ``` + + ```bash $ skupper connector status NAME STATUS ROUTING-KEY SELECTOR HOST PORT HAS MATCHING LISTENER MESSAGE backend Pending backend app=backend 8080 false No matching listeners ``` + **📌 NOTE** By default, the routing key name is set to the name of the connector. If you want to use a custom routing key, set the `--routing-key` to your custom name. @@ -57,6 +61,7 @@ If you need to expose a service from another namespace, you must use YAML as des ## Creating a listener using the CLI + A listener binds a local connection endpoint to connectors in remote sites. Listeners and connectors are matched using routing keys. @@ -73,7 +78,8 @@ For more information about listeners. see [Listener concept][listener]. skupper listener create [--routing-key ] ``` For example: - ``` + + ```bash $ skupper listener create backend 8080 Waiting for create to complete... Listener "backend" is ready @@ -83,15 +89,14 @@ For more information about listeners. see [Listener concept][listener]. ```bash skupper listener status ``` - For example: - - ``` + + ```bash $ skupper listener status NAME STATUS ROUTING-KEY HOST PORT MATCHING-CONNECTOR MESSAGE backend Ready backend backend 8080 true OK ``` - + **📌 NOTE** There must be a `MATCHING-CONNECTOR` for the service to operate. By default, the routing key name is the listener name. diff --git a/input/kube-cli/site-configuration.md b/input/kube-cli/site-configuration.md index 7dce8b5..079715b 100644 --- a/input/kube-cli/site-configuration.md +++ b/input/kube-cli/site-configuration.md @@ -1,5 +1,6 @@ # Creating a site on Kubernetes using the Skupper CLI + Using the skupper command-line interface (CLI) allows you to create and manage sites from the context of the current namespace. @@ -7,9 +8,12 @@ A typical workflow is to create a site, link sites together, and expose services ## Checking the Skupper CLI + Installing the skupper command-line interface (CLI) provides a simple method to get started with Skupper. +**Procedure** + 1. Follow the instructions for [Installing Skupper](https://skupper.io/releases/index.html). 2. Verify the installation. @@ -22,6 +26,9 @@ Installing the skupper command-line interface (CLI) provides a simple method to ## Creating a simple site using the CLI on Kubernetes + + +Use the Skupper CLI to create a site on Kubernetes from the current namespace context. **Prerequisites** @@ -52,28 +59,24 @@ Installing the skupper command-line interface (CLI) provides a simple method to ``` There are many options to consider when creating sites using the CLI, see [CLI Reference][cli-ref], including *frequently used* options. -For example - -* `--enable-link-access` - - If enabled, this option allows you create tokens and link *to* this site. - By default, this option is disabled but you can change the setting later `skupper site update --enable-link-access`. - -* `--timeout