feat: add linkcheckers lychee/mdbook

jeffabailey · jeffabailey · commit 7d89ebb0bdd0 · 2026-03-18T18:50:50.000-07:00
fix: broken links
chore: improve clarity
diff --git a/.lycheeignore b/.lycheeignore
@@ -0,0 +1,9 @@
+# Pages excluded from link checking (see scripts/lychee-book.sh)
+# print.html aggregates the whole book and repeats links; excluding it is required.
+^https?://[^/]+/print\.html
+# External sites that block or throttle link checkers
+https://pixabay.com/users/bru-no-1161770/
+https://pixabay.com/service/license-summary/
+https://www.sap.com/
+# Built book may serve this chapter at README.html or index.html; ignore if 404
+^https?://[^/]+/measuring/gqm_example/README\.html
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -23,7 +23,7 @@ This book uses the [Goal-Question-Metric] approach to documenting InnerSource me
 The full graph of relationships is visible in this [graph].
 
 Add in your scenarios by copying this [goal template], [question template], and/or [metric template], filling them out, and submitting them in pull request.
-After successful merge, a [Trusted Committer](https://github.com/orgs/InnerSourceCommons/teams/ispo-working-group-trusted-committers) will manually[^1] add those to the [graph].
+After successful merge, a [Trusted Committer](https://github.com/orgs/InnerSourceCommons/teams/ispo-working-group-trusted-committers) will manually add those to the [graph].
 If interested, feel free to [edit the MermaidJS source] of the graph on your own!
 
 By adding in your scenarios to the graph, you will be able to see how others approach and interact with them.
@@ -33,9 +33,6 @@ You may get new ideas of what metrics answer the questions you have or what addi
 
 When using titles in Markdown, use # for main title, ## for the second header title, etc. It's just to follow the same style :).
 
-[^1]: [#37](https://github.com/InnerSourceCommons/managing-inner-source-projects/issues/37) will automate the addition of new goals, questions, and metrics to the graph.
-At that time this manual step will no longer be needed.
-
 [Goal-Question-Metric]: https://en.wikipedia.org/wiki/GQM
 [goals]: https://github.com/InnerSourceCommons/managing-inner-source-projects/tree/main/measuring/goals
 [questions]: https://github.com/InnerSourceCommons/managing-inner-source-projects/tree/main/measuring/questions
diff --git a/README.md b/README.md
@@ -1,6 +1,6 @@
 # Managing InnerSource Projects book
 
-![Managing InnerSource Projects](managing-innersource-projects-cover.jpg)
+![Managing InnerSource Projects](./managing-innersource-projects-cover.jpg)
 
 ## What is this book about?
 
@@ -40,9 +40,9 @@ Come join us and contribute!
 ## How Do We Structure Goals, Questions, and Metrics?
 
 Review the [Goal-Question-Metric Approach](./measuring/gqm.md) to further understand how we structure goals, questions, and metrics.
-Review [GQM use cases and user journeys](./measuring/gqm_example/README.md) to guide their development.
+Review [GQM use cases and user journeys](measuring/gqm_example/README.md) to guide their development.
 
-We document goals, questions, and metrics in separate folders in the [measuring](./measuring) directory.
+We document goals, questions, and metrics in separate folders in the [measuring](./measuring/index.md) directory.
 You can browse all goals, questions, and metrics in [graph format](./measuring/use_gqm.md). 
 
 Add in your own scenarios to the graph!
@@ -60,13 +60,12 @@ Each chapter in the book is authored and reviewed by different people. That info
 be found at the beginning of each chapter. This initiative is fostered by the [ISPO Working Group].
 For further questions, please contact us in [Slack](https://innersourcecommons.org/slack)!
 
-The book cover was created by [Sebastian Spier](https://spier.hu), using an image by user [Bru-nO](https://pixabay.com/photos/measure-unit-of-measure-meterstab-2737004/), available under the [Pixabay License](https://pixabay.com/service/license/).
+The book cover was created by [Sebastian Spier](https://spier.hu), using an image by user [Bru-nO](https://pixabay.com/users/bru-no-1161770/), available under the [Pixabay License](https://pixabay.com/service/license-summary/).
 
 All of the content found in this repository is licensed [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
-Please see [LICENSE.txt] in this repository for the full text of the license.
+Please see [LICENSE.txt](https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/LICENSE.txt) in this repository for the full text of the license.
 
 [Bitergia]: https://bitergia.com/
 [ISPO Working Group]: https://innersourcecommons.org/community/#ispo
 [InnerSource Commons]: https://innersourcecommons.org/
 [InnerSource Patterns]: https://patterns.innersourcecommons.org/
-[LICENSE.txt]: ./LICENSE.txt
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -1,6 +1,7 @@
 # Summary
 
 * [Summary](README.md)
+* [Contributing](CONTRIBUTING.md)
 * [Introduction](introduction/introduction.md)
   * [Scenarios](introduction/scenarios.md)
   * [Framework](introduction/framework.md)
@@ -15,19 +16,23 @@
       * [Goals](measuring/goals/index.md)
         * [Find InnerSource Projects](measuring/goals/find-projects.md)
         * [Reduce Duplication](measuring/goals/reduce-duplication.md)
+        * [GQM Goal Template](measuring/goals/gqm_goal_template.md)
       * [Questions](measuring/questions/index.md)
-        * [What is the InnerSource Adoption Trend?](measuring/questions/adoption-trend.md) 
+        * [What is the InnerSource Adoption Trend?](measuring/questions/adoption-trend.md)
         * [Who contributes to the InnerSource project?](measuring/questions/who-contributes.md)
         * [Who Uses](measuring/questions/who-uses.md)
+        * [GQM Question Template](measuring/questions/gqm_question_template.md)
       * [Metrics](measuring/metrics/index.md)
         * [Code Contributions](measuring/metrics/code-contributions.md)
         * [Contribution Distance](measuring/metrics/contribution-distance.md)
         * [Number of InnerSource repositories](measuring/metrics/number-of-innersource-repositories.md)
         * [Usage Count](measuring/metrics/usage-count.md)
+        * [GQM Metric Template](measuring/metrics/gqm_metric_template.md)
   * [Areas of Analysis](measuring/areas.md)
   * [Goal-Question-Metric Approach](measuring/gqm.md)
   * [Strategy](measuring/strategy.md)
   * [Examples of Interest](measuring/examples.md)
+  * [GQM Use Cases and User Journeys](measuring/gqm_example/README.md)
   * [References](measuring/references.md)
   * [Authors and Reviewers](measuring/authors.md)
 * [Governance](governance/governance.md)
diff --git a/book.toml b/book.toml
@@ -23,3 +23,5 @@ giscus.crossorigin = "anonymous"
 # Required for correct asset and 404 paths on GitHub Pages (project site and PR preview subpaths).
 site-url = "/managing-innersource-projects/"
 additional-js = ["mermaid.min.js", "mermaid-init.js"]
+
+[output.linkcheck2]
diff --git a/governance/governance.md b/governance/governance.md
@@ -250,7 +250,7 @@ organization and its context and find other goals InnerSource may
 contribute towards. Then communicate it and get as much air cover
 from your executives as you can.
 
-For how governance and transparency support responsible use of AI in development, see [InnerSource and AI](/innersource-and-ai/innersource-and-ai.md), in particular [Risks and Guardrails](/innersource-and-ai/risks-and-guardrails.md).
+For how governance and transparency support responsible use of AI in development, see [InnerSource and AI](../innersource-and-ai/innersource-and-ai.md), in particular [Risks and Guardrails](../innersource-and-ai/risks-and-guardrails.md).
 
 [^1]: http://oss-watch.ac.uk/resources/governancemodels
 
diff --git a/infrastructure/basics.md b/infrastructure/basics.md
@@ -147,7 +147,7 @@ and communication. Even when the developers are in face to face meetings,
 those tools should be used as they will leave traces of activity readable
 by others within the organization.
 
-![Extended usual software development process](development_workflow_all.jpg)
+![Extended usual software development process](./development_workflow_all.jpg)
 
 ## Communication Channels Infrastructure
 
@@ -210,7 +210,7 @@ to their specific needs.
 The following is a potential architecture that could help when accessing
 the several data layers, from raw information to detailed visualizations.
 
-![Monitoring Infrastructure](monitoring_infrastructure.jpg)
+![Monitoring Infrastructure](./monitoring_infrastructure.jpg)
 
 * **Retrieval Platform**: this first part uses as input any of the data
 sources already mentioned. Version systems, mailing lists, tickets,
diff --git a/innersource-and-ai/shaping-for-ai.md b/innersource-and-ai/shaping-for-ai.md
@@ -34,4 +34,4 @@ Several open standards are emerging that are relevant to InnerSource programs ad
 
 InnerSource program leads should monitor these standards as they mature. Organizations that adopt them early can shape how agent-to-agent and agent-to-repository interactions work across team boundaries, reinforcing InnerSource collaboration patterns at the tooling level.
 
-For more on infrastructure and tooling in InnerSource, see [Tooling](/tooling/innersource-tooling.md) and [Infrastructure](/infrastructure/infrastructure.md).
+For more on infrastructure and tooling in InnerSource, see [Tooling](../tooling/innersource-tooling.md) and [Infrastructure](../infrastructure/infrastructure.md).
diff --git a/introduction/framework.md b/introduction/framework.md
@@ -34,7 +34,7 @@ Let's introduce the *InnerSource framework*.
 
 A core aspect of the InnerSource framework is the governance model. Good governance is essential for the success of any project, and InnerSource is no exception.
 
-Pick the right [governance standards and model](/governance/governance.md) for your organization.
+Pick the right [governance standards and model](../governance/governance.md) for your organization.
 
 ## Technical infrastructure
 
@@ -115,4 +115,4 @@ Open measurement gives a lot of benefits for our InnerSource community:
 
 ## InnerSource and AI
 
-Organizations adopting AI in the workplace—from generative AI assistants to agentic coding tools—can benefit from InnerSource in new ways. Shared repositories, clear boundaries, and collaborative practices help both humans and AI work with the right context and reuse. See the [InnerSource and AI](/innersource-and-ai/innersource-and-ai.md) section for why it matters, how to shape repositories and practices for AI, and what risks and guardrails to consider.
+Organizations adopting AI in the workplace—from generative AI assistants to agentic coding tools—can benefit from InnerSource in new ways. Shared repositories, clear boundaries, and collaborative practices help both humans and AI work with the right context and reuse. See the [InnerSource and AI](../innersource-and-ai/innersource-and-ai.md) section for why it matters, how to shape repositories and practices for AI, and what risks and guardrails to consider.
diff --git a/lychee.toml b/lychee.toml
@@ -0,0 +1,8 @@
+# Lychee config for checking the built mdbook served at http://localhost:3000/
+# Run: scripts/lychee-book.sh or:
+#   find book/html -name "*.html" -not -path "*/.cargo/*" -not -path "*/.git/*" -not -path "*/.rustup/*" -not -path "*/.github/*" -not -path "*/.claude/*" -not -path "*/.nwave/*" | lychee --base-url "http://localhost:3000/" --files-from -
+
+format = "detailed"
+verbose = "info"
+# Allow 2xx and 3xx (redirects) as success
+accept = "100..=103,200..=399"
diff --git a/scripts/install-mdbook.sh b/scripts/install-mdbook.sh
@@ -6,6 +6,7 @@ set -euo pipefail
 MDBOOK_VERSION="${MDBOOK_VERSION:-0.5.2}"
 MDBOOK_MERMAID_VERSION="${MDBOOK_MERMAID_VERSION:-0.17.0}"
 MDBOOK_EMBEDIFY_VERSION="${MDBOOK_EMBEDIFY_VERSION:-0.3.2}"
+MDBOOK_LINKCHECK2_VERSION="${MDBOOK_LINKCHECK2_VERSION:-0.12.0}"
 RUST_TOOLCHAIN_VERSION="${RUST_TOOLCHAIN_VERSION:-1.91.1}"
 
 # Install into repo so CI and local use the same layout (avoids cross-device issues in act)
@@ -23,9 +24,14 @@ fi
 rustup toolchain install "${RUST_TOOLCHAIN_VERSION}" --profile minimal
 rustup default "${RUST_TOOLCHAIN_VERSION}"
 
+# https://github.com/rust-lang/mdBook
 cargo install --version "${MDBOOK_VERSION}" mdbook
+# https://github.com/badboy/mdbook-mermaid
 cargo install --version "${MDBOOK_MERMAID_VERSION}" mdbook-mermaid
+# https://github.com/rust-lang/mdbook-embedify
 cargo install --version "${MDBOOK_EMBEDIFY_VERSION}" mdbook-embedify
+# https://github.com/Michael-F-Bryan/mdbook-linkcheck
+cargo install --version "${MDBOOK_LINKCHECK2_VERSION}" mdbook-linkcheck2
 
 echo "Done. To build the book, use the project mdbook (do not use your global 'mdbook'):"
 echo "  ${CARGO_HOME}/bin/mdbook build"
diff --git a/scripts/lychee-book.sh b/scripts/lychee-book.sh
@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# Check all links in the built and served book with lychee.
+#
+# Prereqs:
+#   1. Build the book: mdbook build
+#   2. Serve the book: npx serve book -p 3000
+#   3. Install lychee: cargo install lychee
+#
+# Usage: ./scripts/lychee-book.sh [BASE_URL]
+#   BASE_URL defaults to http://localhost:3000/
+#
+# Report shows which page contains each broken link (source page → failed URL).
+# For the "Broken links by page" section, jq must be installed; otherwise only lychee's default output is shown.
+
+set -e
+
+BASE_URL="${1:-http://localhost:3000/}"
+# Ensure base URL has no trailing slash for consistent resolution (lychee strips fragment)
+BASE_URL="${BASE_URL%/}"
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BOOK_DIR="${ROOT}/book"
+JSON_REPORT="${ROOT}/.lychee-report.json"
+
+# Collect only the book's HTML (exclude vendored/cache dirs and nested book/html/).
+# npx serve book -p 3000 serves BOOK_DIR at BASE_URL, so URLs are BASE_URL/<path-under-book>.
+# Required: exclude print.html (see .lycheeignore); it aggregates the whole book and repeats links.
+set +e
+find "$BOOK_DIR" -name "*.html" \
+  -not -path "*/.cargo/*" \
+  -not -path "*/.git/*" \
+  -not -path "*/.rustup/*" \
+  -not -path "*/.github/*" \
+  -not -path "*/.claude/*" \
+  -not -path "*/.nwave/*" \
+  -not -path "*/html/*" \
+  2>/dev/null | while read -r f; do
+  # Convert path to URL: book/measuring/use_gqm.html -> BASE_URL/measuring/use_gqm.html
+  path="${f#"$BOOK_DIR/"}"
+  [[ "$path" == "print.html" ]] && continue
+  echo "${BASE_URL}/${path}"
+done | lychee --no-progress -q --format json --output "$JSON_REPORT" --files-from -
+lychee_exit=$?
+set -e
+
+# Print report: for each broken link, show the page that contains it.
+# Lychee uses "error_map" (source URL -> list of { url, status: { code } }); some versions use "fail_map".
+echo "JSON_REPORT: $JSON_REPORT"
+if [[ -f "$JSON_REPORT" ]]; then
+  errors=""
+  if command -v jq &>/dev/null; then
+    errors=$(jq -r '(.error_map // .fail_map // {}) | to_entries[] | "Page: \(.key)\n  Broken:\n\(.value[] | "    [\(.status.code)] \(.url)")"' "$JSON_REPORT" 2>/dev/null)
+  fi
+  if [[ -n "$errors" ]]; then
+    echo ""
+    echo "=== Broken links by page ==="
+    echo "$errors"
+  else
+    # Report has failures but we couldn't print them (no jq or jq failed); leave report for inspection
+    report_errors=$(jq -r '.errors // 0' "$JSON_REPORT" 2>/dev/null || echo "0")
+    if [[ "$report_errors" != "0" ]] && [[ "$report_errors" != "null" ]]; then
+      echo ""
+      echo "=== Broken links (report has $report_errors failure(s)); full report: $JSON_REPORT ==="
+      echo "Install jq to see 'Broken links by page' summary, or: cat $JSON_REPORT | jq '.error_map'"
+    fi
+  fi
+  rm -f "$JSON_REPORT"
+fi
+
+exit "$lychee_exit"
diff --git a/tooling/authors.md b/tooling/authors.md
@@ -9,4 +9,4 @@
 
 (Chronological order)
 
-- Guilherme Dellagustin ([SAP](https://sap.com/))
+- Guilherme Dellagustin ([SAP](https://www.sap.com/index.html))
diff --git a/tooling/github-configuration.md b/tooling/github-configuration.md
@@ -218,4 +218,4 @@ Enabling Server Statistics in your GitHub Enterprise Server environment can prov
 
 ## Resources
 
-- [Orgs and Teams Best Practices · GitHub](https://gist.github.com/rwnfoo/3e19747f6dc2c5b9cfb0ff9c89d834b4)
+- [Organization and repository settings](#organization-setting) (in this guide)
diff --git a/tooling/innersource-tooling.md b/tooling/innersource-tooling.md
@@ -1,6 +1,6 @@
 # InnerSource with GitHub
 
-For how tooling and workflow integration support AI-assisted development and InnerSource together, see the [InnerSource and AI](/innersource-and-ai/innersource-and-ai.md) section, in particular [Shaping Repositories and Practices for AI](/innersource-and-ai/shaping-for-ai.md).
+For how tooling and workflow integration support AI-assisted development and InnerSource together, see the [InnerSource and AI](../innersource-and-ai/innersource-and-ai.md) section, in particular [Shaping Repositories and Practices for AI](../innersource-and-ai/shaping-for-ai.md).
 
 ## Effective InnerSource Strategies and Configuration for GitHub
 
diff --git a/translations/gl/README.md b/translations/gl/README.md
@@ -28,7 +28,7 @@ Se ten algunha pregunta, pode pórse en contacto con José Manrique López ou Da
 
 Grazas polo seu interese.
 
-A portada do libro foi creada por [Sebastian Spier](https://spier.hu), a partir dunha imaxe do usuario [Bru-nO](https://pixabay.com/photos/measure-unit-of-measure-meterstab-2737004/), dispoñible baixo a [licenza Pixabay](https://pixabay.com/service/license/).
+A portada do libro foi creada por [Sebastian Spier](https://spier.hu), a partir dunha imaxe do usuario [Bru-nO](https://pixabay.com/photos/measure-unit-of-measure-meterstab-2737004/), dispoñible baixo a [licenza Pixabay](https://pixabay.com/service/license-summary/).
 
 Todo o contido que se atopa neste repositorio ten licenza [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/).
 

Original file line number	Diff line number	Diff line change
`@@ -34,4 +34,4 @@ Several open standards are emerging that are relevant to InnerSource programs ad`
`34`	`34`
`35`	`35`	`InnerSource program leads should monitor these standards as they mature. Organizations that adopt them early can shape how agent-to-agent and agent-to-repository interactions work across team boundaries, reinforcing InnerSource collaboration patterns at the tooling level.`
`36`	`36`
`37`		`-For more on infrastructure and tooling in InnerSource, see [Tooling](/tooling/innersource-tooling.md) and [Infrastructure](/infrastructure/infrastructure.md).`
	`37`	`+For more on infrastructure and tooling in InnerSource, see [Tooling](../tooling/innersource-tooling.md) and [Infrastructure](../infrastructure/infrastructure.md).`