Fix Automatic Markdown Sidebar (k3s-io#20)

* Convert header 1 markdown anchors * Add vscode to gitignore * Update the README Signed-off-by: Derek Nola <[email protected]>
dereknola · Sep 7, 2022 · 3cdba29 · 3cdba29
1 parent d4ac840
commit 3cdba29
Show file tree

Hide file tree

Showing 8 changed files with 27 additions and 36 deletions.
diff --git a/.gitignore b/.gitignore
@@ -14,6 +14,7 @@
 .env.development.local
 .env.test.local
 .env.production.local
+.vscode
 
 npm-debug.log*
 yarn-debug.log*

diff --git a/README.md b/README.md
@@ -1,6 +1,8 @@
-# Website
+# K3s Website and Docs
 
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+This repo contains the content of the K3s landing page and documentation. Please open an issue if you have suggestions for new content or edits. We also gladly accept community PRs. 
+
+The website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
 
 ### Installation
 
@@ -31,16 +33,4 @@ This command generates static content into the `build` directory and can be serv
 
 ### Deployment
 
-Using SSH:
-
-```
-$ USE_SSH=true yarn deploy
-```
-
-Not using SSH:
-
-```
-$ GIT_USER=<Your GitHub username> yarn deploy
-```
-
-If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
+An automated GH action will deploy the website to GitHub Pages once a PR has been merged to `main`.
diff --git a/docs/installation/airgap.md b/docs/installation/airgap.md
@@ -7,7 +7,7 @@ import TabItem from '@theme/TabItem';
 
 You can install K3s in an air-gapped environment using two different methods. An air-gapped environment is any environment that is not directly connected to the Internet. You can either deploy a private registry and mirror docker.io, or you can manually deploy images such as for small clusters.
 
-# Private Registry Method
+## Private Registry Method
 
 This document assumes you have already created your nodes in your air-gap environment and have a Docker private registry on your bastion host.
 
@@ -20,7 +20,7 @@ Follow the [Private Registry Configuration](private-registry.md) guide to create
 Once you have completed this, you may now go to the [Install K3s](#install-k3s) section below.
 
 
-# Manually Deploy Images Method
+## Manually Deploy Images Method
 
 We are assuming you have created your nodes in your air-gap environment.
 This method requires you to manually deploy the necessary images to each node and is appropriate for edge deployments where running a private registry is not practical.
@@ -39,7 +39,7 @@ Place the k3s binary at `/usr/local/bin/k3s` and ensure it is executable.
 
 Follow the steps in the next section to install K3s.
 
-# Install K3s
+## Install K3s
 
 ### Prerequisites
 
@@ -92,7 +92,7 @@ INSTALL_K3S_SKIP_DOWNLOAD=true INSTALL_K3S_EXEC='server' K3S_DATASTORE_ENDPOINT=
 
 >**Note:** K3s additionally provides a `--resolv-conf` flag for kubelets, which may help with configuring DNS in air-gap networks.
 
-# Upgrading
+## Upgrading
 
 ### Install Script Method
 

diff --git a/docs/installation/disable-flags.md b/docs/installation/disable-flags.md
@@ -5,7 +5,7 @@ weight: 60
 
 Starting the K3s server with `--cluster-init` will run all control plane components, including the api server, controller manager, scheduler, and etcd. However, you can run server nodes with certain components and exclude others; the following sections will explain how to do that.
 
-# ETCD Only Nodes
+## ETCD Only Nodes
 
 This document assumes you run K3s server with embedded etcd by passing `--cluster-init` flag to the server process.
 
@@ -17,7 +17,7 @@ curl -fL https://get.k3s.io | sh -s - server --cluster-init --disable-apiserver
 
 You can join other nodes to the cluster normally after that.
 
-# Disable ETCD
+## Disable ETCD
 
 You can also disable etcd from a server node and this will result in a k3s server running control components other than etcd, that can be accomplished by running k3s server with flag `--disable-etcd` for example to join another node with only control components to the etcd node created in the previous section:
 
@@ -55,7 +55,7 @@ ip-172-31-14-69   Ready    control-plane,master        5h45m   v1.20.4+k3s1
 
 Notice that role labels has been re-added to the node `ip-172-31-13-32` with the correct labels (control-plane,etcd,master).
 
-# Add disable flags using the config file
+## Add disable flags using the config file
 
 In any of the previous situations you can use the config file instead of running the curl commands with the associated flags, for example to run an etcd only node you can add the following options to the `/etc/rancher/k3s/config.yaml` file:
 
@@ -71,7 +71,7 @@ and then start K3s using the curl command without any arguents:
 ```bash
 curl -fL https://get.k3s.io | sh -
 ```
-# Disable components using .skip files
+## Disable components using .skip files
 
 For any yaml file under `/var/lib/rancher/k3s/server/manifests` (coredns, traefik, local-storeage, etc.) you can add a `.skip` file which will cause K3s to not apply the associated yaml file.
 For example, adding `traefik.yaml.skip` in the manifests directory will cause K3s to skip `traefik.yaml`.

diff --git a/docs/installation/ha.md b/docs/installation/ha.md
@@ -18,7 +18,7 @@ For more details on how these components work together, refer to the [architectu
 
 Agents register through the fixed registration address, but after registration they establish a connection directly to one of the server nodes. This is a websocket connection initiated by the `k3s agent` process and it is maintained by a client-side load balancer running as part of the agent process.
 
-# Installation Outline
+## Installation Outline
 
 Setting up an HA cluster requires the following steps:
 

diff --git a/docs/installation/private-registry.md b/docs/installation/private-registry.md
@@ -13,7 +13,7 @@ Note that server nodes are schedulable by default. If you have not tainted the s
 
 Configuration in containerd can be used to connect to a private registry with a TLS connection and with registries that enable authentication as well. The following section will explain the `registries.yaml` file and give different examples of using private registry configuration in K3s.
 
-# Registries Configuration File
+## Registries Configuration File
 
 The file consists of two main sections:
 
@@ -149,7 +149,7 @@ mirrors:
 
 In order for the registry changes to take effect, you need to restart K3s on each node.
 
-# Adding Images to the Private Registry
+## Adding Images to the Private Registry
 
 First, obtain the k3s-images.txt file from GitHub for the release you are working with.
 Pull the K3s images listed on the k3s-images.txt file from docker.io

diff --git a/docs/networking/networking.md b/docs/networking/networking.md
@@ -18,13 +18,13 @@ For information on which ports need to be opened for K3s, refer to the [ Require
   - [Disabling the Service LB](#disabling-the-service-lb)
 - [Nodes Without a Hostname](#nodes-without-a-hostname)
 
-# CoreDNS
+## CoreDNS
 
 CoreDNS is deployed on start of the agent. To disable, run each server with the `--disable coredns` option.
 
 If you don't install CoreDNS, you will need to install a cluster DNS provider yourself.
 
-# Traefik Ingress Controller
+## Traefik Ingress Controller
 
 [Traefik](https://traefik.io/) is a modern HTTP reverse proxy and load balancer made to deploy microservices with ease. It simplifies networking complexity while designing, deploying, and running applications.
 
@@ -40,7 +40,7 @@ If Traefik is not disabled K3s versions 1.20 and earlier will install Traefik v1
 
 To migrate from an older Traefik v1 instance please refer to the [Traefik documentation](https://doc.traefik.io/traefik/migration/v1-to-v2/) and [migration tool](https://github.com/traefik/traefik-migration-tool).
 
-# Service Load Balancer
+## Service Load Balancer
 
 Any service load balancer (LB) can be leveraged in your Kubernetes cluster. K3s provides a load balancer known as [Klipper Load Balancer](https://github.com/k3s-io/klipper-lb) that uses available host ports.
 
@@ -82,6 +82,6 @@ To disable the embedded LB, run the server with the `--disable servicelb` option
 
 This is necessary if you wish to run a different LB, such as MetalLB.
 
-# Nodes Without a Hostname
+## Nodes Without a Hostname
 
 Some cloud providers, such as Linode, will create machines with "localhost" as the hostname and others may not have a hostname set at all. This can cause problems with domain name resolution. You can run K3s with the `--node-name` flag or `K3S_NODE_NAME` environment variable and this will pass the node name to resolve this issue.
diff --git a/docs/reference/resource-profiling.md b/docs/reference/resource-profiling.md
@@ -29,14 +29,14 @@ The results are summarized as follows:
   - [Primary Resource Utilization Drivers](#primary-resource-utilization-drivers)
   - [Preventing Agents and Workloads from Interfering with the Cluster Datastore](#preventing-agents-and-workloads-from-interfering-with-the-cluster-datastore)
 
-# Scope of Resource Testing
+## Scope of Resource Testing
 
 The resource tests were intended to address the following problem statements:
 
 - On a single-node cluster, determine the legitimate minimum amount of CPU, memory, and IOPs that should be set aside to run the entire K3s stack server stack, assuming that a real workload will be deployed on the cluster.
 - On an agent (worker) node, determine the legitimate minimum amount of CPU, memory, and IOPs that should be set aside for the Kubernetes and K3s control plane components (the kubelet and k3s agent).
 
-# Components Included for Baseline Measurements
+## Components Included for Baseline Measurements
 
 The tested components are:
 
@@ -48,7 +48,7 @@ These are baseline figures for a stable system using only K3s packaged component
 
 Resource figures including IOPS are for the Kubernetes datastore and control plane only, and do not include overhead for system-level management agents or logging, container image management, or any workload-specific requirements. 
 
-# Methodology
+## Methodology
 
 A standalone instance of Prometheus v2.21.0 was used to collect host CPU, memory, and disk IO statistics using `prometheus-node-exporter` installed via apt.
 
@@ -58,7 +58,7 @@ Additional detailed K3s memory utilization data was collected from the `process_
 
 Utilization figures were based on 95th percentile readings from steady state operation on nodes running the described workloads.
 
-# Environment
+## Environment
 
 OS: Ubuntu 20.04 x86_64, aarch64
 
@@ -67,7 +67,7 @@ Hardware:
 - AWS c5d.xlarge - 4 core, 8 GB RAM, NVME SSD
 - Raspberry Pi 4 Model B - 4 core, 8 GB RAM, Class 10 SDHC
 
-# Baseline Resource Requirements
+## Baseline Resource Requirements
 
 This section captures the results of tests to determine minimum resource requirements for the K3s agent, the K3s server with a workload, and the K3s server with one agent.
 
@@ -118,7 +118,7 @@ The CPU requirements are:
 
 256 M of RAM is required.
 
-# Analysis
+## Analysis
 
 This section captures what has the biggest impact on K3s server and agent utilization, and how the cluster datastore can be protected from interference from agents and workloads.