HermesDocs HermesDocs
v2
Edit on GitHub

Getting Started

Get up and running with Hermes in minutes

5 min read

Getting Started

Welcome to Hermes - a professional, production-ready documentation website kit built with Astro. This guide will help you get started with building your documentation site in just a few minutes.

What is Hermes?

Hermes is a complete documentation template designed for:

  • Developer tools and APIs
  • SDKs and libraries
  • SaaS products with documentation needs
  • Open-source projects
  • AI tools and platforms

It comes with everything you need out of the box: search, dark mode, versioning, MDX support, and more.

Prerequisites

Before you begin, make sure you have:

  • Node.js 18+ installed (Download Node.js)
  • A package manager (npm, yarn, or pnpm)
  • A code editor (VS Code recommended)
  • Basic familiarity with Markdown and JavaScript/TypeScript

Quick Start

1. Clone or Download

If you’re using this as a template:

git clone https://github.com/mrebati/hermes-docs-kit.git
cd hermes-docs-kit

Or if you’ve purchased/downloaded the kit, extract it and navigate to the directory.

2. Install Dependencies

Choose your preferred package manager:

# Using npm
npm install

# Using yarn
yarn install

# Using pnpm (recommended)
pnpm install

3. Start the Development Server

npm run dev
# or
yarn dev
# or
pnpm dev

The development server will start at http://localhost:4321. Open this URL in your browser to see your documentation site.

4. Make Your First Change

  1. Open src/content/docs/getting-started.mdx (this file!)
  2. Make a small edit to see the changes live
  3. The page will automatically reload in your browser

🎉 Congratulations! You’re now running Hermes locally.

Project Structure

Understanding the project structure will help you customize your documentation:

hermes-docs-kit/
├── src/
│   ├── components/          # Reusable Astro components
│   │   ├── mdx/            # MDX-specific components (Callout, Tabs, etc.)
│   │   ├── Header.astro    # Site header
│   │   ├── Footer.astro    # Site footer
│   │   ├── Sidebar.astro   # Navigation sidebar
│   │   └── ...             # Other components
│   ├── content/             # Your documentation content
│   │   ├── docs/           # Documentation pages (.mdx files)
│   │   └── blog/           # Blog posts (optional)
│   ├── layouts/            # Page layouts
│   │   ├── BaseLayout.astro
│   │   └── DocLayout.astro
│   ├── lib/                # Utility functions
│   │   ├── navigation.ts   # Navigation helpers
│   │   ├── search.ts       # Search functionality
│   │   └── utils.ts        # General utilities
│   ├── pages/              # Astro pages (routing)
│   │   ├── index.astro     # Homepage
│   │   ├── docs/           # Documentation pages
│   │   └── blog/           # Blog pages
│   ├── styles/             # Global styles
│   └── config.ts           # Site configuration
├── public/                 # Static assets (images, favicons, etc.)
├── astro.config.mjs        # Astro configuration
├── tailwind.config.mjs     # Tailwind CSS configuration
└── package.json            # Dependencies and scripts

Customization

Update Site Information

Edit src/config.ts to customize your site:

export const siteConfig = {
  name: 'Your Project Name',
  title: 'Your Documentation',
  description: 'Your project description',
  url: 'https://your-domain.com',
  author: {
    name: 'Your Name',
    email: 'your@email.com',
    url: 'https://yourwebsite.com',
  },
  github: {
    repo: 'your-username/your-repo',
    editBaseUrl: 'https://github.com/your-username/your-repo/edit/main',
  },
  // ... more settings
};

Customize Colors

Edit tailwind.config.mjs to match your brand:

theme: {
  extend: {
    colors: {
      primary: {
        50: '#f0f9ff',
        100: '#e0f2fe',
        // ... customize your color palette
        900: '#0c4a6e',
      },
    },
  },
}
  1. Add your logo to public/logo.svg (or .png)
  2. Update src/components/Header.astro to use your logo

Creating Content

Add a New Documentation Page

Use the CLI script:

npm run new:page my-page-name

Or manually create a file in src/content/docs/:

---
title: My New Page
description: A brief description
order: 5
---

# My New Page

Your content here...

The page will automatically appear in the navigation sidebar based on the order field.

Using MDX Components

Hermes includes powerful MDX components. Here’s an example:

import { Callout, Tabs, CodeBlock } from '@components/mdx';

<Callout type="info" title="Pro Tip">
  This is an informational callout!
</Callout>

<Tabs items={['JavaScript', 'TypeScript', 'Python']}>
  <div>JavaScript code here</div>
  <div>TypeScript code here</div>
  <div>Python code here</div>
</Tabs>

See the API Reference for all available components.

Next Steps

Now that you’re set up, here’s what to do next:

  1. Read the Installation Guide for detailed setup instructions
  2. Check out the API Reference to learn about all features
  3. Explore the Guides for advanced customization
  4. Customize your site with your branding and content
  5. Deploy to Vercel, Netlify, or your preferred hosting platform

Getting Help

Common Questions

Q: How do I change the theme colors?
A: Edit tailwind.config.mjs and update the primary color palette.

Q: Can I use my own domain?
A: Yes! Update the url in src/config.ts and configure your hosting provider.

Q: How do I add search?
A: Search is enabled by default. For Algolia integration, see the Guides.

Q: Can I customize the navigation?
A: Yes! Navigation is auto-generated from your content files. Use the order and parent fields in frontmatter to organize it.

Ready to build something amazing? Let’s continue to the Installation Guide!