Skip to main content

Repository Setup

Working in the docs repo

This repo is the shared documentation layer for Builder Insights. It works best when it sits alongside the mobile and admin repos and stays focused on cross-repo architecture, workflows, screenshots, and operations.

Sibling repos

  • devrel-insights
  • devrel-insights-admin
  • devrel-insights-docs
Legacy naming

These repository names still use legacy devrel identifiers during the broader Builder Insights rename.

Local setup path​

1. Clone or open the repo

Place the docs repo near the application repos so cross-repo references stay easy to manage.

2. Install dependencies

Use the standard local setup flow before previewing or editing docs changes.

3. Run the docs site

Start the local Docusaurus server and confirm the major pages, diagrams, and screenshots render correctly.

cd /path/to/devrel-insights-docs
npm install
npm run start

Build verification​

npm run build

QA check

What to verify locally

  • the homepage and top-level docs render without layout regressions
  • Mermaid diagrams and illustration assets load correctly
  • navigation, screenshots, and internal links still work after edits

Screenshot automation​

Mobile screenshots

Source automation currently lives in the mobile app repo, where the capture fixtures and scripted flow are maintained.

Admin screenshots

This repo includes a hosted admin capture script so the shared docs can refresh portal screenshots directly.

npm run screenshots:admin

Default demo credentials are built into the admin script for the shared demo environment, but can be overridden with:

  • ADMIN_BASE_URL
  • ADMIN_DEMO_EMAIL
  • ADMIN_DEMO_CODE

Remote and hosting context​

  • Git remote: https://github.com/mongodb-developer/devrel-insights-docs.git
  • Update docusaurus.config.ts if hosting details, URL targets, or branding references change

Recommended content ownership​

Keep in this repo

Use the docs site for material that spans both apps or helps the organization understand the platform as a whole.

  • system-level architecture
  • cross-repo workflows
  • operational runbooks
  • screenshots and UX walkthroughs
  • release and testing checklists that touch both apps
Keep in app repos

Use code-local docs for information that changes directly with implementation details.

  • repo-specific setup instructions
  • fine-grained implementation notes
  • API details that evolve tightly with code
  • screen behavior notes that are not system-level documentation

Decision

Publishing note

Before first publish, decide whether the site is deployed with Vercel, GitHub Pages, or another static host, then keep `docusaurus.config.ts` aligned with that choice.