fix: mdbook install\nfix: gqm build and links

Author: jeffabailey

Makefile

@@ -0,0 +1,7 @@
+.PHONY: build serve
+
+build:
+	./scripts/build.sh
+
+serve:
+	./scripts/serve.sh

README.md

@@ -15,6 +15,30 @@ Articles should be relatively short and self-contained so that they can be read
 Detailed explanation of InnerSource topics should go in the [InnerSource Patterns] book and be linked from the article here.
 Think of the articles in this book like either a conversational introduction/summary to a pattern or possible a journey showing how multiple patterns can be used together in an InnerSource Program.
 
+## Building the Book Locally
+
+The book is built with [mdBook](https://rust-lang.github.io/mdBook/).
+You don't need to install anything manually — the helper scripts handle everything.
+
+**Build the book** (output goes to `book/`):
+
+```sh
+make build
+```
+
+**Live-preview with auto-reload** (opens a local web server):
+
+```sh
+make serve
+```
+
+On the first run, the scripts will automatically install Rust and mdBook into the
+repo-local `.cargo/` and `.rustup/` directories (these are git-ignored).
+Subsequent runs reuse the existing install and start immediately.
+
+> **Windows users:** Run these scripts in **Git Bash** (included with
+> [Git for Windows](https://gitforwindows.org/)) or in WSL.
+
 ## Who can contribute?
 
 This book is a work in progress where anyone is more than welcome to contribute

book.toml

@@ -24,4 +24,5 @@ giscus.crossorigin = "anonymous"
 site-url = "/managing-innersource-projects/"
 additional-js = ["mermaid.min.js", "mermaid-init.js"]
 
-[output.linkcheck2]
+[output.linkcheck2]
+optional = true

measuring/use_gqm.md

@@ -31,32 +31,47 @@ graph LR;
   subgraph GQM[Goals, Questions, Metrics]
   %% begin nodes
     find-projects.md[Find InnerSource Projects]
+    index.md[InnerSource Goals]
     reduce-duplication.md[Reduce duplication]
     adoption-trend.md[What is the InnerSource adoption trend?]
+    index.md[InnerSource Questions]
     who-contributes.md[Who contributes to the InnerSource project?]
     who-uses.md[Who uses the InnerSource project?]
     code-contributions.md[Code contributions]
     contribution-distance.md[Contribution Distance]
+    index.md[InnerSource Metrics]
     number-of-innersource-repositories.md[Number of InnerSource repositories]
     usage-count.md[Usage count]
   %% begin edges
     find-projects.md-->who-uses.md
     find-projects.md-->who-contributes.md
+    index.md-->find-projects.md
+    index.md-->reduce-duplication.md
     reduce-duplication.md-->who-uses.md
     adoption-trend.md-->number-of-innersource-repositories.md
+    index.md-->adoption-trend.md
+    index.md-->who-contributes.md
+    index.md-->who-uses.md
     who-contributes.md-->code-contributions.md
     who-contributes.md-->contribution-distance.md
     who-uses.md-->usage-count.md
+    index.md-->code-contributions.md
+    index.md-->contribution-distance.md
+    index.md-->number-of-innersource-repositories.md
+    index.md-->usage-count.md
   %% begin clicks
-    click find-projects.md "/measuring/goals/find-projects" "Find InnerSource Projects"
-    click reduce-duplication.md "/measuring/goals/reduce-duplication" "Reduce duplication"
-    click adoption-trend.md "/measuring/questions/adoption-trend" "What is the InnerSource adoption trend?"
-    click who-contributes.md "/measuring/questions/who-contributes" "Who contributes to the InnerSource project?"
-    click who-uses.md "/measuring/questions/who-uses" "Who uses the InnerSource project?"
-    click code-contributions.md "/measuring/metrics/code-contributions" "Code contributions"
-    click contribution-distance.md "/measuring/metrics/contribution-distance" "Contribution Distance"
-    click number-of-innersource-repositories.md "/measuring/metrics/number-of-innersource-repositories" "Number of InnerSource repositories"
-    click usage-count.md "/measuring/metrics/usage-count" "Usage count"
+    click find-projects.md "goals/find-projects.html" "Find InnerSource Projects"
+    click index.md "goals/index.html" "InnerSource Goals"
+    click reduce-duplication.md "goals/reduce-duplication.html" "Reduce duplication"
+    click adoption-trend.md "questions/adoption-trend.html" "What is the InnerSource adoption trend?"
+    click index.md "questions/index.html" "InnerSource Questions"
+    click who-contributes.md "questions/who-contributes.html" "Who contributes to the InnerSource project?"
+    click who-uses.md "questions/who-uses.html" "Who uses the InnerSource project?"
+    click code-contributions.md "metrics/code-contributions.html" "Code contributions"
+    click contribution-distance.md "metrics/contribution-distance.html" "Contribution Distance"
+    click index.md "metrics/index.html" "InnerSource Metrics"
+    click number-of-innersource-repositories.md "metrics/number-of-innersource-repositories.html" "Number of InnerSource repositories"
+    click usage-count.md "metrics/usage-count.html" "Usage count"
   end
   subgraph Legend
     direction TB
@@ -65,13 +80,13 @@ graph LR;
     metric[Metric]
 
     classDef goals stroke:green,stroke-width:2px;
-    class goal,find-projects.md,reduce-duplication.md goals
+    class goal,find-projects.md,index.md,reduce-duplication.md goals
 
     classDef questions stroke:orange,stroke-width:2px;
-    class question,adoption-trend.md,who-contributes.md,who-uses.md questions
+    class question,adoption-trend.md,index.md,who-contributes.md,who-uses.md questions
 
     classDef metrics stroke:purple,stroke-width:2px;
-    class metric,code-contributions.md,contribution-distance.md,number-of-innersource-repositories.md,usage-count.md metrics
+    class metric,code-contributions.md,contribution-distance.md,index.md,number-of-innersource-repositories.md,usage-count.md metrics
   end
 ```
 

scripts/build.sh

@@ -0,0 +1,24 @@
+#!/usr/bin/env bash
+# Build the book locally.
+# Usage: ./scripts/build.sh
+#
+# On first run this will install Rust, mdBook, and its plugins into the
+# repo-local .cargo/ and .rustup/ directories (ignored by git).  Subsequent
+# runs reuse the existing install.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Point Rust/Cargo at repo-local directories (matches CI and install-mdbook.sh)
+export RUSTUP_HOME="${REPO_ROOT}/.rustup"
+export CARGO_HOME="${REPO_ROOT}/.cargo"
+export PATH="${CARGO_HOME}/bin:${PATH}"
+
+# Install mdBook if it isn't already present
+if [ ! -x "${CARGO_HOME}/bin/mdbook" ]; then
+    echo "mdBook not found — running first-time install (this may take a few minutes)…"
+    bash "${REPO_ROOT}/scripts/install-mdbook.sh"
+fi
+
+cd "${REPO_ROOT}"
+mdbook build "$@"

scripts/gqm_gen/index.test.ts

@@ -7,9 +7,17 @@ import {
   getLinks,
   getFileLinks,
   generateMermaidDiagram,
-  getGQMFileLinks
+  getGQMFileLinks,
+  getLinkUrl,
 } from "./index";
 
+test("getLinkUrl targets built HTML pages", () => {
+  assert.strictEqual(
+    getLinkUrl(LinkType.GOAL, "find-projects.md"),
+    "goals/find-projects.html"
+  );
+});
+
 test("can get links", () => {
   const node = new Commonmark.Node("paragraph");
   const links = getLinks(node);
@@ -38,3 +46,11 @@ test("can generate mermaid diagram from file", () => {
   const diagram = generateMermaidDiagram(graph);
   assert(diagram.indexOf("graph LR;") > 1);
 });
+
+test("GQM graph excludes template markdown from link edges", () => {
+  const graph = getGQMFileLinks("../../measuring/");
+  const hasTemplateEdge = graph.edges.some(
+    (e) => e.to?.endsWith("template.md") ?? false
+  );
+  assert.strictEqual(hasTemplateEdge, false);
+});

scripts/gqm_gen/index.ts

@@ -10,9 +10,8 @@ const outputPath = process.env.npm_config_outputPath || "../../measuring/use_gqm
 const graph = getGQMFileLinks(mdFilePath);
 
 export function getLinkUrl(linkType: LinkType, file: string) {
-  const measuringUrl = "/measuring";
-  const url = `${measuringUrl}/${linkType.toLowerCase()}s/${file}`
-  return url;
+  const htmlFile = file.replace(/\.md$/i, ".html");
+  return `${linkType.toLowerCase()}s/${htmlFile}`;
 }
 
 export function getGQMFileLinks(mdFilePath: string): Graph {
@@ -82,11 +81,17 @@ export function getLinks(parsed: Commonmark.Node): Link[] {
     node = event.node;
     if (event.entering && node.type === "link") {
       const destination = node.destination as string;
-      if (destination.includes('.md') && !destination.includes('use_gqm')) {
+      const linkFileName = path.parse(destination).base;
+      // Match getFileLinks readdir filter: skip template stubs linked from index pages.
+      if (
+        destination.includes('.md') &&
+        !destination.includes('use_gqm') &&
+        !linkFileName.endsWith('template.md')
+      ) {
         links.push({
           url: destination,
           text: node.firstChild?.literal as string,
-          name: path.parse(destination).base
+          name: linkFileName
         });
       }
     }
@@ -105,12 +110,8 @@ function getNodeShapeSyntax(node: Node): string {
 }
 
 export function generateMermaidDiagram(graph: Graph): string {
-  console.log('graph', graph);
-
   const { nodes, edges } = graph;
 
-  const getLinkUrl = (type: LinkType, nodeId: string) => `/measuring/${type.toLowerCase()}s/${nodeId}`;
-
   let mermaidSyntax = "```mermaid\ngraph LR;\n  subgraph GQM[Goals, Questions, Metrics]\n";
 
   // Add nodes
@@ -128,7 +129,7 @@ export function generateMermaidDiagram(graph: Graph): string {
   // Add click handlers
   mermaidSyntax += "  %% begin clicks\n";
   nodes.forEach(node => {
-    const url = getLinkUrl(node.type, node.id).replace('.md', '');
+    const url = getLinkUrl(node.type, node.id);
     mermaidSyntax += `    click ${node.id} "${url}" "${node.label}"\n`;
   });
 
@@ -157,25 +158,33 @@ export function updateGQMDiagram(): void {
 
     const graph = getGQMFileLinks(mdFilePath);
     const mermaidContent = generateMermaidDiagram(graph);
-    
+
+    // Strip the markdown fences to get raw mermaid syntax
+    const rawMermaid = mermaidContent
+      .replace(/^```mermaid\n/, '')
+      .replace(/\n```$/, '');
+
+    // Write raw mermaid to stdout so it can be piped to mmdc
+    process.stdout.write(rawMermaid + '\n');
+
     // Check if the output file exists
     if (!fs.existsSync(outputPath)) {
       console.error(`Error: Output file not found at ${outputPath}`);
       process.exit(1);
     }
-    
+
     // Read the existing file
     const existingContent = fs.readFileSync(outputPath, 'utf-8');
-    
+
     // Replace the mermaid block
     const updatedContent = existingContent.replace(
       /```mermaid[\s\S]*?```/,
       mermaidContent
     );
-    
+
     // Write back to file
     fs.writeFileSync(outputPath, updatedContent);
-    console.log(`Successfully updated GQM diagram at ${outputPath}`);
+    console.error(`Successfully updated GQM diagram at ${outputPath}`);
   } catch (error) {
     console.error('Error updating GQM diagram:', error);
     process.exit(1);

scripts/install-mdbook.sh

@@ -16,10 +16,11 @@ export CARGO_HOME="${REPO_ROOT}/.cargo"
 
 echo "Installing Rust and mdBook into ${REPO_ROOT} (RUSTUP_HOME=$RUSTUP_HOME, CARGO_HOME=$CARGO_HOME)"
 
-if ! command -v rustup >/dev/null 2>&1; then
+# Install Rust into repo-local RUSTUP_HOME/CARGO_HOME if not already there
+if [ ! -x "${CARGO_HOME}/bin/rustup" ]; then
 	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y --no-modify-path
-	source "${CARGO_HOME}/env"
 fi
+source "${CARGO_HOME}/env"
 
 rustup toolchain install "${RUST_TOOLCHAIN_VERSION}" --profile minimal
 rustup default "${RUST_TOOLCHAIN_VERSION}"

scripts/serve.sh

@@ -0,0 +1,25 @@
+#!/usr/bin/env bash
+# Build and serve the book locally with live-reload.
+# Usage: ./scripts/serve.sh
+#        ./scripts/serve.sh --open   # also opens a browser tab
+#
+# On first run this will install Rust, mdBook, and its plugins into the
+# repo-local .cargo/ and .rustup/ directories (ignored by git).  Subsequent
+# runs reuse the existing install.
+set -euo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Point Rust/Cargo at repo-local directories (matches CI and install-mdbook.sh)
+export RUSTUP_HOME="${REPO_ROOT}/.rustup"
+export CARGO_HOME="${REPO_ROOT}/.cargo"
+export PATH="${CARGO_HOME}/bin:${PATH}"
+
+# Install mdBook if it isn't already present
+if [ ! -x "${CARGO_HOME}/bin/mdbook" ]; then
+    echo "mdBook not found — running first-time install (this may take a few minutes)…"
+    bash "${REPO_ROOT}/scripts/install-mdbook.sh"
+fi
+
+cd "${REPO_ROOT}"
+mdbook serve "$@"