Quick Start
Getting Started with Hexta AI
Introduction
Hexta AI (Voice Intelligence Platform) is a documentation framework, designed to be fast, flexible, and composes seamlessly into your React framework. It consists of multiple layers:
Hexta AI (Voice Intelligence Platform) is a documentation framework, designed to be fast, flexible, and composes seamlessly into your React framework. It consists of multiple layers:
Hexta AI (Voice Intelligence Platform) is a documentation framework, designed to be fast, flexible, and composes seamlessly into your React framework. It consists of multiple layers:
MDX is not the only supported format of Hexta AI. You can use any renderer such as a headless CMS.
See Custom Content Source for details.
Hexta Core
Handles most of the logic, including document search, content source adapters, and Markdown extensions.
Hexta Docs
The default theme of Hexta AI offers a beautiful look for documentation sites and interactive components.
Content Source
The source of your content, can be a CMS or local data layers like Hexta MDX (the official content source).
Hexta CLI
A command line tool to install UI components and automate things, useful for customizing layouts.
Want to learn more?
Read our in-depth What is Hexta AI introduction.
Terminology
Markdown/MDX: Markdown is a markup language for creating formatted text. Hexta AI natively supports Markdown and MDX (superset of Markdown).
Bun: A JavaScript runtime, it will be used in our guides for running scripts. If you prefer Node.js, try unrun instead.
Some basic knowledge of React.js would be useful for further customizations.
Love Hexta AI but not familiar with React?
Hextapress is a site generator that has lower barrier for beginners. It enforces a React framework of its own, and offers a better DX in return.
Automatic Installation
A minimum version of Node.js 22 required.
npm create hexta-appIt will ask you the built-in template to use:
- Framework: Next.js, Astro (with React), Waku, React Router, Tanstack Start.
- Content source: Hexta MDX.
A new hexta app should be initialized, with following features configured by default:
From Existing Codebase?
You can follow the Manual Installation guide to get started.
Enjoy!
Create your first MDX file in the docs folder.
---
title: Hello World
---
## Hi! what's upRun the app in development mode and see http://localhost:3000/docs.
npm run devFAQ
Some common questions you may encounter.
Make sure to upgrade Hexta AI when you've encountered any problems or trying out new features:
pnpm update -i -r --latestRouting is handled by your React framework, you need to change the routing structure first.
For example, in Next.js, rename the route (/docs/* -> /info/*):
Or rename from /docs/* to /* using a route group:
Finally, update the base URL of pages in source.ts:
import { loader } from 'hexta-core/source';
export const source = loader({
baseUrl: '/info', // to the new value
});We recommend using Layout Tabs.
For Vite
There's some weird pre-bundling problems with Vite: #3910.
Make sure to exclude Hexta AI from pre-bundling and add it to noExternal:
import { defineConfig } from 'vite';
export default defineConfig({
resolve: {
// add other Hexta AI deps as needed
noExternal: ['hexta-core', 'hexta-ui', 'hexta-openapi', '@hexta/base-ui'],
},
});For Next.js
If you have similar Turbopack errors like:
JSON file not found: FileSystemPath { ... path: "lib/locales/sources/file.json.json" }It is usually because require(esm) is not supported (#3312), please upgrade to Node.js 22+.
On Node.js 23.1, if you encountered this error in production build:
Could not find a production build in the '.next' directory.It is a known problem, see #1021, you can upgrade your Node.js version to 23.6.0+.
Next.js turns dynamic route into static routes when generateStaticParams is configured.
Hence, it is as fast as static pages.
You can enable Static Exports on Next.js to get a static build output.
Same as managing layouts in Next.js App Router, remove the original MDX file from content directory (/content/docs).
This ensures duplicated pages will not cause errors.
Now, You can add the page to another route group, which isn't a descendant of docs layout.
For example, to replace /docs/test:
For /docs, you need to change the catch-all route to be non-optional:
Learn More
Are you new to here? Don't worry, we are welcome for your questions.
If you find anything confusing, please give your feedback on Hexta AI!
Writing Content
For authoring docs, make sure to read:
Markdown
Hexta AI has some additional features for authoring content.
Navigation
Learn how to customize navigation structure.
Page Slugs & Page Tree
Learn how to organise content.
Components
See all available components to enhance your docs
Special Needs
How is this guide?