EDU-4420: Adds audit-stray-pages and updates READMEs

Erica Sadun · Erica Sadun · commit 4a835aaae359 · 2025-04-30T13:30:03.000-06:00
diff --git a/COMPONENTS.md b/COMPONENTS.md
@@ -21,6 +21,7 @@ Whether you’re using core components or experimenting with new ones, this guid
 - [Using CaptionedImage](#using-captionedimage)
 - [Using DiscoverableDisclosure](#using-discoverabledisclosure)
 - [Using DocsTable](#using-docstable)
+- [Using PhotoCarousel](#using-photocarousel)
 - [Using RelatedRead](#using-relatedread)
 - [Using ToolTipTerm](#using-tooltipterm)
 - [Using ZoomingImage](#using-zoomingimage)
@@ -39,39 +40,6 @@ Our components are located in the `src/components` folder at the root of this re
 - **`experimental`**: This folder contains components that are not currently used on the site.
   These are either for testing or were previously part of ongoing development.
 
-```
-components
-├── elements
-│   ├── Button.js
-│   ├── Intro.js
-│   ├── PhotoCarousel.js
-│   ├── RetrySimulator.js
-│   ├── SdkLogos.js
-│   └── retry-simulator.module.css
-├── experimental
-│   ├── CenteredImage.js
-│   ├── CustomWarning.js
-│   ├── DetermineHeader.js
-│   ├── InfoButton.js
-│   ├── NoBreak.js
-│   ├── ResponsivePlayer.js
-│   ├── RowOfImages.js
-│   ├── Spacer.js
-│   └── ToolTipText.js
-├── formatting
-│   └── DocsTable.js
-├── images
-│   ├── CaptionedImage.js
-│   └── CaptionedImage.module.css
-├── index.js
-└── info
-    ├── DiscoverableDisclosure.js
-    ├── RelatedRead.js
-    ├── RelatedRead.module.css
-    ├── RelatedReadList.js
-    └── ToolTipTerm.js
-```
-
 Components are reusable, self-contained units of code used for our Documentation site.
 As shown in this file tree, our components are built using JavaScript and React.
 Components often have associated CSS files to manage styling, although this is optional.
@@ -262,6 +230,44 @@ Archetypes:
 - feature-guide
 - feature-summary
 
+## Using PhotoCarousel
+
+Role: Provide annotated walk-through using an image carousel presentation with text.
+
+How to import:
+
+```
+import { PhotoCarousel } from '@site/src/components';
+```
+
+or 
+
+```
+import PhotoCarousel from "@site/src/components/elements/PhotoCarousel";
+```
+
+Usage:
+
+```
+<PhotoCarousel
+images={[
+"/link/to/image-1",
+"/link/to/image-2",
+...
+]}
+captions={[
+"caption-1",
+"caption-2",
+...
+]}
+/>
+```
+
+- If links are stored on-site, place images in static in an appropriately themed folder.
+- If links are stored off-site, use a fully specified URL
+- Please ensure the caption count and order matches that of the images
+- You may pass an optional `isDarkMode` Boolean prop
+
 ## Using ToolTipTerm
 
 Role: Provide definitions or background information at the point of use.
diff --git a/READABILITY.md b/READABILITY.md
@@ -1,6 +1,8 @@
 # Readability Tools
 
 This repository includes a small set of utilities to support content readability.
+These utilities are not meant for use by contributors.
+
 All tools are Bash scripts, located in the `bin/` directory at the root of this repository.
 These scripts help review and transform content to improve documentation processing.
 They are lightweight and designed to work within the content-creation and content-evaluation workflow.
diff --git a/README.md b/README.md
@@ -6,8 +6,15 @@ Welcome to Temporal's documentation repository!
 
 This repository contains a large chunk of the Temporal information corpus.
 
-- [Contributing guidance](./CONTRIBUTING.md)
-- [Style guidance](./STYLE.md)
+| Resource                                   | Audience                |
+|--------------------------------------------|--------------------------|
+| [Contact information](./CONTACT.md)        | For our open source community |
+| [Contributing guidance](./CONTRIBUTING.md) | For our open source community |
+| [License](./LICENSE.md) | For our open source community |
+| [React Component catalog and guidance](./COMPONENTS.md) | For our open source community |
+| [Readability tooling guidance](./READABILITY.md) | For repo maintainers |
+| [Style guidance](./STYLE.md)               | For our open source community |
+| [Utility tooling guidance](./UTILITIES.md) | For repo maintainers |
 
 ### Current component versioning philosophy
 
diff --git a/UTILITIES.md b/UTILITIES.md
@@ -0,0 +1,78 @@
+# Temporal Documentation Site Utilities
+
+This file documents utilities meant to support repository health.
+These utilities are not meant for use by contributors.
+
+## audit-stray-pages
+
+[**Docusaurus**](https://docusaurus.io) serves all files, whether they are mentioned in sidebars.js or not.
+[**Algolia**](https://algolia.com) will index these files so they show up in search, even though we intend to hide them.
+
+The `audit-stray-pages` utility audits unreferenced docs files so they can be evaluated and, if needed, hidden in Docusaurus.
+This script scans your Docusaurus project for `.md` and `.mdx` files in the top level `docs/` folder and reports the ones that are **not actively referenced** in your `sidebars.js` file. "Not actively referenced" includes:
+
+- Files that were commented out in sidebars.js
+- Files that are not included at all
+
+It helps you find:
+
+- Stray or deprecated documentation pages that aren’t in the site navigation
+- Files that are publicly accessible but unintentionally published
+- Gaps in `id:` usage where default IDs don’t match sidebar references
+
+You can hide Docusaurus files by setting them to drafts in the file metadata:
+
+```
+draft: true
+```
+
+Docusaurus will render drafts in preview mode but not production.
+
+**Please note**: 
+
+- Some "deprecated" files are left intentionally visible outside the normal navigation system and are linked from other pages.
+  They should not be set to draft as that breaks `yarn build` and will fail CI and Vercel deployment.
+- The sidebars.js file does not use `/path/to/file.mdx`.
+  It uses `/path/to/folder/your-file-id`, which uses the `id: your-file-id` declared in your mdx YAML frontmatter.
+- Slugs are not equivalent to ids.
+  Ids are used to stitch together the site.
+
+### What It Does
+
+1. **Parses `sidebars.js`** to extract all actively referenced doc IDs  
+   - Ignores lines that are commented out (`//` or `/* ... */`)
+2. **Extracts doc IDs** from sidebar references, including:
+   - Simple string references: `"foo/bar"`
+   - Object syntax: `{ type: 'doc', id: 'foo/bar' }`
+3. **Scans all `.md` and `.mdx` files** in the `docs/` directory:
+   - First checks if the file's path-derived ID is in the sidebar
+   - Then checks for a frontmatter `id:` override and searches that
+   - If neither is found, the file is flagged as unreferenced
+
+### Usage
+
+Save the script as `audit-stray-pages` and make it executable:
+
+```bash
+chmod +x audit-stray-pages
+./audit-stray-pages
+```
+
+### Work
+
+After running the script, review each unreferenced file carefully.
+
+- Some files may be intentionally excluded from the sidebar, such as deprecated pages or internal drafts.
+- Others may be unintentional omissions that should be added to sidebars.js.
+- Others are intentionally excluded but not referenced from anywhere on the site.
+  This is deliberate in the case of `tctl` pages.
+  This is accidental for other pages.
+
+For each flagged file, check whether it:
+
+- Should be deleted or archived
+- Should have a `draft: true` frontmatter added (Docusaurus v3+)
+- Needs a matching `id:` in the frontmatter
+- Belongs in `sidebars.js` but was accidentally left out or commented out
+
+This utility highlights potential issues—it’s up to you to decide what belongs in our published documentation.
diff --git a/bin/audit-stray-pages b/bin/audit-stray-pages
@@ -0,0 +1,40 @@
+#!/bin/bash
+
+SIDEBARS_FILE="sidebars.js"
+CLEANED_SIDEBAR="/tmp/cleaned_sidebars.txt"
+
+# 1. Preprocess sidebars.js
+# Remove // comments and /* block comments */
+sed '/^\s*\/\//d' "$SIDEBARS_FILE" | sed '/\/\*/,/\*\//d' > "$CLEANED_SIDEBAR"
+
+# 2. Extract IDs from cleaned sidebars
+# IDs can appear like "foo/bar" or id: "foo/bar"
+grep -oE '"[^"]+"' "$CLEANED_SIDEBAR" | tr -d '"' | sort | uniq > /tmp/sidebar_ids.txt
+
+# 3. Now audit all docs
+find docs \( -name "*.mdx" -o -name "*.md" \) | while read -r filepath; do
+  # Get default ID
+  default_id=$(echo "$filepath" | sed -E 's|^docs/||;s|\.mdx$||;s|\.md$||')
+
+  # Check if default_id is in the sidebar IDs
+  if grep -qxF "$default_id" /tmp/sidebar_ids.txt; then
+    continue
+  fi
+
+  # If not found, check for custom ID
+  custom_id=$(grep -m 1 '^id:' "$filepath" | sed 's/id:[[:space:]]*//' | tr -d '\r')
+  if [ -n "$custom_id" ]; then
+    custom_id=$(echo "$custom_id" | xargs)
+    if grep -qxF "$custom_id" /tmp/sidebar_ids.txt; then
+      continue
+    fi
+  fi
+
+  # Neither found — this is a potential stray file
+  # Removing something linked but deprecated will break the build
+  # Prefer to remove intentional items (commented out in sidebars.js)
+  # Investigate items that may be unintentional.
+  # Try to add slugs to all affected files that match the file names
+  # and search for those
+  echo "$filepath"
+done
