How the Prompt Engineering Guide Repository Is Structured: A Complete Technical Breakdown

The Prompt Engineering Guide follows a Next.js/Nextra static-site architecture with multilingual MDX content in pages/, React components in components/, educational guides in guides/, and Jupyter notebooks in notebooks/, supporting 13 locales through file-based routing.

The dair-ai/Prompt-Engineering-Guide repository serves as the open-source engine behind one of the most comprehensive prompt engineering resources available today. Understanding this repository's structure is critical for contributors adding new techniques, maintaining translations, or extending the documentation platform. This analysis examines the exact file organization, internationalization setup, and component architecture as implemented in the source code.

High-Level Repository Architecture

The repository adheres to standard Next.js conventions while leveraging Nextra-specific patterns for documentation sites. The root directory houses configuration files, with content and functionality strictly compartmentalized into specialized folders.

Core Directory Layout

Directory	Purpose
pages/	Language-specific MDX documentation files (e.g., pages/tools.en.mdx, pages/techniques.zh.mdx)
components/	Reusable React UI components including components/pre.tsx and components/CopyPageDropdown.tsx
guides/	Long-form markdown tutorials covering prompt fundamentals and advanced usage
notebooks/	Interactive Jupyter notebooks including pe-lecture.ipynb and pe-rag.ipynb
ar-pages/	Arabic language translations mirroring the pages/ structure for RTL support
img/	Static images and infographics referenced throughout the documentation
public/	Static assets including favicons served from the domain root
.github/	Continuous integration workflow definitions

The Next.js configuration resides in next.config.js, which initializes the Nextra theme and registers the site's internationalization settings. TypeScript compiler options live in tsconfig.json, while theme.config.tsx centralizes visual settings including the logo, navigation hierarchy, language selector, and footer configuration.

Internationalization and Localization Strategy

The site supports 13 locales through a mirror-file routing system defined in next.config.js. The locales array explicitly lists: 'en', 'zh', 'jp', 'pt', 'tr', 'es', 'it', 'fr', 'kr', 'ca', 'fi', 'ru', 'de', and 'ar'.

Content files follow strict naming conventions: {topic}.{locale}.mdx. For example, English documentation resides in pages/tools.en.mdx, while Chinese translations live in pages/tools.zh.mdx. Arabic content utilizes a dedicated top-level ar-pages/ directory to accommodate RTL (right-to-left) layout requirements, though the internal file naming remains consistent with other languages.

The theme.config.tsx file registers these locales in the language selector UI, ensuring visitors can toggle between translations. This configuration must mirror the next.config.js locale array to maintain routing consistency across the Prompt Engineering Guide repository structure.

Content Organization Patterns

The repository separates educational material into three distinct layers: quick-reference documentation, in-depth guides, and executable code examples.

Documentation Pages

The pages/ directory contains the primary navigation structure rendered by Nextra. Each topic occupies a folder with language-specific MDX files. Nextra automatically generates sidebar navigation based on the file system hierarchy. For instance, pages/techniques.en.mdx renders at the /techniques route and appears in the English navigation menu.

These files use MDX syntax, allowing JSX components alongside standard Markdown. The components/pre.tsx component provides custom-styled code blocks, while components/word-wrap.tsx handles text overflow for long strings without breaking layouts.

Educational Guides

Longer, narrative-driven content lives in the guides/ directory as standard Markdown files. These include prompts-intro.md and prompts-advanced-usage.md, which cover conceptual material rather than quick-reference documentation. Unlike the MDX pages in pages/, these guides are not automatically routed by Nextra and are typically linked manually from the main documentation or README.

Interactive Notebooks

The notebooks/ directory stores Jupyter notebooks for hands-on learning. Files like pe-lecture.ipynb contain executable Python code demonstrating prompt engineering concepts. These notebooks are not rendered directly by the Next.js site; instead, they are distributed as supplementary learning materials referenced via download links in the MDX documentation.

React Component Architecture

Custom UI components ensure consistent styling across all 13 language variants. The components/ directory contains TypeScript React components wired into Nextra through the components export in theme.config.tsx.

Key components include:

• components/pre.tsx – Custom <pre> block styling for code snippets with enhanced syntax highlighting
• components/CopyPageDropdown.tsx – URL copying functionality restricted to English pages only
• components/word-wrap.tsx – Typography helper preventing layout breaks from unbreakable long words

These components are imported using the @/components alias configured in the Next.js project, enabling clean import paths like import { CopyPageDropdown } from '@/components/CopyPageDropdown'.

Development Workflow and Build Process

Running the site locally requires Node.js 18+ and pnpm. The package.json defines dependencies including next, react, nextra, and nextra-theme-docs, along with npm scripts for development and production builds.

Local Development Setup

# Install pnpm if not present

npm i -g pnpm

# Install dependencies

pnpm i

# Start development server

pnpm dev

The development server launches at http://localhost:3000/, rendering the full multilingual site with hot-reloading for MDX and component changes.

Adding New Documentation

To create a new English documentation page, add an MDX file to pages/ following the naming convention:

---
title: New Technique
description: Description of the new prompting technique
---

# New Technique

Content here...

<Pre>

```python
print("Example code")

Nextra automatically routes this to `/new-technique` and adds it to the navigation sidebar based on the file system position.

### Using Shared Components

Components can be imported directly into MDX files or React pages:

```tsx
import { CopyPageDropdown } from '@/components/CopyPageDropdown'

export default function Page() {
  return (
    <div>
      <h1>Custom Page</h1>
      <CopyPageDropdown />
    </div>
  )
}

This pattern ensures consistent UI elements appear uniformly across the documentation platform.

Summary

• The dair-ai/Prompt-Engineering-Guide uses Next.js with Nextra to generate a static documentation site from MDX files located in pages/
• 13 locales are supported through files named {topic}.{locale}.mdx configured in both next.config.js and theme.config.tsx
• Educational content is organized into three tiers: MDX documentation pages, markdown guides in guides/, and executable Jupyter notebooks in notebooks/
• React components in components/pre.tsx and components/CopyPageDropdown.tsx provide custom UI elements integrated via theme.config.tsx
• The build system uses pnpm with standard Next.js scripts (dev, build, start) defined in package.json

Frequently Asked Questions

What framework powers the Prompt Engineering Guide?

The site is built with Next.js using the Nextra documentation theme according to the repository source code. This combination enables MDX support, automatic sidebar generation from the file system, and built-in internationalization. The configuration in next.config.js initializes Nextra, while theme.config.tsx controls the visual theme and navigation elements.

How does the repository handle multiple languages?

The repository implements a file-based i18n system where each language has its own MDX files (e.g., tools.en.mdx, tools.zh.mdx). The next.config.js file defines 13 supported locales, and theme.config.tsx provides the language selector UI. Arabic content uses a dedicated ar-pages/ directory to support RTL layouts while maintaining the same routing logic as other languages.

Where are the interactive code examples stored?

Executable code examples live in the notebooks/ directory as Jupyter notebooks (.ipynb files). Key files include pe-lecture.ipynb and pe-rag.ipynb, which contain Python demonstrations of prompt engineering techniques. These are distributed as downloadable resources rather than being rendered directly by the Next.js application.

How do I add a new page to the documentation?

Create a new MDX file in the pages/ directory following the naming convention {topic}.{locale}.mdx. For example, pages/new-topic.en.mdx creates an English page at the /new-topic route. Include frontmatter for the title and description, and optionally import components from components/ using the @/components alias. Nextra automatically adds the page to the navigation sidebar based on its file system location.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}