Skip to content
Zoos GlobalZoos GlobalZoos EngineeringHub

documentation

README documentation for documentation

stableRepositoryAstroprivate
4 min readUpdated Jul 24, 2026@devex-teamDeveloper Experience
Edit source

Source: ZoosGlobal/documentation Visibility: Private This page is automatically synchronized from the repository README. Do not edit this generated file directly.

Zoos Global Documentation Portal

Section titled “Zoos Global Documentation Portal”

Welcome to the internal engineering, infrastructure, and operational documentation portal for Zoos Global. This portal serves as the single source of truth for our technical workflows, guidelines, architectural patterns, and corporate policies.

Built using Astro and Starlight, the site is designed to be highly performant, searchable, and easy to update.

📂 Project Structure

Section titled “📂 Project Structure”

The project conforms to the following layout:

zoosglobal-docs/
├── .github/
│   └── workflows/
│       └── sync-readmes.yml        # CI/CD GitHub Actions workflow for sync
├── public/
│   └── favicon.svg                 # Browser favicon
├── src/
│   ├── assets/
│   │   └── logo.png                # Corporate brand logo
│   ├── components/
│   │   ├── overrides/              # Starlight component overrides (Header, Sidebar, PageTitle, ...)
│   │   ├── home/                   # Homepage widgets (Hero, StatCard, CategoryCard, ...)
│   │   ├── repo/                   # Repository catalog card
│   │   ├── page/                   # Per-document chrome (Breadcrumbs, MetaBar, RelatedDocs, ...)
│   │   ├── sidebar/                # Left navigation tree renderer
│   │   ├── search/                 # Pagefind search enhancements (recent/popular searches)
│   │   ├── mdx/                    # Reusable authoring components (Timeline, Checklist, ...)
│   │   └── Icon.astro              # Shared inline icon set
│   ├── data/
│   │   └── announcements.ts        # Homepage "Engineering announcements" — edit directly to publish
│   ├── lib/
│   │   ├── docs.ts                 # Shared content helpers (formatting, icons, category metadata)
│   │   └── homepage.ts             # Homepage data aggregation (recent, pinned, health stats)
│   ├── pages/
│   │   ├── index.astro             # Custom homepage ("Engineering Command Center")
│   │   ├── browse/[category].astro # Category listing pages
│   │   └── repositories/index.astro# Repository catalog
│   ├── scripts/
│   │   └── local-store.ts          # localStorage helpers (favorites, recently viewed)
│   ├── styles/
│   │   ├── tokens.css              # Design tokens (color, type, spacing, motion)
│   │   └── custom.css              # Global chrome + markdown content restyling
│   └── content/
│       └── docs/
│           ├── getting-started/    # Onboarding & workstation setup guides
│           ├── engineering/        # Architecture, deployment, standards & the component library
│           ├── devops/             # AWS structure, Terraform, & Datadog
│           ├── policies/           # Security policies & access control
│           └── repositories/       # [Generated] Synchronized GitHub READMEs
├── scripts/
│   └── sync-github-readmes.mjs     # Node.js sync script for GitHub READMEs
├── astro.config.mjs                # Astro & Starlight configuration
├── package.json                    # Project metadata & dependency definitions
└── README.md                       # This file

The homepage and repository catalog are built as custom Astro pages (via Starlight’s <StarlightPage> API) rather than Markdown, so they can pull live data — recently updated docs, documentation coverage, pinned pages — instead of being hand-maintained. Regular content pages keep using Markdown/MDX under src/content/docs/ exactly as before.

Frontmatter reference

Section titled “Frontmatter reference”

Every document under src/content/docs/ supports a richer, fully optional frontmatter schema (defined in src/content.config.ts) that powers the homepage widgets, meta bar and search facets: docType, status, category, tags, owner, team, environment, difficulty, docVersion, related, pinned, and featured. See src/content/docs/engineering/component-library.mdx for a live reference of every reusable authoring component (callouts, tabs, timelines, checklists, decision trees, service cards, and more).

🛠️ Getting Started

Section titled “🛠️ Getting Started”

Prerequisites

Section titled “Prerequisites”

Make sure you have the following installed on your machine:

  • Node.js: v20 or newer (LTS recommended)
  • npm: Installed with Node.js

1. Installation

Section titled “1. Installation”

Clone the repository and install the dependencies from the root directory:

Terminal window
npm install

2. Run the Development Server

Section titled “2. Run the Development Server”

Start the local development server to preview pages:

Terminal window
npm run dev

By default, the documentation will be accessible at http://localhost:4321.

3. Build for Production

Section titled “3. Build for Production”

To compile a static production build into the ./dist/ directory:

Terminal window
npm run build

🔄 Repository README Synchronization

Section titled “🔄 Repository README Synchronization”

The portal features an automated synchronization pipeline that pulls README files from all active repositories in the ZoosGlobal GitHub organization and places them under the Repositories section.

Manual Sync

Section titled “Manual Sync”

To run the sync script locally, you must provide a read-only GitHub token with access to the organization’s repositories:

Terminal window
export GITHUB_READ_TOKEN="your_github_token"
npm run sync:readmes

Automated Sync

Section titled “Automated Sync”

A GitHub Action is configured at .github/workflows/sync-readmes.yml which:

  1. Runs automatically every 6 hours.
  2. Pulls the latest READMEs from the organization.
  3. Automatically commits and pushes changes back to this repository.

⚙️ Development Guidelines

Section titled “⚙️ Development Guidelines”
  • Adding Content: To add new static documentation, create a Markdown (.md) or MDX (.mdx) file under the corresponding sub-folder in src/content/docs/. Add category/tags/owner frontmatter so it surfaces correctly in search, the homepage and /browse/<category>/.
  • Configuring Sidebar: Category groupings and ordering are managed automatically by folder routing configuration inside astro.config.mjs.
  • Reusable Components: Use the components documented in src/content/docs/engineering/component-library.mdx (info cards, timelines, checklists, decision trees, service cards, terminal blocks) instead of hand-rolling new UI in content pages.
  • Mermaid Diagrams: Not wired up yet — rendering Mermaid requires adding a remark/rehype plugin (e.g. rehype-mermaid) to astro.config.mjs.

Maintained by the Zoos Global Engineering Team. If you have any questions or find any outdated information, please open a PR or reach out in the #docs-feedback Slack channel.