hashicorp / web-unified-docs

Web Unified Docs > [!IMPORTANT] > This README is for developers working on the documentation website. If you > want to contribute docs content, refer to the Contribute to HashiCorp > documentation guide. --- The project in this repository, , aims to implement [[DEVDOT-023] Unified Product Documentation Repository](https://docs.google.com/document/d/1p8kOqySttvWUVfn7qiC4wGBR73LMBGMelwLt69pM3FQ/edit). The RFC for this project was intentionally light on implementation details, in order to foster consensus on the broad direction. • **PR previews**: Show broken links in comments for awareness (informational only, don't block PRs) • **Production monitoring**: Weekly scans create GitHub issues and send critical alerts to Datadog when users are affected The weekly workflow generates comprehensive broken link reports with prioritization guidance. When contributors create PRs that modify content, the link checker shows any broken links in PR comments with actionable guidance without blocking development. **Quick tips for contributors**: • **Fix internal HashiCorp links** (high priority) • **Check external docs/API links** (medium priority) • **Consider removing unreliable external links** (low priority) For detailed information about the monitoring system, see Broken Link Monitoring Documentation. The Unified Product Documentation Repository RFC for this project was intentionally light on implementation details, in order to foster consensus on the broad direction. The existing API ( ) has endpoints that serve documentation content. You can find the source code in hashicorp/mktg-content-workflows. The goal of the unified docs API is to host all of HashiCorp's product documentation. The unified docs API will eventually replace the existing content API. Local development Requirements • Docker and Docker Compose (for managing containers) Quick start To get a migration preview running, run from the root of this repo. The command starts the Docker profile that spins up a local instance of and . Once this command completes, you can access the following endpoints: • http://localhost:3000 - An instance of the container configured to pull from the experimental docs API (this repo). This image depends on the unified docs API ( ). • http://localhost:8080 - An instance of the unified docs API container (this repo - ) that serves content from the directory. On startup, this container processes the content and assets in into and . In addition, the container also generates and from the contents within . Use the following example to test this endpoint: http://localhost:8080/api/content/terraform-plugin-framework/doc/latest/plugin/framework > [!NOTE] > The unified docs API container takes time to process the content and assets. You must wait for both the and containers to complete before you can successfully test content in the preview environment ( ). Visit http://localhost:8080/api/all-docs-paths to verify the container is complete. To spin this down gracefully, run in a separate terminal. If you wish to remove the local Docker images as well, run . More commands The serves as a convenience tool start the local preview. If you need more granular control, the file contains a full list of available commands. To use these, you will need to intentionally run and before anything else. Use to run coverage tests. Preview environments for unified-docs and dev-portal Unified docs API serves as one of the content APIs for (frontend application for DevDot). As a result, when implementing new features, you may need to modify both the backend (this repo) and the frontend ( ). If you are working on a ticket that requires changes to both the unified docs API and , please set custom environment variables for your branch in Vercel to simplify testing instructions. For example, in Vercel, for your branch, you can set the following environment variables: | Environment variable | Value | | -------------------- | ---------------------- | | | | | | | Vercel will use these values to create deploy previews. API development Reach out to team #team-web-presence if you need to do local API development Background Project Rationale • Storing documentation in one branch of one repo dramatically simplifies the workflow for contributing documentation. • Publishing changes to multiple versions can be done in a single PR, as opposed to multiple PRs which is required by the current setup. • Finding and making the same change across multiple versions is as simple as doing a find-and-replace since all the versioned docs are on the filesystem at the same time. • Adding a new product is as easy as making a new folder, as opposed to the current process which requires code-changes on the API side and the installation of a GitHub App to monitor for events. • Sourcing from one branch in one repo eliminates the situation where a missed GitHub event can result in out-of-date documentation. If something goes wrong in the publishing process, simply run it again instead of relying on incoming commit/release events from the GitHub API. • Since we can make edits to all docs for all products and versions from a single PR, making platform-level changes is dramatically simplified (such as updating to MDX v2, or rewriting URLs). • Adding new features like content conformance (basically linting for docs) can be done for the entire codebase at once. • Removes the ability for docs to break the release workflow in product repos. • Enables us to support fully versioned deployment previews, whereas current previews are limited to the branch being modified. Architectural Decision Records Update product repo documentation This script helps with product documentation migration to the web-unified-docs repository. When migrating documentation: • The repository becomes the source of truth • Original documentation may remain temporarily as a fallback • Users should be directed to make future changes in only This script automatically adds a pro…