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.

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
  • When you encounter an empty link like [missing link](), always find and set the correct URL

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

Important Notes ​

  • All documentation is public
  • Keep content customer-focused
  • Test all links before deploying
  • Optimize images for web
  • Use consistent formatting
  • Coordinate with product updates

Releases ​

  • Update release notes regularly
  • When adding a release note, always look at existing documentation to find a potential link. If a link is found, link the relevant part of the text to the documentation, 4 words max linked. The link may contain an anchor to link to the right paragraph.
  • coordinate with the monthly newsletter process documented in @services/business/product-update/CLAUDE.md

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