# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

# Project Overview

VuePress 1.x documentation site for Virtuoso (a test automation platform). Markdown content with Vue 2 components and Stylus styling. Deployed to AWS S3, served at docs.virtuoso.qa.

# Commands

This project uses npm. Never use yarn.

npm install      # Install dependencies
npm run dev      # Dev server with hot reload
npm run build    # Production build
npm run lint     # ESLint on .js/.vue files in .vuepress/

All scripts use NODE_OPTIONS=--openssl-legacy-provider (required for VuePress 1.x webpack compatibility).

# Architecture

# Content

/guide/ — Main documentation organized by topic area (getting-started, introduction-to-virtuoso, using-virtuoso, making-the-most-of-virtuoso, advanced-topics)
/library/ — API reference: /apps/ (integrations), /language-extensions/, /directives/

# VuePress Configuration (`.vuepress/`)

config.js — Central config: sidebar structure, nav, Algolia search, plugins, base path. Sidebar structure here determines navigation — new pages must be added to the sidebar config.
components/ — Vue components usable directly in markdown: VIcon, VBadge, Beta, Capabilities, Rapidoc (OpenAPI viewer), GettingStartedCard, etc.
styles/index.styl — Main styles including icomoon icon font definitions
styles/palette.styl — Color variables
enhanceApp.js — Legacy route redirects (e.g., integrations -> apps)
public/ — Static assets (icons, images, API spec files)

# Deployment

CircleCI (.circleci/config.yml) — Primary CI/CD:

master merges deploy to production S3
Other branches deploy to S3 under /branch/{branch-name}/ with VUEPRESS_BASE set accordingly
Uses AWS OIDC role assumption; requires PACKAGE_KEY env var for @spotqa GitHub npm registry

GitHub Actions (.github/workflows/):

update_api_docs.yml — Auto-generates API docs from virtuoso-api-client repo
update_crossbrowser_capabilities.yml — Fetches browser capabilities from Virtuoso API
compress-images.yml — Scheduled image compression (creates PR)
rebuild_algolia_index.yml — Manual trigger to rebuild search index

# Markdown Conventions

<VIcon name="icon-name" /> for inline icons
<VBadge type="tip|error|warning|info" text="..." /> for badges
<Beta /> for beta feature indicator
::: tip / ::: warning / ::: danger for callout blocks
Vue components can be embedded directly in markdown files
Tab groups via vuepress-plugin-tabs

# Linting

ESLint extends plugin:vue/essential, plugin:vue/recommended, @vue/standard. Key rules:

comma-dangle: always-multiline
vue/no-v-html: warn
Only .vuepress/ is linted (everything else is ignored via .eslintignore)

# Key Details

config.js base path is dynamic: process.env.VUEPRESS_BASE || '/' — branch deploys override this
Algolia search index: prod_DOCS_replica (in config), prod_DOCS_master (in docsearch scraper config)
Icon font (icomoon) is manually synced from the frontend repo — no automatic sync
deploy_docs.sh creates both directory and file S3 objects for folder emulation
Contributing guidelines live in the GitHub wiki: https://github.com/spotqa/virtuoso-docs/wiki/