Use GitHub Markdown blockquote tags instead of Alert

Use tags like `[!NOTE]`, `[!TIP]`, `[!WARNING]`, and `[!IMPORTANT]` instead of importing and using an `<Alert>` tag. Signed-off-by: Thomas Hallgren <thomas@tada.se>
telepresenceio · Sep 7, 2024 · 5fedfaa · 5fedfaa
1 parent fa87a58
commit 5fedfaa
Show file tree

Hide file tree

Showing 13 changed files with 176 additions and 117 deletions.
diff --git a/docs/v2.19/CONTRIBUTING.md b/docs/v2.19/CONTRIBUTING.md
@@ -0,0 +1,23 @@
+# Telepresence Documentation
+
+This folder contains the Telepresence documentation in a format suitable for a versioned folder in the
+telepresenceio/telepresence.io repository. The folder will show up in that repository when a new minor revision
+tag is created here.
+
+Assuming that a 2.20.0 release is pending, and that a release/v2.20.0 branch has been created, then:
+```console
+$ export TELEPRESENCE_VERSION=v2.20.0
+$ make prepare-release
+$ git push origin {,rpc/}v2.20.0 release/v2.20.0
+```
+
+will result in a `docs/v2.20` folder with this folder's contents in the telepresenceio/telepresence.io repository.
+
+Subsequent bugfix tags for the same minor tag, i.e.:
+```console
+$ export TELEPRESENCE_VERSION=v2.20.1
+$ make prepare-release
+$ git push origin {,rpc/}v2.20.1 release/v2.20.1
+```
+will not result in a new folder when it is pushed, but it will update the content of the `docs/v2.20` folder to
+reflect this folder's content for that tag.
diff --git a/docs/v2.19/README.md b/docs/v2.19/README.md
@@ -1,23 +1,39 @@
-# Telepresence Documentation
+# <img src=images/logo.png height=64px/> Telepresence Documentation
+raw markdown version, more bells and whistles at [telepresence.io](https://telepresence.io)
 
-This folder contains the Telepresence documentation in a format suitable for a versioned folder in the
-telepresenceio/telepresence.io repository. The folder will show up in that repository when a new minor revision
-tag is created here.
-
-Assuming that a 2.20.0 release is pending, and that a release/v2.20.0 branch has been created, then:
-```console
-$ export TELEPRESENCE_VERSION=v2.20.0
-$ make prepare-release
-$ git push origin {,rpc/}v2.20.0 release/v2.20.0
-```
-
-will result in a `docs/v2.20` folder with this folder's contents in the telepresenceio/telepresence.io repository.
-
-Subsequent bugfix tags for the same minor tag, i.e.:
-```console
-$ export TELEPRESENCE_VERSION=v2.20.1
-$ make prepare-release
-$ git push origin {,rpc/}v2.20.1 release/v2.20.1
-```
-will not result in a new folder when it is pushed, but it will update the content of the `docs/v2.20` folder to
-reflect this folder's content for that tag.
+- [Quick start](quick-start.md)
+- Install Telepresence
+  - [Install Client](install/client.md)
+  - [Upgrade Client](install/upgrade.md)
+  - [Install Traffic Manager](install/manager.md)
+  - [Cloud Provider Prerequisites](install/cloud.md)
+- Core concepts
+  - [The developer experience and the inner dev loop](concepts/devloop.md)
+  - [Making the remote local: Faster feedback, collaboration and debugging](concepts/faster.md)
+  - [Intercepts](concepts/intercepts.md)
+- How do I...
+  - [Intercept a service in your own environment](howtos/intercepts.md)
+  - [Proxy outbound traffic to my cluster](howtos/outbound.md)
+  - [Work with large clusters](howtos/large-clusters.md)
+  - [Host a cluster in a local VM](howtos/cluster-in-vm.md)
+- Technical reference
+  - [Architecture](reference/architecture.md)
+  - [Client reference](reference/client.md)
+  - [Laptop-side configuration](reference/config.md)
+  - [Cluster-side configuration](reference/cluster-config.md)
+  - [Using Docker for intercepts](reference/docker-run.md)
+  - [Running Telepresence in a Docker container](reference/inside-container.md)
+  - [Environment variables](reference/environment.md)
+  - [Intercepts](reference/intercepts.md)
+    - [Configure intercept using CLI](reference/intercepts/cli.md)
+  - [Volume mounts](reference/volume.md)
+  - [DNS resolution](reference/dns.md)
+  - [RBAC](reference/rbac.md)
+  - [Telepresence and VPNs](reference/vpn.md)
+  - [Networking through Virtual Network Interface](reference/tun-device.md)
+  - [Connection Routing](reference/routing.md)
+- [FAQs](faqs.md)
+- [Troubleshooting](troubleshooting.md)
+- [Community](community.md)
+- [Release Notes](release-notes.md)
+- [Licenses](licenses.md)
diff --git a/docs/v2.19/howtos/cluster-in-vm.md b/docs/v2.19/howtos/cluster-in-vm.md
@@ -6,7 +6,7 @@ description: "Use Telepresence to intercept services in a cluster running in a h
 # Network considerations for locally hosted clusters
 
 ## The problem
-Telepresence creates a Virtual Network Interface ([VIF](../reference/tun-device.md)) that maps the clusters subnets to the host machine when it connects. If you're running Kubernetes locally (e.g., k3s, Minikube, Docker for Desktop), you may encounter network problems because the devices in the host are also accessible from the cluster's nodes.
+Telepresence creates a Virtual Network Interface ([VIF](../reference/tun-device.md)) that maps the clusters subnets to the host machine when it connects. If you're running Kubernetes locally (e.g., Docker Desktop, Kind, Minikube, k3s), you may encounter network problems because the devices in the host are also accessible from the cluster's nodes.
 
 ### Example:
 A k3s cluster runs in a headless VirtualBox machine that uses a "host-only" network. This network will allow both host-to-guest and guest-to-host connections. In other words, the cluster will have access to the host's network and, while Telepresence is connected, also to its VIF. This means that from the cluster's perspective, there will now be more than one interface that maps the cluster's subnets; the ones already present in the cluster's nodes, and then the Telepresence VIF, mapping them again.
@@ -189,4 +189,3 @@ spec:
     protocol: TCP
   type: LoadBalancer
 ```
-
diff --git a/docs/v2.19/howtos/intercepts.md b/docs/v2.19/howtos/intercepts.md
@@ -2,9 +2,6 @@
 description: "Start using Telepresence in your own environment. Follow these steps to intercept your service in your cluster."
 ---
 
-import Alert from '@material-ui/lab/Alert';
-import Platform from '@src/components/Platform';
-
 # Intercept a service in your own environment
 
 Telepresence enables you to create intercepts to a target Kubernetes workload. Once you have created and intercept, you can code and debug your associated service locally. 
@@ -20,7 +17,7 @@ This guide assumes you have a Kubernetes deployment and service accessible publi
 
 With Telepresence, you can create an intercept that intercepts all traffic going to a service in your cluster and route it to your local environment instead. 
 
-1. Connect to your cluster with `telepresence connect` and try to curl to the Kubernetes API server:
+1. Connect to your cluster with `telepresence connect` and try to curl to the Kubernetes API server. A 401 response code is expected and indicates that the service could be reached:
 
    ```console
    $ curl -ik https://kubernetes.default
@@ -30,10 +27,6 @@ With Telepresence, you can create an intercept that intercepts all traffic going
    ...
    ```
 
-   <Alert>
-    The 401 response is expected.
-   </Alert>
-
    You now have access to your remote Kubernetes API server as if you were on the same network. You can now use any local tools to connect to any service in the cluster.
 
 2. Enter `telepresence list` and make sure the service you want to intercept is listed. For example:
@@ -93,8 +86,5 @@ You can now:
 - Query services only exposed in your cluster's network.
 - Set breakpoints in your IDE to investigate bugs.
 
-   <Alert severity="info">
-
-    **Didn't work?** Make sure the port you're listening on matches the one you specified when you created your intercept.
-
-   </Alert>
+> [!TIP]
+> **Didn't work?** Make sure the port you're listening on matches the one you specified when you created your intercept.
diff --git a/docs/v2.19/howtos/outbound.md b/docs/v2.19/howtos/outbound.md
@@ -2,8 +2,6 @@
 description: "Telepresence can connect to your Kubernetes cluster, letting you access cluster services as if your laptop was another pod in the cluster."
 ---
 
-import Alert from '@material-ui/lab/Alert';
-
 # Proxy outbound traffic to my cluster
 
 Telepresence offers other options for proxying traffic between your laptop and the cluster. This section discribes how to proxy outbound traffic and control outbound connectivity to your cluster.

diff --git a/docs/v2.19/quick-start.md b/docs/v2.19/quick-start.md
@@ -2,9 +2,6 @@
 description: "Start using Telepresence in your own environment. Follow these steps to intercept your service in your cluster."
 ---
 
-import Alert from '@material-ui/lab/Alert';
-import Platform from '@src/components/Platform';
-
 # Telepresence Quickstart
 
 Telepresence is an open source tool that enables you to set up remote development environments for Kubernetes where you can still use all of your favorite local tools like IDEs, debuggers, and profilers.
@@ -23,7 +20,7 @@ telepresence client on your workstation, and the traffic manager in your cluster
 
 With Telepresence, you can create [intercepts](concepts/intercepts.md) that intercept all traffic going to a service in your remote cluster and route it to your local environment instead.
 
-1. Connect to your cluster with `telepresence connect` and connect to the Kubernetes API server:
+1. Connect to your cluster with `telepresence connect` and connect to the Kubernetes API server. A 401 response code is expected and indicates that the service could be reached:
 
    ```
    $ telepresence connect
@@ -40,12 +37,9 @@ With Telepresence, you can create [intercepts](concepts/intercepts.md) that inte
 
    ```
 
-   <Alert>
-    The 401 response is expected when you first connect.
-   </Alert>
-
    You now have access to your remote Kubernetes API server as if you were on the same network. You can now use any local tools to connect to any service in the cluster.
 
+
 2. Enter `telepresence list` and make sure the service you want to intercept is listed. For example:
 
    ```
@@ -104,19 +98,14 @@ The following are some examples of how to pass the environment variables to your
 
 Now, with Telepresence, you can:
 
-- <div>
-   Make changes on the fly and see them reflected when interacting with your remote Kubernetes environment, this is just like hot reloading, but it works across both local and remote environments.
-  </div>
-- <div>Query services and microservice APIs that are only accessible in your remote cluster's network.</div>
-- <div>Set breakpoints in your IDE and re-route remote traffic to your local machine to investigate bugs with realistic user traffic and API calls.</div>
-
-   <Alert severity="info">
-
-  **Didn't work?** Make sure the port you're listening on matches the one you specified when you created your intercept.
+- Make changes on the fly and see them reflected when interacting with your remote Kubernetes environment, this is just like hot reloading, but it works across both local and remote environments.
+- Query services and microservice APIs that are only accessible in your remote cluster's network.
+- Set breakpoints in your IDE and re-route remote traffic to your local machine to investigate bugs with realistic user traffic and API calls.
 
-   </Alert>
+> [!TIP]
+> **Didn't work?** Make sure the port you're listening on matches the one you specified when you created your intercept.
 
 ## What’s Next?
 - [Learn about the Telepresence architecture.](reference/architecture)
 
-<img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=d842651a-2e4d-465a-98e1-4808722c01ab" />
+<img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=d842651a-2e4d-465a-98e1-4808722c01ab" />
diff --git a/docs/v2.19/reference/cluster-config.md b/docs/v2.19/reference/cluster-config.md
@@ -1,5 +1,3 @@
-import Alert from '@material-ui/lab/Alert';
-
 # Cluster-side configuration
 
 For the most part, Telepresence doesn't require any special
@@ -107,14 +105,12 @@ An annotation `telepresence.getambassador.io/inject-ignore-volume-mounts` can be
 
 ### Note on Numeric Ports
 
-If the <code>targetPort</code> of your intercepted service is pointing at a port number, in addition to
-injecting the Traffic Agent sidecar, Telepresence will also inject an <code>initContainer</code> that will
+If the `targetPort` of your intercepted service is pointing at a port number, in addition to
+injecting the Traffic Agent sidecar, Telepresence will also inject an `initContainer` that will
 reconfigure the pod's firewall rules to redirect traffic to the Traffic Agent.
 
-<Alert severity="info">
-Note that this <code>initContainer</code> requires `NET_ADMIN` capabilities.
-If your cluster administrator has disabled them, you will be unable to use numeric ports with the agent injector.
-</Alert>
+> [!IMPORTANT]
+> Note that this `initContainer` requires `NET_ADMIN` capabilities. If your cluster administrator has disabled them, you will be unable to use numeric ports with the agent injector.
 
 For example, the following service is using a numeric port, so Telepresence would inject an initContainer into it:
 ```yaml

diff --git a/docs/v2.19/reference/intercepts/cli.md b/docs/v2.19/reference/intercepts/cli.md
@@ -1,5 +1,3 @@
-import Alert from '@material-ui/lab/Alert';
-
 # Configuring intercept using CLI
 
 ## Specifying a namespace for an intercept
@@ -230,20 +228,9 @@ intercepted
     Intercepting      : all TCP connections
 ```
 
-<Alert severity="info">
-This utilizes an <code>initContainer</code> that requires `NET_ADMIN` capabilities.
-If your cluster administrator has disabled them, you will be unable to use numeric ports with the agent injector.
-</Alert>
-
-<Alert severity="info">
-This requires the Traffic Agent to run as GID <code>7777</code>. By default, this is disabled on openshift clusters.
-To enable running as GID <code>7777</code> on a specific openshift namespace, run:
-<code>oc adm policy add-scc-to-group anyuid system:serviceaccounts:$NAMESPACE</code>
-</Alert>
-
-<Alert severity="info">
-Intercepting headless services without a selector is not supported.
-</Alert>
+> [!IMPORTANT]
+> This utilizes an `initContainer` that requires `NET_ADMIN` capabilities.
+> If your cluster administrator has disabled them, you will be unable to use numeric ports with the agent injector.
 
 ## Specifying the intercept traffic target
 
@@ -286,12 +273,5 @@ $ telepresence intercept my-service --port 8080 --replace
    Intercepting           : all TCP connections
 ```
 
-<Alert severity="info">
-Using the --replace flag implies a global intercept. This is to prevent situations
-where multiple personal intercepts are consuming from the same message queue, which
-would be the same as allowing the application to do so while an intercept is running.
-</Alert>
-
-<Alert severity="info">
-Sidecars will not be stopped. Only the container serving the intrcepted port will be removed from the pod.
-</Alert>
+> [!NOTE]
+> Sidecars will not be stopped. Only the container serving the intercepted port will be removed from the pod.
diff --git a/docs/v2.19/reference/intercepts/index.md b/docs/v2.19/reference/intercepts/index.md
@@ -1,5 +1,3 @@
-import Alert from '@material-ui/lab/Alert';
-
 # Intercepts
 
 When intercepting a service, the Telepresence Traffic Manager ensures
@@ -20,9 +18,5 @@ Kubernetes has various
 Currently, Telepresence supports intercepting (installing a
 traffic-agent on) `Deployments`, `ReplicaSets`, and `StatefulSets`.
 
-<Alert severity="info">
-
-While many of our examples use Deployments, they would also work on
-ReplicaSets and StatefulSets
-
-</Alert>
+> [!NOTE]
+> While many of our examples use Deployments, they would also work on ReplicaSets and StatefulSets
diff --git a/docs/v2.19/reference/rbac.md b/docs/v2.19/reference/rbac.md
@@ -1,5 +1,3 @@
-import Alert from '@material-ui/lab/Alert';
-
 # Telepresence RBAC
 The intention of this document is to provide a template for securing and limiting the permissions of Telepresence.
 This documentation covers the full extent of permissions necessary to administrate Telepresence components in a cluster.
@@ -116,7 +114,8 @@ By using `telepresence connect`, Telepresence will use your kubeconfig to create
 
 To allow users to make intercepts across all namespaces, but with more limited `kubectl` permissions, the following `ServiceAccount`, `ClusterRole`, and `ClusterRoleBinding` will allow full `telepresence intercept` functionality.
 
-<Alert severity="warning">The following RBAC configurations assume that there is already a Traffic Manager deployment set up by a Cluster Administrator</Alert>
+> [!WARNING]
+> The following RBAC configurations assume that there is already a Traffic Manager deployment set up by a Cluster Administrator
 
 ```yaml
 ---
@@ -195,7 +194,8 @@ roleRef:
 
 RBAC for multi-tenant scenarios where multiple dev teams are sharing a single cluster where users are constrained to a specific namespace(s).
 
-<Alert severity="warning">The following RBAC configurations assume that there is already a Traffic Manager deployment set up by a Cluster Administrator</Alert>
+> [!WARNING]
+> The following RBAC configurations assume that there is already a Traffic Manager deployment set up by a Cluster Administrator
 
 For each accessible namespace
 ```yaml

diff --git a/docs/v2.19/reference/vpn.md b/docs/v2.19/reference/vpn.md
@@ -1,21 +1,10 @@
-import Alert from '@material-ui/lab/Alert';
-
-<!-- TODO: We should figure out a way to make this site-wide without affecting the release notes page -->
-<div class="container">
-
 # Telepresence and VPNs
 
 It is often important to set up Kubernetes API server endpoints to be only accessible via a VPN.
 In setups like these, users need to connect first to their VPN, and then use Telepresence to connect
 to their cluster. As Telepresence uses many of the same underlying technologies that VPNs use,
 the two can sometimes conflict. This page will help you identify and resolve such VPN conflicts.
 
-
-<Alert severity="warning">
-The <strong>test-vpn</strong> command, which was once part of Telepresence, became obsolete in <strong>2.14</strong> due to a change in functionality and was subsequently removed.
-</Alert>
-
-
 ## VPN Configuration
 
 Let's begin by reviewing what a VPN does and imagining a sample configuration that might come
@@ -150,5 +139,3 @@ The cluster's subnets are now hidden behind a virtual subnet, and the resulting
 ### Using docker
 
 Use `telepresence connect --docker` to make the Telepresence daemon containerized, which means that it has its own network configuration and therefore no conflict with a VPN. Read more about docker [here](docker-run.md).
-
-</div>
diff --git a/package.json b/package.json
@@ -38,6 +38,7 @@
     "react-intersection-observer": "^8.32.0",
     "react-markdown": "^9.0.1",
     "react-scroll": "^1.8.2",
+    "rehype-github-alerts": "^3.0.0",
     "slick-carousel": "^1.8.1",
     "typescript": "^4.4.4",
     "typescript-plugin-css-modules": "^5.1.0",
@@ -58,5 +59,6 @@
   "repository": {
     "type": "git",
     "url": "https://github.com/telepresenceio/telepresence.io"
-  }
+  },
+  "version": "0.0.0"
 }