Skip to content

API Documentation Guide

Last Updated March 31, 2025

Guide

Developer FAQs

How is the project structured?

File Structure

Starlight looks for .md or .mdx files in the src/content/docs/ directory. Each file is exposed as a route based on its file name.

Images can be added to src/assets/ and embedded in Markdown with a relative link.

Static assets, like favicons, can be placed in the public/ directory.

Directorypublic favicons and other static assets
- …
Directorysrc
- Directoryassets Images for doc pages
  - …
- Directorycomponents Custom components
  - DirectoryGraphQLExplorer
    GraphQLExplorer.astro Main file of the GraphQL Explorer component
    …
  - Directoryui shadcn/ui components
    …
  - …
- Directorycontent
  - Directorydocs mdx files that generates doc pages
    Directoryapi
    DirectoryGraphQL
    DirectorySchema Data schemas
    …
    …
    Directoryguides Guides and tutorials
    …
    getting-started.mdx
    …
    Directorycontributing Contributing guidelines
    …
    Directoryit Italian translations
    …
    Directorylibrarians Librarian guides
    …
    ui.json translations for any UI strings
- Directorylayouts Layouts for doc pages
  - documentation.astro Main layout for doc pages
  - …
astro.config.mjs Astro configuration file
components.json shadcn/ui components
CONTRIBUTING Contributing guidelines
DEVELOPERS.md Developer FAQs
tailwind.config.mjs Tailwind CSS configuration
…

How do I run the project locally?

🚀 Quick Start

Clone the repo:

git clone https://github.com/hardcoverapp/hardcover-docs.git

Navigate to the project directory:

cd hardcover-docs

Install dependencies:

npm install

Start the dev server:

npm run dev

Open your browser
Navigate to http://localhost:4321

🧞 Commands

The Hardcover documentation site is built with Astro. All commands are run from the root of the project, from a terminal:

Command	Action
`npm install`	Installs dependencies
`npm run dev`	Starts local dev server at `localhost:4321`
`npm run build`	Build your production site to `./dist/`
`npm run preview`	Preview your build locally, before deploying
`npm run astro ...`	Run CLI commands like `astro add`, `astro check`
`npm run astro -- --help`	Get help using the Astro CLI
`npx vitest`	Run the unit tests for the project
`npx vitest --coverage.enabled true`	Run the unit tests with code coverage

How do I add a new page or update an existing page?

Adding a New Page

Create a new .mdx file in the src/content/docs/ directory.
Give the file a name that describes the content.
Add frontmatter to the top of the file.
Add content to the file using Markdown or MDX syntax.
Add the new page to the sidebar

If the page is part of the api/GraphQL/Schema or guides sections the sidebar will automatically update with the new page.
All other pages will need to be added to the astro config file see Starlight - Add links and link groups for more information.

Page Frontmatter

Moved to Frontmatter

Available Components

Moved to Astro Components for Astro components and React Components for React components.

Translating Content

Moved to Translating Documentation Guide

Support Resources

Submitting a Bug Report

Requesting a Feature

Finding Help on Discord

Connect with us on Discord