Fix Hugo relref references to work in md (#100)

This PR fixes the "ref" and "relref" links in the documentation so that they work in Markdown and thus Github. This will mean the links will not work in the Hugo documentation. We need to figure out a way to get the links working in both but they really should work in Github. The links are now all absolute links in order to pass linkspector and to work in md. The linkspector tool fails on any link with a '#' in it, that is a link to a tag in any document. The change to the .linkspector file is to remove the '#' character and any following text, thus allowing those links to pass linkspector.
nephio-project · Feb 2, 2024 · 994ff89 · 994ff89
1 parent 8d8ed82
commit 994ff89
Show file tree

Hide file tree

Showing 21 changed files with 66 additions and 46 deletions.
diff --git a/.linkspector.yml b/.linkspector.yml
@@ -10,4 +10,6 @@ aliveStatusCodes:
 ignorePatterns:
   - pattern: "^http://localhost.*$"
   - pattern: "^http://HOSTNAME:PORT.*$"
-
+replacementPatterns:
+  - pattern: ".md#.*$"
+    replacement: ".md"
diff --git a/content/en/docs/abbreviations.md b/content/en/docs/abbreviations.md
@@ -5,7 +5,7 @@ weight: 3
 ---
 
 This page gives brief explanations of abbreviations used in the Nephio project. See also the
-[Nephio Glossary]({{< ref "glossary.md" >}}) for more detailed descriptions of Nephio related terms.
+[Nephio Glossary](/content/en/docs/glossary.md) for more detailed descriptions of Nephio related terms.
 
 ## Nephio related abbreviations
 * NF: Network Function

diff --git a/content/en/docs/guides/contributor-guides/_index.md b/content/en/docs/guides/contributor-guides/_index.md
@@ -11,5 +11,5 @@ This developer guide is for for people who want to write code for the Nephio pro
 extension of the [Kubernetes Developer Guides](https://github.com/kubernetes/community/tree/master/contributors/devel#the-process-of-developing-and-contributing-code-to-the-kubernetes-project)
 and therefore covers topics that are specific to Nephio development.
 
-* How to set up a [Minimal Development Environment]({{< relref "minimal-environment.md" >}}) defines common terminology
+* How to set up a [Minimal Development Environment](/content/en/docs/guides/contributor-guides/minimal-environment.md) defines common terminology
   used in the Nephio project.
diff --git a/content/en/docs/guides/contributor-guides/doc-faq.md b/content/en/docs/guides/contributor-guides/doc-faq.md
@@ -0,0 +1,16 @@
+---
+title: Nephio Documentation System FAQ
+description: >
+  Frequently Asked Questions on the Nephio Documentation system
+weight: 5
+---
+
+#   Frequently Asked Questions on the Nephio Documentation system
+
+1. How do I check the documentation links on the documentation before I check in my changes?
+
+    Install and run *linkspector*
+    ```
+    npm install -g @umbrelladocs/linkspector
+    linkinspector check -c .linkspector.yml
+    ```
diff --git a/content/en/docs/guides/install-guides/_index.md b/content/en/docs/guides/install-guides/_index.md
@@ -173,7 +173,7 @@ ssh <user>@<vm-address>
 
 ## Next Steps
 
-* Step through the [Free5GC]({{< relref "exercise-1-free5gc.md" >}}) and [OAI]({{< relref "exercise-2-oai.md" >}}) exercises
-* Learn more about the [Nephio demo sandbox]({{< relref "explore-sandbox.md" >}})
-* Dig into the [user guide]({{< ref "user-guides#nephio-r1-user-guide" >}})
-* Create a [Bring-Your-Own-Cluster]({{< relref "install-on-byoc.md" >}}) Nephio Installation
+* Step through the [Free5GC](/content/en/docs/guides/user-guides/exercise-1-free5gc.md) and [OAI](/content/en/docs/guides/user-guides/exercise-2-oai.md) exercises
+* Learn more about the [Nephio demo sandbox](/content/en/docs/guides/install-guides/explore-sandbox.md)
+* Dig into the [user guide](/content/en/docs/guides/user-guides/_index.md)
+* Create a [Bring-Your-Own-Cluster](/content/en/docs/guides/install-guides/install-on-byoc.md) Nephio Installation
diff --git a/content/en/docs/guides/install-guides/explore-nephio-free5gc.md b/content/en/docs/guides/install-guides/explore-nephio-free5gc.md
@@ -5,9 +5,9 @@ description: >
 weight: 6
 ---
 
-Concepts as [Operator]({{< ref "/docs/glossary.md#operator" >}}) and
-[Controller]({{< ref "/docs/glossary.md#controller" >}}) and
-[CR]({{< ref "/docs/glossary.md#custom-resource" >}}) have already been explained here.
+Concepts as [Operator](/content/en/docs/glossary.md#operator) and
+[Controller](/content/en/docs/glossary.md#controller) and
+[CR](/content/en/docs/glossary.md#custom-resource) have already been explained here.
 
 # Deploy the operator to the cluster
 

diff --git a/content/en/docs/guides/install-guides/explore-sandbox.md b/content/en/docs/guides/install-guides/explore-sandbox.md
@@ -6,7 +6,7 @@ weight: 5
 ---
 
 
-You have installed the Nephio single VM [using the installation instructions]({{< relref "install-on-single-vm.md" >}}).
+You have installed the Nephio single VM [using the installation instructions](/content/en/docs/guides/install-guides/install-on-single-vm.md).
 The installation has done a good job of installing a complex software stack without any fuss. Let's take a look around.
 
 ![Software Installed by the Nephio Sandbox Installation](/images/install-guides/ManagementCluster.png)

diff --git a/content/en/docs/guides/install-guides/install-on-byoc.md b/content/en/docs/guides/install-guides/install-on-byoc.md
@@ -67,9 +67,9 @@ options, if you wish to assemble your own set of components.
 
 | Environment | Description                                                |
 | ----------- | ---------------------------------------------------------- |
-| [Single VM]({{< relref "install-on-single-vm.md" >}}) | The single VM demo environment, set up "the hard way" - without using the included provisioning script. This creates a complete Nephio-in-a-VM, just like the R1 demo environment. These instructions cover both Ubuntu and Fedora. |
-| [Google Cloud Platform]({{< relref "install-on-gcp.md" >}}) | Nephio running in GCP. A GKE cluster is used as the management cluster, with Anthos Config Controller for GCP infrastructure provisioning, Gitea as the Git provider, and Web UI authentication and authorization via Google OAuth 2.0 |
-| [OpenShift]({{< relref "install-on-openshift.md" >}}) | Nephio running in OpenShift, with Cluster API as the cluster provisioner, Gitea as the Git provider and Web UI authentication backed by Open Shift OIDC. |
+| [Single VM](/content/en/docs/guides/install-guides/install-on-single-vm.md) | The single VM demo environment, set up "the hard way" - without using the included provisioning script. This creates a complete Nephio-in-a-VM, just like the R1 demo environment. These instructions cover both Ubuntu and Fedora. |
+| [Google Cloud Platform](/content/en/docs/guides/install-guides/install-on-gcp.md) | Nephio running in GCP. A GKE cluster is used as the management cluster, with Anthos Config Controller for GCP infrastructure provisioning, Gitea as the Git provider, and Web UI authentication and authorization via Google OAuth 2.0 |
+| [OpenShift](/content/en/docs/guides/install-guides/install-on-openshift.md) | Nephio running in OpenShift, with Cluster API as the cluster provisioner, Gitea as the Git provider and Web UI authentication backed by Open Shift OIDC. |
 
 ## A La Carte Installation
 
@@ -146,8 +146,8 @@ development it must not be exposed on the internet (for example, via a
 LoadBalancer service, Ingress, or Route).
 
 The WebUI currently supports the following options:
-- [Google OAuth or OIDC]({{< relref "webui-auth-gcp.md" >}})
-- [OIDC with Okta]({{< relref "webui-auth-okta.md" >}})
+- [Google OAuth or OIDC](/content/en/docs/guides/install-guides/webui-auth-gcp.md)
+- [OIDC with Okta](/content/en/docs/guides/install-guides/webui-auth-okta.md)
 
 ### Nephio Stock Repositories
 

diff --git a/content/en/docs/guides/install-guides/install-on-gce.md b/content/en/docs/guides/install-guides/install-on-gce.md
@@ -174,7 +174,7 @@ ssh <user>@<vm-address>
 ## Next Steps
 
 * Step through the exercises
-  * [Free5GC Testbed Deployment and E2E testing with UERANSIM]({{< relref "/docs/guides/user-guides/exercise-1-free5gc.md" >}})
-  * [OAI Core and RAN Testbed Deployment and E2E testing]({{< relref "/docs/guides/user-guides/exercise-2-oai.md" >}})
-* Learn more about the [Nephio demo sandbox]({{< relref "explore-sandbox.md" >}})
-* Dig into the [user guide]({{< relref "/docs/guides/user-guides/_index.md" >}})
+  * [Free5GC Testbed Deployment and E2E testing with UERANSIM](/content/en/docs/guides/user-guides/exercise-1-free5gc.md)
+  * [OAI Core and RAN Testbed Deployment and E2E testing](/content/en/docs/guides/user-guides/exercise-2-oai.md)
+* Learn more about the [Nephio demo sandbox](/content/en/docs/guides/install-guides/explore-sandbox.md)
+* Dig into the [user guide](/content/en/docs/guides/user-guides/_index.md)
diff --git a/content/en/docs/guides/install-guides/install-on-gcp.md b/content/en/docs/guides/install-guides/install-on-gcp.md
@@ -1022,9 +1022,9 @@ git commit -m "Initial checking of nephio-mgmt"
 **Prior to deploying the package, we need to manually setup the secret for the
 WebUI.**
 
-See [Google OAuth 2.0 or OIDC]({{< relref "webui-auth-gcp.md" >}}) for details on how to
-set up OAuth. In particular you need to [create the client ID]({{< relref "webui-auth-gcp.md#creating-an-oauth-20-client-id" >}})
-and the [secret]({{< relref "webui-auth-gcp.md#create-the-secret-in-the-cluster" >}})
+See [Google OAuth 2.0 or OIDC](/content/en/docs/guides/install-guides/webui-auth-gcp.md) for details on how to
+set up OAuth. In particular you need to [create the client ID](/content/en/docs/guides/install-guides/webui-auth-gcp.md#creating-an-oauth-20-client-id)
+and the [secret](/content/en/docs/guides/install-guides/webui-auth-gcp.md#create-the-secret-in-the-cluster)
 manually.
 
 The `nephio-webui` subpackage in `nephio-mgmt` is already set up for
@@ -1384,5 +1384,6 @@ Note that the exercises using free5gc rely on Multus and on the gtp5g kernel mod
 GKE nodes. Therefore, the free5gc workloads cannot be run on this installation. You will need to alter the exercises to\
 use workloads that do not rely on that functionality in order to experiment with Nephio features.
 
-* Step through the [Free5GC]({{< relref "exercise-1-free5gc.md" >}}) and [OAI]({{< relref "exercise-2-oai.md" >}}) exercises
-* Dig into the [user guide]({{< relref "/docs/guides/user-guides/_index.md" >}})
+* Step through the [Free5GC](/content/en/docs/guides/user-guides/exercise-1-free5gc.md) and
+[OAI](/content/en/docs/guides/user-guides/exercise-2-oai.md) exercises
+* Dig into the [user guide](/content/en/docs/guides/user-guides/_index.md)
diff --git a/content/en/docs/guides/install-guides/install-on-openshift.md b/content/en/docs/guides/install-guides/install-on-openshift.md
@@ -70,7 +70,8 @@ Application:
 oc apply -f https://raw.githubusercontent.com/openshift-telco/blueprints-nephio-openshift/v1.0.1/nephio-mgnt/app-of-apps.yaml
 ```
 
-This will take care of applying the [common dependencies]({{< relref "common-dependencies.md" >}}) and the [common components]({{< relref "common-components.md" >}})
+This will take care of applying the [common dependencies](/content/en/docs/guides/install-guides/common-dependencies.md)
+and the [common components](/content/en/docs/guides/install-guides/common-components.md)
 
 ### Access the Nephio
 

diff --git a/content/en/docs/guides/install-guides/install-on-single-vm.md b/content/en/docs/guides/install-guides/install-on-single-vm.md
@@ -65,12 +65,12 @@ kpt live apply gitea --reconcile-timeout 15m --output=table
 
 There are a few dependencies that are common across most installations, and do not require any installation-specific
 setup. You should install these next, as described in the
-[common dependencies documentation]({{< relref "common-dependencies.md" >}}).
+[common dependencies documentation](/content/en/docs/guides/install-guides/common-dependencies.md).
 
 ## Common Components
 
 With the necessary dependencies now installed, you can now install the essential Nephio components. This is documented
-in the [common components documentation]({{< relref "common-components.md" >}}).
+in the [common components documentation](/content/en/docs/guides/install-guides/common-components.md).
 
 ## Provisioning Cluster API
 

diff --git a/content/en/docs/guides/install-guides/webui.md b/content/en/docs/guides/install-guides/webui.md
@@ -54,8 +54,8 @@ service).
 Configuring authentication for the WebUI is very specific to the particular cluster environment. Guides for different
 environments are below:
 
-- [Google OAuth or OIDC]({{< relref "/webui-auth-gcp.md" >}})
-- [OIDC with Okta]({{< relref "/webui-auth-okta.md" >}})
+- [Google OAuth or OIDC](/content/en/docs/guides/install-guides/webui-auth-gcp.md)
+- [OIDC with Okta](/content/en/docs/guides/install-guides/webui-auth-okta.md)
 
 Once that configuration is updated, you can proceed with the installation (note, this uses `inventory-policy=adopt`,
 since in the previous steps we may have created the namespace already).

diff --git a/content/en/docs/guides/user-guides/_index.md b/content/en/docs/guides/user-guides/_index.md
@@ -330,10 +330,10 @@ The diagram below depicts deployment at the high level.
 
 On the demo VM, the `test-infra/e2e/provision/hacks` directory contains some
 workaround scripts. Also, please see the Release Notes
-[known issues]({{< relref "../../release-notes/r1#known-issues-and-workarounds">}}).
+[known issues](/content/en/docs/release-notes/R2.md#known-issues-and-workarounds).
 
 ## Next Steps
 
-* Learn more about the Nephio [controllers]({{< relref "controllers.md" >}})
-* Learn more about how packages are [transformed]({{< relref "../install-guides/package-transformations.md" >}})
-* Learn more about [deploying helm charts]({{< relref "../user-guides/helm/#helm-integration-in-nephio" >}}) in Nephio
+* Learn more about the Nephio [controllers](/content/en/docs/guides/user-guides/controllers.md)
+* Learn more about how packages are [transformed](/content/en/docs/guides/install-guides/package-transformations.md)
+* Learn more about [deploying helm charts](/content/en/docs/guides/user-guides/helm/_index.md) in Nephio
diff --git a/content/en/docs/guides/user-guides/exercise-1-free5gc.md b/content/en/docs/guides/user-guides/exercise-1-free5gc.md
@@ -20,7 +20,7 @@ weight: 2
 
 ## Introduction
 
-Be sure you have followed the [installation guide]({{< ref "docs/guides/install-guides ">}})
+Be sure you have followed the [installation guide](/content/en/docs/guides/install-guides/_index.md)
 before trying these exercises.
 
 These exercises will take you from a system with only the Nephio Management cluster setup to a deployment with:
@@ -995,7 +995,7 @@ commits to see how Porch interacts with packages stored in Git repositories.
 ![Commits in Gitea made by porch](/images/user-guides/gitea-porch.png)
 
 After the package is approved, the results can be observed in Nephio Web UI. Head over to http://localhost:7007/config-as-data
-([port forwarding]({{< ref "docs/guides/install-guides/#access-to-the-user-interfaces" >}}) must be running).
+([port forwarding](/content/en/docs/guides/install-guides/_index.md#access-to-the-user-interfaces) must be running).
 
 ![Deployments in Nephio UI](/images/user-guides/UPF-Capacity.png)
 

diff --git a/content/en/docs/guides/user-guides/exercise-2-oai.md b/content/en/docs/guides/user-guides/exercise-2-oai.md
@@ -19,7 +19,7 @@ weight: 2
 
 ## Introduction
 
-Be sure you have followed the [installation guide]({{< ref "docs/guides/install-guides ">}})
+Be sure you have followed the [installation guide](/content/en/docs/guides/install-guides/_index.md)
 before trying these exercises.
 
 These exercises will take you from a system with only the Nephio Management cluster setup to a deployment with:

diff --git a/content/en/docs/guides/user-guides/helm/_index.md b/content/en/docs/guides/user-guides/helm/_index.md
@@ -16,6 +16,6 @@ for deploying on Kubernetes, legacy helm support will be required for a number o
 
 ### Deployment options
 
-* [Using Flux CD]({{< ref "flux-helm.md" >}})
+* [Using Flux CD](/content/en/docs/guides/user-guides/helm/flux-helm.md)
 * [Operator SDK](https://sdk.operatorframework.io/docs/building-operators/helm/)
 
diff --git a/content/en/docs/guides/user-guides/helm/flux-helm.md b/content/en/docs/guides/user-guides/helm/flux-helm.md
@@ -16,11 +16,11 @@ Then, we can utilize the flux Custom Resources defined in another test kpt packa
 
 ##  Prerequisites:
 
-* [Nephio R1 sandbox]({{< ref "/docs/guides/install-guides/" >}}): Set up the Nephio sandbox environment.
-* [Access to the Nephio Web UI]({{< ref "/docs/guides/install-guides/#access-to-the-user-interfaces" >}})
-* [Nephio R1 sandbox workload clusters]({{< ref "/docs/guides/user-guides/exercise-1-free5gc.md" >}}):
+* [Nephio R1 sandbox]/content/en/docs/guides/install-guides/install-guides/_index.md): Set up the Nephio sandbox environment.
+* [Access to the Nephio Web UI](/content/en/docs/guides/install-guides/_index.md#access-to-the-user-interfaces)
+* [Nephio R1 sandbox workload clusters](/content/en/docs/guides/user-guides/exercise-1-free5gc.md):
   Create/Deploy the predefined set of workload clusters by completing the Free5GC Core quick start exercises up to and including
-  [Step 3]({{< ref "/docs/guides/user-guides/exercise-1-free5gc.md#step-3-deploy-two-edge-clusters" >}}).
+  [Step 3](/content/en/docs/guides/user-guides/exercise-1-free5gc.md#step-3-deploy-two-edge-clusters).
 
 ### Deploying the flux-helm-controllers pkg
 

diff --git a/content/en/docs/release-notes/R1.md b/content/en/docs/release-notes/R1.md
@@ -7,7 +7,7 @@ weight: 1
 
 ## Prerequisites
 
-Please refer to the [Install Guide]({{< ref "/docs/guides/install-guides" >}})
+Please refer to the [Install Guide](/content/en/docs/guides/install-guides/_index.md)
 for the prerequisites on supported environments.
 
 ## Support Matrix

diff --git a/content/en/docs/release-notes/R2.md b/content/en/docs/release-notes/R2.md
@@ -7,7 +7,7 @@ weight: 1
 
 ## Prerequisites
 
-Please refer to the [Install Guide]({{< ref "docs/guides/install-guides/install-on-byoc.md#prerequisites" >}})
+Please refer to the [Install Guide](/content/en/docs/guides/install-guides/install-on-byoc.md#prerequisites)
 for the prerequisites on supported environments.
 
 ## Support Matrix

diff --git a/resources.md b/resources.md
@@ -46,7 +46,7 @@ More tutorials are under discussion in
 * [SIG Release Meeting playlist](https://www.youtube.com/playlist?list=PLiW9_IXAWtks9Ys4Zs6wPRNEuQYAnWcg1)
 
 ## Other Resources
-* The [Glossary](content/en/docs/glossary.md) defines common terminology used in the Nephio
+* The [Glossary](/content/en/docs/glossary.md) defines common terminology used in the Nephio
   project.
 * The [Nephio Learning Resources page](learning.md) lists some learning resources that are useful for the Nephio community
-* The [Abbreviation Decoder page](content/en/docs/abbreviations.md) explains common abbreviations used in the project.
+* The [Abbreviation Decoder page](/content/en/docs/abbreviations.md) explains common abbreviations used in the project.