Garnet Marketplace

Appearance

Docs Service ​

Customer-facing documentation site built with VitePress.

Overview ​

The docs service is Garnet's official documentation website, providing comprehensive guides, tutorials, and reference materials for marketplace operators and vendors.

Technology Stack ​

  • Framework: VitePress (Vue.js-based static site generator)
  • Language: Markdown with TypeScript
  • Styling: CSS
  • Build: Vite
  • Deployment: AWS (Serverless)

Project Structure ​

.
├── .vitepress/          # VitePress configuration
│   ├── config.ts       # Site configuration and navigation
│   └── theme/          # Custom theme components
├── get-started/         # Getting started guides
├── accounts/            # Account management docs
├── orders/             # Order management guides
├── listings/           # Product listing documentation
├── integrations/       # Platform integration guides
├── shipping/           # Shipping documentation
├── finance/            # Finance and payout guides
├── settings/           # Settings documentation
├── appearance/         # Marketplace appearance customization
├── custom-pages/       # Custom page documentation
├── notifications/      # Notification settings
├── messaging/          # Customer messaging
├── administration/     # Admin features
├── customizations/     # Advanced customizations
├── vendor-guide/       # Vendor-specific guides
├── releases/           # Release notes (current year)
├── releases-2024/      # 2024 release notes archive
├── blog/              # Blog posts
├── faq/               # Frequently asked questions
├── public/            # Static assets (images, etc.)
├── index.md           # Homepage
└── serverless.yml     # AWS deployment config

Development Commands ​

bash
pnpm start        # Start dev server on port 3010
pnpm build        # Build static site to dist/
pnpm preview      # Preview production build
pnpm test         # Run validation tests
pnpm deploy-prod  # Build and deploy to production

Writing Documentation ​

File Structure ​

  • Each page is a Markdown (.md) file
  • Organize pages in topic-based directories
  • Use kebab-case for file names: my-page.md
  • Add frontmatter for metadata

Frontmatter Example ​

markdown
---
title: Page Title
description: Brief description for SEO
---

# Page Content

Edit .vitepress/config.ts to add pages to navigation:

  • sidebar: Left sidebar navigation
  • nav: Top navigation bar

Images ​

  • Place images in public/ directory
  • Reference as /path/to/image.png
  • Optimize images before committing
  • Use descriptive alt text
  • Use relative links for internal pages: [Link Text](./other-page.md)
  • Use absolute URLs for external links
  • Links are validated in tests

Release Notes ​

Two directories for release notes:

  • releases/: Current year release notes
  • releases-2024/: Archived 2024 release notes

Each release note should:

  • Include date in format: YYYY-MM-DD
  • Have clear title describing the feature
  • Include screenshots or images when possible
  • Link to relevant documentation pages

Testing ​

Run automated tests before deploying:

bash
pnpm test

Tests check for:

  • Broken internal links
  • Missing page descriptions
  • Invalid frontmatter

Building ​

VitePress generates a static site:

bash
pnpm build

Output in dist/ directory ready for deployment.

Deployment ​

Deployed to AWS using Serverless Framework:

bash
pnpm deploy-prod

This will:

  1. Build the static site
  2. Upload to S3
  3. Configure CloudFront distribution
  4. Deploy via serverless.yml

Custom Theme ​

Custom theme components in .vitepress/theme/:

  • Vue components for custom layouts
  • Global styles
  • Theme overrides

Content Guidelines ​

  • Clear and Concise: Use simple language
  • Screenshots: Include visuals for UI features
  • Step-by-Step: Break down complex processes
  • Examples: Provide real-world examples
  • Search-Friendly: Use descriptive titles and headings
  • Up-to-Date: Keep content synchronized with product changes

Important Notes ​

  • All documentation is public
  • Keep content customer-focused
  • Test all links before deploying
  • Optimize images for web
  • Use consistent formatting
  • Update release notes regularly - when creating release notes, coordinate with the monthly newsletter process documented in @services/business/product-update/CLAUDE.md
  • Coordinate with product updates

Site Configuration ​

Main configuration in .vitepress/config.ts:

  • Site metadata
  • Navigation structure
  • Plugin configuration
  • Build options
  • Theme settings

URL Structure ​

Documentation is served at: https://garnetmarketplace.com/docs/

  • Clean URLs without .html extension
  • SEO-optimized
  • Sitemap generated automatically