ci(links): fix Lychee configuration and report the failures it finds

Signed-off-by: Ntege Daniel <danientege785@gmail.com>

Author: danielmarv

.github/workflows/check-broken-links.yml

@@ -27,12 +27,38 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
+      # Persists .lycheecache between runs. Note that --max-cache-age below is
+      # deliberately shorter than the weekly cron: every scheduled run re-checks
+      # every URL from scratch, so a link that rots mid-week is still caught.
+      # The cache exists to make same-day repeats cheap -- manual
+      # workflow_dispatch runs and re-runs of a failed job -- rather than to
+      # skip work on the weekly pass.
+      - name: Restore Lychee cache
+        uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 # v6.1.0
+        with:
+          path: .lycheecache
+          key: lychee-cache-${{ github.run_id }}
+          restore-keys: |
+            lychee-cache-
+
       - name: Check Markdown links (Lychee)
         id: lychee
         uses: lycheeverse/lychee-action@e7477775783ea5526144ba13e8db5eec57747ce8 # v2.9.0
         continue-on-error: true
         with:
-          args: --verbose --no-progress './**/*.md'
+          # --root-dir is required for root-relative links such as
+          # /images/foo.png to resolve against public/ instead of the
+          # filesystem root; without it every such link is reported broken.
+          # Concurrency, retries, timeout and accepted status codes come from
+          # lychee.toml; skipped hosts come from .lycheeignore.
+          args: >-
+            --verbose
+            --no-progress
+            --root-dir "${{ github.workspace }}/public"
+            --cache
+            --max-cache-age 1d
+            './**/*.md'
+          output: ./lychee/out.md
           fail: true
           token: ${{ secrets.GITHUB_TOKEN }}
 
@@ -41,6 +67,8 @@ jobs:
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
+            const fs = require('fs');
+
             // Determine if this is a dry run
             const isManual = context.eventName === 'workflow_dispatch';
             const dryRun = isManual ? String(context.payload.inputs.dry_run).toLowerCase() === 'true' : false;
@@ -52,14 +80,55 @@ jobs:
 
             console.log(`Event: ${context.eventName}, Dry Run: ${dryRun}`);
 
-            // Define Issue Body
-            const body = `### 🔗 Broken Links Detected\n\n` +
-              `The scheduled markdown link check workflow has detected broken links.\n\n` +
-              `**Run Details:**\n` +
-              `- **Timestamp:** ${new Date().toISOString()}\n` +
-              `- **Workflow Run:** [View Logs](${runUrl})\n\n` +
-              `> **Note:** We use [Lychee](https://github.com/lycheeverse/lychee) for link checking. ` +
-              `Please check the "Check Markdown links" step in the logs to see the specific URLs that failed.`;
+            // Pull in Lychee's own markdown report so the issue names the
+            // offending URLs and their source files. Without this the report
+            // only ever existed in the run logs, which is why this issue
+            // accumulated timestamps with nothing actionable in them.
+            //
+            // GitHub rejects bodies over 65536 characters, so leave headroom
+            // for the surrounding text and say so explicitly when truncating.
+            const REPORT_LIMIT = 60000;
+            const reportPath = './lychee/out.md';
+
+            function readReport() {
+              try {
+                const raw = fs.readFileSync(reportPath, 'utf8').trim();
+                if (!raw) {
+                  console.log(`${reportPath} is empty; falling back to the log pointer.`);
+                  return null;
+                }
+                if (raw.length <= REPORT_LIMIT) return raw;
+                return raw.slice(0, REPORT_LIMIT) +
+                  `\n\n> **Report truncated** at ${REPORT_LIMIT} characters. ` +
+                  `See the [full run logs](${runUrl}) for the complete list.`;
+              } catch (error) {
+                // A missing artefact must never fail the reporting step.
+                console.log(`Could not read ${reportPath}: ${error.message}`);
+                return null;
+              }
+            }
+
+            const report = readReport();
+            const details = report
+              ? `<details open>\n<summary><strong>Lychee report</strong></summary>\n\n${report}\n\n</details>`
+              : `> **Note:** The Lychee report could not be read for this run. ` +
+                `Please check the "Check Markdown links (Lychee)" step in the logs ` +
+                `to see the specific URLs that failed.`;
+
+            // Shared by both the create and the update path, so recurring
+            // comments carry the current failure list rather than a timestamp.
+            function buildBody(heading) {
+              return `### 🔗 ${heading}\n\n` +
+                `**Run Details:**\n` +
+                `- **Timestamp:** ${new Date().toISOString()}\n` +
+                `- **Workflow Run:** [View Logs](${runUrl})\n\n` +
+                `${details}\n\n` +
+                `> Link checking uses [Lychee](https://github.com/lycheeverse/lychee). ` +
+                `Hosts that cannot be verified by a headless checker are listed, with reasons, ` +
+                `in \`.lycheeignore\`.`;
+            }
+
+            const body = buildBody('Broken Links Detected');
 
             if (dryRun) {
               console.log("DRY RUN: Would have created or updated an issue.");
@@ -84,7 +153,7 @@ jobs:
                   owner: context.repo.owner,
                   repo: context.repo.repo,
                   issue_number: existingIssue.number,
-                  body: `**Update ${new Date().toISOString()}:** Still finding broken links.\nCheck new run logs: ${runUrl}`
+                  body: buildBody('Still Finding Broken Links')
                 });
               } else {
                 console.log("Creating a new issue...");

.gitignore

@@ -39,3 +39,7 @@ yarn-error.log*
 # typescript
 *.tsbuildinfo
 next-env.d.ts
+
+# lychee link checker (report output and response cache)
+/lychee/
+.lycheecache

.lycheeignore

@@ -0,0 +1,47 @@
+# URL patterns (regex) skipped by the weekly Lychee link check.
+# See .github/workflows/check-broken-links.yml and lychee.toml.
+#
+# Every entry must state WHY it is excluded. Only add a host here when it
+# cannot be verified by a headless checker -- a host that is genuinely dead
+# belongs in a content fix, not in this file.
+
+# --- Hosts that reject non-browser clients -----------------------------------
+
+# LFX meeting calendar: returns 403 to any client without a browser session.
+zoom-lfx\.platform\.linuxfoundation\.org
+
+# Zoom join links: redirect to an auth wall for unauthenticated clients.
+zoom\.us
+
+# Discord: answers 403/405 to bots on both the invite and app domains.
+discord\.(com|gg)
+
+# LinkedIn: serves HTTP 999 (a non-standard bot deterrent) to all crawlers.
+linkedin\.com
+
+# Meetup: behind Cloudflare bot protection, returns 403.
+meetup\.com
+
+# HIP documents: hips.hedera.com answers 403 to non-browser clients. The pages
+# resolve normally in a browser, so this is bot protection, not a dead target.
+hips\.hedera\.com
+
+# --- Hosts that are unreliable rather than hostile ---------------------------
+
+# Contributor-stats API on a free Koyeb tier: cold starts exceed the timeout.
+# The endpoint is consumed at runtime by src/components/ContributorsGrid, so a
+# real outage surfaces on the site itself rather than only in this check.
+hedera-issues\.koyeb\.app
+
+# --- Local development URLs --------------------------------------------------
+
+# docs/setup/*.md document the local dev server; nothing listens on port 3000
+# inside CI, so this is expected to be unreachable there.
+^https?://localhost(:\d+)?
+
+# --- Next.js routes with no counterpart under public/ ------------------------
+
+# /heroes and /hacktoberfest are real routes (src/app/heroes, src/app/hacktoberfest)
+# but are rendered by Next.js, so --root-dir cannot resolve them to a file.
+# Matched on the resolved file:// URI that --root-dir produces.
+file:///.*/public/(heroes|hacktoberfest)$

README.md

@@ -1,7 +1,7 @@
 # Hiero Website
 
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/hiero-ledger/hiero-website/badge)](https://scorecard.dev/viewer/?uri=github.com/hiero-ledger/hiero-website)
-[![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/10697/badge)](https://bestpractices.coreinfrastructure.org/projects/10697)
+[![CII Best Practices](https://www.bestpractices.dev/projects/10697/badge)](https://www.bestpractices.dev/projects/10697)
 [![License](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
 Source code for [hiero.org](https://hiero.org) — the official website for the Hiero project.
@@ -70,9 +70,7 @@ Detailed documentation lives in the [`docs/`](docs/) directory. Below is a guide
 
 | Guide | Description |
 | --- | --- |
-| [First Contribution Checklist](docs/05-first-contribution-checklist.md) | Pre-PR validation checklist |
-| [Contribution Workflow](docs/workflow.md) | End-to-end guide: fork, branch, commit, and submit a PR |
-| [Commit Signing Guide](docs/signing.md) | Setting up DCO and GPG signing |
+| [Testing and Quality Checks](docs/06-testing-and-quality-checks.md) | Pre-PR validation: format, lint, test, and build |
 | [Discord Guide](docs/discord.md) | Joining the community chat |
 
 ### For Developers
@@ -84,29 +82,21 @@ Detailed documentation lives in the [`docs/`](docs/) directory. Below is a guide
 | [Adding Pages](docs/03-adding-pages.md) | Creating new routes and markdown-backed pages |
 | [Components Guide](docs/04-components.md) | Component layout, imports, and testing conventions |
 | [Testing and Quality Checks](docs/06-testing-and-quality-checks.md) | Linting, testing, and CI expectations |
-| [Rebasing Guide](docs/rebasing.md) | Keeping your branch in sync with upstream |
-| [Merge Conflicts Guide](docs/merge_conflicts.md) | Resolving merge conflicts |
 
 ### For Content Authors
 
 | Guide | Description |
 | --- | --- |
 | [Blog Writing Guide](docs/blogs.md) | Templates, front matter reference, and publishing workflow |
 
-### For Maintainers
-
-| Guide | Description |
-| --- | --- |
-| [GitHub Automation](docs/07-github-automation.md) | CI workflows and automation overview |
-
 ## Contributing
 
 We welcome contributions of all kinds — code, documentation, and blog posts.
 
 1. **Find an issue**: Browse [unassigned open issues](https://github.com/hiero-ledger/hiero-website/issues?q=is%3Aissue%20state%3Aopen%20no%3Aassignee) and comment `/assign` to claim one.
 2. **Set up your environment**: Follow the [Getting Started](#getting-started) section above.
-3. **Read the workflow**: See the [Contribution Workflow](docs/workflow.md) for the full process.
-4. **Sign your commits**: All commits must be DCO and GPG signed. See the [Signing Guide](docs/signing.md).
+3. **Read the docs**: Start with the [Repository Overview](docs/01-repo-overview.md), then run the [Testing and Quality Checks](docs/06-testing-and-quality-checks.md) before opening a PR.
+4. **Sign your commits**: All commits must be DCO and GPG signed.
 
 New to the project? Start with a [Good First Issue](https://github.com/hiero-ledger/hiero-website/issues?q=is%3Aissue%20state%3Aopen%20label%3A%22good+first+issue%22%20no%3Aassignee).
 

content/_index.md

@@ -274,7 +274,7 @@ quote = '''
 “The HBAR Foundry community is excited to see the contribution of the Hedera software to the Linux Foundation Decentralized Trust project. We're delighted to see Hedera's commitment to growing an independently governed and transparent community with more resources and opportunities to engage and grow the ecosystem.”
 '''
 author = '''
-<a href="https://hbarfoundry.com/" target="_blank" rel="noreferrer noopener">The HBAR Foundry</a>, A Community Of Expert Hedera Builders
+The HBAR Foundry, A Community Of Expert Hedera Builders
 '''
 logo = "images/Hiero-Logo-HbarFoundry.png"
 

content/hacktoberfest/index.md

@@ -11,7 +11,7 @@ Your contributions can help us improve and expand the project, making it better
 
 - **🌱 Learn and Grow**: Dive into open source, pick up new skills, and level up your coding game.
 - **🤝 Join the Community**: Connect with fellow developers, share knowledge, and build lasting relationships.
-  You can find all heros that have already contributed to Hiero [here](/heros).
+  You can find all heroes that have already contributed to Hiero [here](/heroes).
 - **🌍 Make an Impact**: Your code can make a difference, helping users around the globe.
 
 ## Hacktoberfest 2024

content/posts/get-involved/index.md

@@ -31,7 +31,7 @@ Whether you're a civic tech org, an NGO, a DAO, or an enterprise exploring verif
 
 
 ## 📌 Not Ready to Run? List Yourself as an Adopter!
-Even if you’re not ready to run for a seat just yet, there’s still a meaningful way to contribute: **add your organization to the [adopters.md](https://github.com/hiero-identity/hiero/blob/main/adopters.md) file** in the Hiero GitHub repo.
+Even if you’re not ready to run for a seat just yet, there’s still a meaningful way to contribute: **add your organization to the [ADOPTERS.md](https://github.com/hiero-ledger/governance/blob/main/ADOPTERS.md) file** in the Hiero GitHub repo.
 
 This public list of adopters helps:
 - Signal real-world demand for the protocol.

content/posts/hedera-devday-2026.md

@@ -13,9 +13,9 @@ image = "/images/profile-hiero.png"
 
 On February 17th, builders, maintainers and ecosystem collaborators gathered in Denver for Hedera’s DevDay event. This was an exciting day for the Hedera community guided by exciting deep dive presentations into what’s next for the Hedera projects and the broader open source community around it.
 
-Hosted as part of the Hedera community’s ongoing commitment to transparency and developer engagement, [Hedera DevDay 2026](https://devday.hedera.com/home) delivered roadmap updates, technical insights, hands-on demos, and exciting opportunities to collaborate across projects.
+Hosted as part of the Hedera community’s ongoing commitment to transparency and developer engagement, Hedera DevDay 2026 delivered roadmap updates, technical insights, hands-on demos, and exciting opportunities to collaborate across projects.
 
-The [event's agenda](https://devday.hedera.com/agenda) featured several workshops including:
+The event's agenda featured several workshops including:
 
 - Deploying Smart Contracts That Run Themselves
 - Designing for Scale: Batch 1,000 Records On-Chain Using Merkle Proofs

content/posts/hiero-graduation-with-further-reading.md

@@ -52,7 +52,7 @@ Graduation confirms that Hiero has achieved LFDT’s highest standards for:
 - **Neutral governance** and diverse community leadership.
 - **Production readiness** with enterprise-grade deployments (including powering the Hedera mainnet since February 2025).
 - **Security and compliance** with OpenSSF, GitHub Insights, and CI/CD best practices.
-- **Growing adoption** by enterprises, developers, and public sector innovators. [More Information](https://github.com/hiero-ledger/hiero/blob/main/ADOPTERS.md)
+- **Growing adoption** by enterprises, developers, and public sector innovators. [More Information](https://github.com/hiero-ledger/governance/blob/main/ADOPTERS.md)
 
 ---
 

content/posts/hiero-hacktoberfest-2025.md

@@ -28,13 +28,13 @@ This year, the Hiero project is excited to take part and welcome contributors of
 ## Get Started with Hiero
 
 We’ve prepared a set of issues that are perfect for newcomers to our project. You can find them in any repo in our [Hiero GitHub organization](https://github.com/hiero-ledger)
-under the label [good first issue](https://github.com/issues?q=is%3Aopen+is%3Aissue+org%3Ahiero-ledger+archived%3Afalse+label%3A%22good+first+issue%22+).
+under the label [good first issue](https://github.com/search?q=org%3Ahiero-ledger+label%3A%22good+first+issue%22+state%3Aopen&type=issues).
 
 These issues are designed to be approachable and are a great way to learn how Hiero works while making a meaningful contribution.
 
 ## Guidelines for Good First Issues
 
-To keep the experience smooth for both contributors and maintainers, we’ve documented clear [guidelines for creating and reviewing good first issues](https://github.com/hiero-ledger/governance/blob/main/guidelines/good-first-issues.md).
+To keep the experience smooth for both contributors and maintainers, we’ve documented clear [guidelines for creating and reviewing good first issues](https://github.com/hiero-ledger/governance/blob/main/rules-and-guidelines/good-first-issues.md).
 We encourage you to check them out and we welcome you to create more issues that new contributors can pick up.
 
 ## Why Contribute?