API Documentation Guide

Ultimo Aggiornamento   3 gennaio 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

1. Clone the repo:

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

2. Navigate to the project directory:

cd hardcover-docs

3. Install dependencies:

npm install

4. Start the dev server:

npm run dev

5. Open your browser
6. 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

1. Create a new .mdx file in the src/content/docs/ directory.
2. Give the file a name that describes the content.
3. Add frontmatter to the top of the file.
4. Add content to the file using Markdown or MDX syntax.
5. 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.

How do I add a new language to the language dropdown?

The root language should not be changed from English. To add a new language, see Starlight - Configure i18n.

When adding a new language, you should also update the existing translations in the astro config file to include the new language.

How do I add a translation for an existing language?

Once a language has been added to the astro config file you can create a new file in the src/content/docs/ directory inside a folder named with the language code. This new file should have the same name as the original file you are translating.

For example, if you are translating the src/content/docs/getting-started.mdx file into Spanish you would create a new file at src/content/docs/es/getting-started.mdx with the Spanish translation of the content.

Support Resources

Submitting a Bug Report

Requesting a Feature

Finding Help on Discord

Connect with us on Discord