Pointing to a directory (#736)

maoueh · web-flow · commit f3c6ee2ee5f9 · 2025-12-30T12:27:10.000-05:00
* Pointing to a directory

* And now two pages pointing to the same markdown file

* Added better Gitbook validation and now ran through CI
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -14,10 +14,10 @@ jobs:
   test:
     name: Test
     runs-on: ${{ matrix.os }}
-    if: "${{ !startsWith(github.event.head_commit.message, 'GitBook: [#') }}"
+    if: "!startsWith(github.event.head_commit.message, 'GitBook: [#')"
     strategy:
       matrix:
-        go-version: [ 1.24.x ]
+        go-version: [1.24.x]
         os: [ubuntu-latest, macos-latest]
     steps:
       - name: Set up Go
@@ -43,6 +43,9 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-go-
 
+      - name: Validate GitBook
+        run: go run ./docs/.gitbook/validate.go
+
       - name: Run Tests
         run: ./bin/test.sh
 
diff --git a/docs/.gitbook/validate.go b/docs/.gitbook/validate.go
@@ -40,7 +40,11 @@ func main() {
 	validSummary := validateAllFilesAreInSummary(docsRoot)
 
 	fmt.Println("")
-	if validReferences && validSummary {
+	fmt.Println("Checking for duplicate file references in SUMMARY.md...")
+	validUniqueSummary := validateSummaryNoDuplicates(docsRoot)
+
+	fmt.Println("")
+	if validReferences && validSummary && validUniqueSummary {
 		fmt.Println("🎉 All documentation checks passed!")
 		os.Exit(0)
 	} else {
@@ -96,6 +100,57 @@ func validateLocalReferences(docsRoot string) bool {
 	return true
 }
 
+func validateSummaryNoDuplicates(docsRoot string) bool {
+	cwd, err := os.Getwd()
+	cli.NoError(err, "Unable to get current working directory")
+
+	summaryPath := filepath.Join(docsRoot, "SUMMARY.md")
+	summaryContent, err := os.ReadFile(summaryPath)
+	cli.NoError(err, "Unable to read SUMMARY.md", zap.String("path", summaryPath))
+
+	summaryLinks := extractMarkdownLinks(summaryPath, string(summaryContent))
+
+	// Track which files appear and where
+	fileOccurrences := make(map[string][]MarkdownLink)
+	for _, link := range summaryLinks {
+		if link.TargetFilePath != nil {
+			fileOccurrences[*link.TargetFilePath] = append(fileOccurrences[*link.TargetFilePath], link)
+		}
+	}
+
+	// Find duplicates
+	duplicates := []string{}
+	for filePath, occurrences := range fileOccurrences {
+		if len(occurrences) > 1 {
+			duplicates = append(duplicates, filePath)
+		}
+	}
+
+	if len(duplicates) == 0 {
+		fmt.Println("✓ No duplicate file references in SUMMARY.md!")
+		return true
+	}
+
+	fmt.Printf("\n❌ Found %d files referenced multiple times in SUMMARY.md:\n\n", len(duplicates))
+	for _, filePath := range duplicates {
+		relPath, err := filepath.Rel(cwd, filePath)
+		if err != nil {
+			relPath = filePath
+		}
+		fmt.Printf("  • %s (referenced %d times):\n", relPath, len(fileOccurrences[filePath]))
+		for _, link := range fileOccurrences[filePath] {
+			relSummaryPath, err := filepath.Rel(cwd, summaryPath)
+			if err != nil {
+				relSummaryPath = summaryPath
+			}
+			fmt.Printf("    - %s:%d - [%s](%s)\n", relSummaryPath, link.LineNumber, link.LinkText, link.LinkPath)
+		}
+		fmt.Println()
+	}
+
+	return false
+}
+
 func validateAllFilesAreInSummary(docsRoot string) bool {
 	sourceFiles, err := extractAllSourceFiles(docsRoot)
 	cli.NoError(err, "Unable to extract all source files")
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -25,7 +25,7 @@
 * [Install Substreams CLI](how-to-guides/cli/installing-the-cli.md)
   * [Substreams CLI Authentication](how-to-guides/cli/authentication.md)
 * [Developing Substreams](how-to-guides/develop-your-own-substreams/develop-your-own-substreams.md)
-  * [on EVM](how-to-guides/develop-your-own-substreams/on-evm/README.md)
+  * [on EVM](how-to-guides/develop-your-own-substreams/evm)
     * [Exploring Ethereum](how-to-guides/develop-your-own-substreams/evm/exploring-ethereum/exploring-ethereum.md)
       * [Filter Transactions](how-to-guides/develop-your-own-substreams/evm/exploring-ethereum/map_filter_transactions_module.md)
       * [Retrieve Events of a Smart Contract](how-to-guides/develop-your-own-substreams/evm/exploring-ethereum/map_contract_events_module.md)
@@ -71,13 +71,13 @@
 ## Reference Material
 
 * [CLI Reference](references/cli/command-line-interface.md)
-* [Core Concepts](references/architecture.md)
+* Core Concepts
   * [Architecture & Parallel Execution](references/architecture.md)
   * [Foundational Stores](references/foundational-store-reference.md)
   * [Module Concepts](references/substreams-components/modules/modules.md)
   * [Reliability Guarantees](references/reliability-guarantees.md)
   * [FAQ](references/faq.md)
-* [Manifest & Components](references/substreams-components/manifests.md)
+* Manifest & Components
   * [Manifests](references/substreams-components/manifests.md)
   * [Packages](references/substreams-components/packages.md)
   * [Module Types](references/substreams-components/modules/types.md)
@@ -89,7 +89,7 @@
   * [Parameterized Modules](references/substreams-components/modules/parameterized-modules.md)
   * [Dynamic Data Sources](references/substreams-components/modules/dynamic-data-sources.md)
   * [Aggregation Windows](references/substreams-components/modules/aggregation-windows.md)
-* [Chain Support](references/chains-and-endpoints.md)
+* Chain Support
   * [Chains & Endpoints](references/chains-and-endpoints.md)
   * [Ethereum Data Model](references/ethereum-data-model.md)
   * [Flashblocks support](references/flashblocks.md)
@@ -100,7 +100,7 @@
     * [Reorg Handling](references/sql/reorg-handling.md)
 * Operators
   * [Hosting Foundational Stores](./references/foundational-stores/hosting-foundational-stores.md)
-* [Development Tools](references/log-and-debug.md)
+* Development Tools
   * [Logging & Debugging](references/log-and-debug.md)
   * [Dev Container Reference](references/devcontainer-ref.md)
 * [Change log](release-notes/change-log.md)
diff --git a/docs/release-notes/change-log.md b/docs/release-notes/change-log.md
@@ -25,7 +25,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 * commands `run` and `sink webhook` now support these flags:
   - `--include-partial-blocks`: sends every block as partial(s) but also as real block
   - `--partial-blocks-only`: only sends partials (for every block, every bit of data should be there)
-  
+
 ### Sink library
 
 * To use the new partial blocks in a sink that uses github.com/streamingfast/substreams/sink, simply:
@@ -269,7 +269,7 @@ People using their own authentication layer will need to consider these changes
 
 * **Improved** Improved `substreams build`, `substreams protogen` and `substreams pack` command outputs to be streamlined and condensed.
 * **Added** support for reading manifest from stdin across all manifest-accepting commands using `"-"` as the manifest path. Affected commands: `build`, `run`, `gui`, `info`, `graph`, `pack`, `protogen`. This enables dynamic manifest generation and preprocessing workflows, including integration with tools like `envsubst` for environment variable substitution and CI/CD pipeline automation.
-* **Added** `substreams sink webhook` command to send Substreams output to a webhook endpoint. See [the documentation](./sink/webhook/README.md) for more information.
+* **Added** `substreams sink webhook` command to send Substreams output to a webhook endpoint. See [the documentation](../how-to-guides/sinks/) for more information.
 * Changed `substreams-api-token-envvar` flag to `api-token-envvar`
 * Changed `substreams-api-key-envvar` flag to `api-key-envvar`
 
