Skip to content

Update "Setup your docs environment" instructions to match current repo layout #1964

Description

@zachcasper

Summary

The Setup your docs environment section in the docs contribution guide is out of date and points contributors to a Docsy theme directory that no longer exists in this repository layout.

Problem

The guide currently instructs contributors to run:

cd docs
git submodule update --init --recursive
npm install
cd themes/docsy
npm install
cd ..

In the current radius-project/docs repository:

  • there is no themes/docsy directory
  • npm install fails at the repository root because package.json is not there
  • the actual Node project lives under docs/docs
  • Docsy is brought in via Hugo Modules rather than a checked-in theme folder
  • npm run dev fails because no dev script is defined in docs/package.json

This causes a confusing setup experience for contributors following the documented steps.

Evidence

A local reproduction following the current guide shows:

  • npm install fails in docs/ with ENOENT because package.json is missing
  • cd themes/docsy fails with no such file or directory
  • npm ci succeeds after changing into docs/docs
  • npm start successfully launches the local Hugo server from docs/docs
  • npm run dev fails because no dev script is defined

Suggested update

Revise the setup steps to match the current repository structure and Hugo Module-based theme usage. At minimum, update the instructions to:

  1. clone the repos as needed
  2. generate CLI docs
  3. change into docs/docs
  4. run npm ci
  5. run npm start from docs/docs
  6. remove the themes/docsy initialization step
  7. remove references to npm run dev where no such script exists

Likely files to update

  • docs/content/contributing/contributing-docs/index.md
  • docs/README.md
  • potentially any linked docs pages that duplicate the same outdated setup sequence

Acceptance criteria

  • setup instructions no longer reference themes/docsy
  • setup instructions use the correct working directory for npm commands
  • setup instructions use commands that exist in docs/package.json
  • a contributor can follow the documented steps from a fresh clone without hitting missing-directory or missing-package.json errors
  • the contribution guide reflects the current Hugo Modules/Docsy setup

Metadata

Metadata

Labels

No labels
No labels

Type

Fields

No fields configured for Bug.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions