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

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions