[HOUSEKEEPING] Finding broken links in md files and fix them

guides/config-file.md

@@ -1,6 +1,6 @@
 # spk-config.yaml
 
-The [`spk-config.yaml`](./spk-config.yaml) consists of three main sections:
+The [`spk-config.yaml`](../spk-config.yaml) consists of three main sections:
 
 1. `introspection`
 2. `infra`
@@ -35,7 +35,7 @@ There are two options to create environment variables:
 A recommended approach is to have a `.env` file in your folder **(make sure it's
 gitignored!)** with all variables and their values.
 
-[Sample `.env`](./.env.example):
+[Sample `.env`](../.env.example):
 
 ```
 INTROSPECTION_STORAGE_ACCESS_KEY="access key"

guides/contributing.md

@@ -40,8 +40,8 @@ ts-node src/index.ts project init # same as running `./spk project init`
 
 ### Implementing Commands
 
-Refer to this [doc](./guides/command-implementation.md) for guidelines for
-implementing commands.
+Refer to this [doc](./command-implementation.md) for guidelines for implementing
+commands.
 
 ### Running Tests
 

guides/infra/spk-infra-generation-pipeline.md

@@ -13,9 +13,7 @@ orchestrator for your Infrastructure Generation workflow using `spk infra`.
    [here](https://github.com/yradsmikham/spk-infra-hld). You should be able to
    create your Infra HLD repo using a scaffolding process via `spk` (i.e.
    `spk infra scaffold`). For more information on how to do that, please refer
-   to the
-   [Cloud Infra Management](https://github.com/CatalystCode/spk/blob/master/docs/cloud-infra-management.md#scaffold)
-   doc.
+   to the [Cloud Infra Management](../cloud-infra-management.md) doc.
 
 ## Setup
 

guides/infra/spk-infra-under-the-hood.md

@@ -82,8 +82,8 @@ directory):
 
 `spk` will extend the capability to clone private repositories using personal
 access tokens (PAT). For more information, please refer to this
-[section](https://github.com/CatalystCode/spk/blob/master/docs/cloud-infra-management.md#authentication)
-of Cloud Infra Management.
+[section](../cloud-infra-management.md#authentication-private-repos) of Cloud
+Infra Management.
 
 ## Future Considerations
 

guides/manual-guide-to-rings.md

@@ -6,7 +6,7 @@ This guide presumes that you have set up your `spk` project, and installed all
 necessary pipelines created via `spk project init` (the lifecycle pipeline),
 `spk service create` (build update hld pipeline), and `spk hld init` (manifest
 generation pipeline), and followed the
-[guidelines for creating helm charts](./building-helm-charts-for-spk).
+[guidelines for creating helm charts](./building-helm-charts-for-spk.md).
 
 In `spk`, we offer the concept of a `ring` - a way to route inbound traffic to
 _revisions_ of a service on a Kubernetes cluster via request headers. For

guides/project-service-management-guide.md

@@ -28,7 +28,7 @@ This document describes the workflow for deploying a set of services
 An overview of how these different pieces fit together from an automation
 perspective:
 
-![spk resources](/guides/images/spk-resource-diagram.png "Bedrock SPK Resources")
+![spk resources](./images/spk-resource-diagram.png "Bedrock SPK Resources")
 
 ## Requirements
 
@@ -134,7 +134,7 @@ applied to the Kubernetes cluster by Flux.
   ```
 
 **NOTE** `spk hld` command documentation can be found
-[here](/guides/hld-management.md).
+[here](./hld-management.md).
 
 ### Materialized Manifests Repository
 
@@ -225,7 +225,7 @@ application repositories
   run `install-lifecycle-pipeline` once for each repo.
 
 **NOTE** `spk project` command documentation can be found
-[here](/guides/project-management.md).
+[here](./project-management.md).
 
 #### Adding a Service to a Application Repository
 
@@ -249,7 +249,7 @@ application repositories
   definition in Azure Devops.
 
 **NOTE** `spk service` command documentation can be found
-[here](/guides/service-management.md).
+[here](./service-management.md).
 
 #### Helm Configuration for SPK
 
@@ -426,7 +426,7 @@ parameters to `spk service create --helm-config-git`:
   ```
 
 **NOTE** `spk service` command documentation can be found
-[here](/guides/service-management.md).
+[here](./service-management.md).
 
 ## Helm Charts
 

guides/service-introspection-onboarding.md

@@ -5,7 +5,7 @@ Service Introspection shows information about a
 
 Service introspection is used via the `spk deployment` commands. More
 information about the commands is available in the command reference
-[here](https://github.com/CatalystCode/spk/blob/master/docs/service-introspection.md).
+[here](./service-introspection.md).
 
 The following diagram shows the main components of service introspection.
 ![spk service introspection diagram](./images/service_introspection.png)
@@ -34,7 +34,7 @@ it or use an existing one.
 **Option 1:**
 
 Use the
-[`spk deployment onboard`](https://github.com/CatalystCode/spk/blob/master/guides/service-introspection.md#onboard)
+[`spk deployment onboard`](https://catalystcode.github.io/spk/commands/#master@deployment_onboard)
 command.
 
 **Option 2:**
@@ -248,10 +248,10 @@ After completing the steps in this guide, you should be able to:
 
 - Validate and verify the `spk-config.yaml` settings and the service
   introspection storage using
-  [`spk deployment validate`](https://github.com/CatalystCode/spk/blob/master/docs/service-introspection.md#validate)
+  [`spk deployment validate`](https://catalystcode.github.io/spk/commands/#master@deployment_validate)
 
 - Get information about your deployment using
-  [`spk deployment get`](https://github.com/CatalystCode/spk/blob/master/docs/service-introspection.md#get)
+  [`spk deployment get`](https://catalystcode.github.io/spk/commands/#master@deployment_get)
 
 - Launch the dashboard to visualize the data using
-  [`spk deployment dashboard`](https://github.com/CatalystCode/spk/blob/master/docs/service-introspection.md#dashboard)
+  [`spk deployment dashboard`](https://catalystcode.github.io/spk/commands/#master@deployment_dashboard)

guides/service-introspection.md

@@ -35,7 +35,7 @@ Global options:
 ## Requirements
 
 Fill out the service introspection settings in your spk config file, for example
-`spk-config.yaml`. [Sample config file](./../../spk-config.yaml).
+`spk-config.yaml`. [Sample config file](../spk-config.yaml).
 
 ```
 introspection:

tools/brokenLinks.ts

@@ -0,0 +1,80 @@
+// DISCLAIMER: Only test this tool on mac
+// There may be some false negative results
+
+import fs from "fs";
+import path from "path";
+import axios from "axios";
+
+const urlExists = async (url: string): Promise<boolean> => {
+  try {
+    const res = await axios.head(url);
+    return res.status === 200;
+  } catch (_) {
+    return false;
+  }
+};
+
+const regex = /\[[^[]+?\]\(([^(]+?)\)/g;
+
+// get sub folders under commands folder.
+const getMarkdownFiles = (curDir: string, mds: string[]): void => {
+  fs.readdirSync(curDir).forEach(f => {
+    const p = path.join(curDir, f);
+    if (fs.lstatSync(p).isDirectory()) {
+      getMarkdownFiles(p, mds);
+    } else if (p.endsWith(".md")) {
+      mds.push(p);
+    }
+  });
+};
+
+const testFile = (folder: string, link: string): boolean => {
+  const arr = link.split(" ");
+  const target = arr[0].replace(/#.+/, "");
+  return fs.existsSync(folder + "/" + target);
+};
+
+const testLink = async (
+  file: string,
+  folder: string,
+  link: string
+): Promise<void> => {
+  if (link.startsWith("#")) {
+    return;
+  }
+  let ok = false;
+  if (link.startsWith("./")) {
+    ok = testFile(folder, link.substring(2));
+  }
+  if (!link.startsWith("https://") && !link.startsWith("http://")) {
+    ok = testFile(folder, link);
+  }
+  if (link.startsWith("https://") || link.startsWith("http://")) {
+    ok = await urlExists(link);
+  }
+  if (!ok) {
+    console.log(`${file}: ${link}`);
+  }
+};
+
+(async (): Promise<void> => {
+  const dir = path.join(process.cwd(), "guides");
+  const mdFiles: string[] = [];
+  getMarkdownFiles(dir, mdFiles);
+  const promises: Promise<void>[] = [];
+
+  mdFiles.forEach(f => {
+    const folder = f.substring(0, f.lastIndexOf("/"));
+    let content = fs.readFileSync(f, "utf-8");
+    content = content.replace(/\n/g, " ");
+
+    let m = regex.exec(content);
+    while (m) {
+      const target = m[1];
+      promises.push(testLink(f, folder, target));
+      m = regex.exec(content);
+    }
+  });
+
+  Promise.all(promises);
+})();

tools/generateDoc.ts

@@ -2,12 +2,12 @@ import fs from "fs";
 import path from "path";
 import { CommandBuildElements } from "../src/lib/commandBuilder";
 
-interface ICommand {
+interface Command {
   command: string;
   subcommands: CommandBuildElements[];
 }
 
-interface ICommandElement extends CommandBuildElements {
+interface CommandElement extends CommandBuildElements {
   markdown?: string;
 }
 
@@ -17,9 +17,9 @@ interface ICommandElement extends CommandBuildElements {
 const getAllDecorators = (curDir: string): CommandBuildElements[] => {
   const allFiles = fs.readdirSync(curDir);
   const jsonFiles = allFiles.filter(f => f.endsWith(".json"));
-  const arrJson: ICommandElement[] = [];
+  const arrJson: CommandElement[] = [];
   jsonFiles.forEach(fileName => {
-    const json = require(path.join(curDir, fileName)) as ICommandElement;
+    const json = require(path.join(curDir, fileName)) as CommandElement;
     if (!json.disabled) {
       const mdPath = path.join(
         curDir,
@@ -35,7 +35,7 @@ const getAllDecorators = (curDir: string): CommandBuildElements[] => {
 };
 
 // get sub folders under commands folder.
-const getSubDirectories = (curDir: string) => {
+const getSubDirectories = (curDir: string): string[] => {
   return fs
     .readdirSync(curDir)
     .map(f => path.join(curDir, f))
@@ -46,7 +46,7 @@ const getSubDirectories = (curDir: string) => {
 // command object. e.g `spk infra generate` and
 // `spk deployment dashboard`
 const listCommands = (
-  allCommands: ICommand[]
+  allCommands: Command[]
 ): { [key: string]: CommandBuildElements } => {
   const mainCommands: { [key: string]: CommandBuildElements } = {};
   allCommands.forEach(cmd => {
@@ -68,7 +68,7 @@ const dir = path.join(process.cwd(), "src", "commands");
 const commandDirs = getSubDirectories(dir);
 commandDirs.unshift(dir); // this is needed because `spk init` is outside `commands` folder
 
-const commands: ICommand[] = commandDirs
+const commands: Command[] = commandDirs
   .map(d => {
     return {
       command: path.basename(d),

tools/locateAliases.ts

@@ -2,7 +2,7 @@ import fs from "fs";
 import path from "path";
 import { CommandBuildElements } from "../src/lib/commandBuilder";
 
-interface ICommandElement extends CommandBuildElements {
+interface CommandElement extends CommandBuildElements {
   markdown?: string;
 }
 
@@ -12,9 +12,9 @@ interface ICommandElement extends CommandBuildElements {
 const getAllDecorators = (curDir: string): CommandBuildElements[] => {
   const allFiles = fs.readdirSync(curDir);
   const jsonFiles = allFiles.filter(f => f.endsWith(".json"));
-  const arrJson: ICommandElement[] = [];
+  const arrJson: CommandElement[] = [];
   jsonFiles.forEach(fileName => {
-    const json = require(path.join(curDir, fileName)) as ICommandElement;
+    const json = require(path.join(curDir, fileName)) as CommandElement;
     arrJson.push(json);
   });
   return arrJson;