Prompt Engineering Guide — Administrator & Developer Guide

This guide covers the architecture, deployment, internals, and extension of the Prompt Engineering Guide (PEG) — a Nextra-based documentation site maintained by DAIR.AI. It is written for developers who need to modify, deploy, or understand the codebase. See the User Guide for content navigation and usage.

1. Architecture Overview

What the System Does

The Prompt Engineering Guide is a statically generated, multilingual documentation website built on the Nextra framework (which itself is built on Next.js). The site serves structured educational content about prompt engineering through MDX pages, with interactive React components for code copying, AI assistant integration, and course promotion. The entire content layer is file-based — MDX files in the pages/ directory define both the site structure and the rendered content.

Architecture Diagram

Browser Request
      │
      ▼
┌─────────────┐
│  Next.js     │
│  Server      │
│  (SSG/SSR)   │
├─────────────┤
│  Nextra      │  MDX → React pages
│  v2.13.2     │  i18n routing
│  Theme: docs │  Search indexing
├─────────────┤
│  Custom      │  AnnouncementBar, CopyPageDropdown,
│  Components  │  CourseCard, CodeBlock, Pre,
│              │  TabsComponent, PromptFiles,
│              │  ContentFileNames, Screenshot
├─────────────┤
│  API Routes  │  /api/contentFiles
│  (3 routes)  │  /api/getPageContent
│              │  /api/promptsFiles
├─────────────┤
│  pages/      │  MDX content (14 locales)
│  (1500+      │  _meta.*.json (navigation)
│   files)     │  img/ (static assets)
└─────────────┘

Note

The project is titled nextra-docs-template in package.json — it was bootstrapped from Nextra's documentation template and customized with DAIR.AI-specific components and content. This has no functional impact but appears in build logs and lock files.

Component Inventory

Technology Stack

2. System Requirements

Build Requirements

Development

# Clone the repository
git clone https://github.com/dair-ai/Prompt-Engineering-Guide.git
cd Prompt-Engineering-Guide

# Install dependencies
npm install
# or
pnpm install

# Start development server
npm run dev

ready - started server on 0.0.0.0:3000

Important

The project uses pnpm-lock.yaml alongside package-lock.json. If both are present, ensure you use the same package manager consistently to avoid dependency resolution conflicts.

Build and Production

# Build for production
npm run build

# Start production server
npm start

3. Configuration Reference

next.config.js

The core configuration file applies the Nextra plugin and configures Next.js.

const withNextra = require('nextra')({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.tsx',
  latex: true
})

module.exports = withNextra({
  i18n: {
    locales: ['en', 'zh', 'jp', 'pt', 'tr', 'es', 'it', 'fr', 'kr', 'ca', 'fi', 'ru', 'de', 'ar'],
    defaultLocale: 'en',
  },
  webpack(config) {
    // SVG handling for components/icons/
    const allowedSvgRegex = /components\/icons\/.+\.svg$/
    const fileLoaderRule = config.module.rules.find(rule => rule.test?.test?.('.svg'))
    fileLoaderRule.exclude = allowedSvgRegex
    config.module.rules.push({
      test: allowedSvgRegex,
      use: ['@svgr/webpack']
    })
    return config
  }
})

theme.config.tsx

Controls site branding, navigation, and layout customization.

Important

The main wrapper conditionally renders CopyPageDropdown only when router.locale === 'en' and router.pathname !== '/'. Modifying locale routing logic may break this feature.

Google Analytics

Analytics are configured directly in pages/_app.tsx:

<Script async src="https://www.googletagmanager.com/gtag/js?id=G-ST7R3WQ353"/>

Tracking ID: G-ST7R3WQ353

Vercel Analytics is also enabled via @vercel/analytics/react.

4. Deployment & Scaling

Build Pipeline

The standard Next.js build process applies:

npm run build    # Generates .next/ directory
npm start        # Starts production server

The site is designed for deployment on Vercel (evidenced by @vercel/analytics integration and Nextra's Vercel-optimized defaults), but can be deployed to any platform that supports Next.js.

Static Export Considerations

Nextra with i18n enabled requires server-side rendering for locale detection (via middleware.js). A fully static export (next export) is not supported with the current configuration due to:

1. The i18n configuration in next.config.js
2. The API routes in pages/api/
3. The middleware-based locale routing

Warning

Do not attempt next export with this configuration. The middleware and API routes require a Node.js runtime.

Deployment Checklist

• [ ] All dependencies installed (npm install)
• [ ] Build completes without errors (npm run build)
• [ ] Verify search works on production URL
• [ ] Verify locale switching works
• [ ] Verify CopyPageDropdown works on English pages
• [ ] Verify LaTeX/KaTeX rendering on research pages
• [ ] Confirm Google Analytics is receiving events

5. Operations

Content Updates

Content is managed entirely through MDX files. The update workflow:

1. Edit or add .mdx files in the appropriate pages/ subdirectory
2. Add corresponding _meta.*.json entries for navigation
3. Test locally with npm run dev
4. Commit and push — deployment handles the rest

Adding a New Content Page

1. Create the MDX file with the locale suffix:

   pages/techniques/new-technique.en.mdx
   

2. Add the page to the English navigation metadata:

   // pages/techniques/_meta.en.json
   {
     "new-technique": "New Technique Name"
   }
   

3. For translations, create locale-specific files and metadata:

   pages/techniques/new-technique.zh.mdx
   pages/techniques/new-technique.de.mdx
   

Tip

You only need to add metadata entries for languages where a translation exists. Nextra gracefully handles missing translations by not showing those pages in the sidebar for that locale.

Adding a New Language

1. Add the locale code to next.config.js:

   i18n: {
     locales: ['en', 'zh', /* ... */, 'new-locale'],
     defaultLocale: 'en',
   }
   

2. Add the locale label to theme.config.tsx:

   i18n: [
     // ... existing locales
     { locale: 'new-locale', text: 'Language Name' },
   ]
   

3. Create _meta.new-locale.json files in each section directory

4. Create .new-locale.mdx content files

Monitoring

• Google Analytics (G-ST7R3WQ353) — page views, user geography, session data
• Vercel Analytics — web vitals, performance metrics (if deployed on Vercel)
• Git timestamps — each page shows its last update date via @napi-rs/simple-git

Note

The @napi-rs/simple-git dependency enables the "Last updated on" timestamp feature. It reads git history for each file. If the git history is shallow (e.g., --depth 1 clone), timestamps may be inaccurate or missing.

6. Performance

Build Performance

With 1,556 files across 14 locales, build times can be significant. Key factors:

Runtime Performance

• Static generation — most pages are statically generated at build time
• API routes — contentFiles, promptsFiles, and getPageContent run on the server and read the filesystem at request time
• Client-side — CopyPageDropdown fetches page content from GitHub raw URLs via the /api/getPageContent route

Tip

The /api/getPageContent route fetches content from https://raw.githubusercontent.com/dair-ai/Prompt-Engineering-Guide/main/pages/ at request time. This means the "Copy page" feature always serves the latest main branch content, not the deployed version.

7. Security

API Route Input Validation

The three API routes perform basic input validation:

/api/getPageContent — the most security-sensitive route:

• Validates pagePath parameter exists and is a string
• Restricts to .en.mdx files only (hardcoded)
• Constructs URLs from user input — path traversal is mitigated by the .en.mdx suffix requirement and GitHub's own URL validation
• Fetches from a hardcoded GitHub raw URL base

/api/contentFiles and /api/promptsFiles — read local filesystem:

• Accept section and lang parameters
• Construct filesystem paths using path.join(process.cwd(), 'pages', section)
• No explicit sanitization of the section parameter — directory traversal is limited by Next.js's API route sandboxing and the fact that fs.existsSync / fs.readdirSync would fail for non-existent paths

Warning

The section parameter in /api/contentFiles is used directly in path.join without sanitization. While Next.js provides some protection, a defense-in-depth approach would validate that section contains no .. or path separators. This is low-risk in practice since the API only reads metadata files.

Third-Party Scripts

External Data Flows

Caution

The "Open in Claude" and "Open in ChatGPT" features construct URLs that include the current page's URL. Ensure no sensitive internal routes are accidentally exposed through this mechanism.

8. Developer Internals

Repository Structure

Prompt-Engineering-Guide/
├── middleware.js              # Nextra locale routing
├── next.config.js             # Next.js + Nextra configuration
├── theme.config.tsx           # Site theme and branding
├── package.json               # Dependencies and scripts
├── tsconfig.json              # TypeScript configuration
├── CITATION.cff               # Academic citation metadata
├── LICENSE.md                  # MIT License
├── components/                # React components
│   ├── AnnouncementBar.tsx    # Promotional banner
│   ├── CodeBlock.tsx          # Code display with copy
│   ├── ContentFileNames.tsx   # Dynamic content card grid
│   ├── CopyPageDropdown.tsx   # AI integration dropdown
│   ├── CourseCard.tsx         # Course promotion cards
│   ├── PromptFiles.jsx       # Prompt Hub listing
│   ├── TabsComponent.tsx     # Multi-model code tabs
│   ├── button.tsx            # Reusable button
│   ├── check.tsx             # Check icon SVG
│   ├── copy.tsx              # Copy icon SVG
│   ├── copy-to-clipboard.tsx # Clipboard utility
│   ├── counters.tsx          # Example counter
│   ├── pre.tsx               # Custom code block
│   ├── word-wrap.tsx         # Word-wrap icon SVG
│   ├── counters.module.css   # Counter styles
│   ├── icons/                # SVG icons (28 files)
│   │   └── index.ts          # Icon barrel exports
│   └── screenshot/           # Screenshot component
│       └── index.jsx         # Image display
├── pages/                     # Content and routing
│   ├── _app.tsx              # App root (analytics, announcement bar)
│   ├── style.css             # Global styles
│   ├── _meta.*.json          # Navigation metadata (per locale)
│   ├── index.*.mdx           # Homepage (per locale)
│   ├── about.*.mdx           # About page
│   ├── api/                  # API routes
│   │   ├── contentFiles.js   # Section content listing
│   │   ├── getPageContent.ts # Fetch page markdown from GitHub
│   │   └── promptsFiles.js   # Prompt Hub category listing
│   ├── introduction/         # Introduction section
│   ├── techniques/           # Prompting techniques
│   ├── agents/               # AI Agents (English only)
│   ├── guides/               # Topical guides (English only)
│   ├── applications/         # Application guides
│   ├── prompts/              # Prompt Hub
│   ├── models/               # Model guides
│   ├── risks/                # Risks & Misuses
│   └── research/             # Research findings
├── guides/                    # Legacy markdown guides
├── notebooks/                 # Jupyter notebooks (13 files)
├── img/                       # Static images
├── lecture/                   # Lecture PDF
├── ar-pages/                  # Arabic locale pages
└── public/                    # Static assets (favicons)

Content File Naming Convention

All content files follow a strict naming pattern:

{page-slug}.{locale}.mdx

Examples:

• pages/techniques/cot.en.mdx — Chain-of-Thought page, English
• pages/techniques/cot.zh.mdx — Chain-of-Thought page, Chinese
• pages/techniques/cot.de.mdx — Chain-of-Thought page, German

Navigation metadata follows the same pattern:

_meta.{locale}.json

Each _meta.*.json file maps page slugs to display titles for that locale:

{
  "cot": "Chain-of-Thought Prompting",
  "fewshot": "Few-shot Prompting"
}

Note

Arabic (ar) uses a different directory structure — content lives in ar-pages/ rather than within pages/. Arabic-locale metadata files use the .ar.json and .ar.mdx suffixes but are in a separate directory tree. This is an architectural inconsistency — all other locales coexist within pages/.

API Routes

GET /api/contentFiles

Returns ordered page listings for a given section and locale.

Response: { fileNames: [{ slug, title }] }

Reads _meta.{lang}.json from the specified section directory and returns page slugs with their titles in metadata-defined order.

GET /api/getPageContent

Fetches cleaned markdown content from GitHub.

Response: { content, pagePath }

Processing steps:

1. Validates that pagePath ends with .en.mdx
2. Fetches raw content from https://raw.githubusercontent.com/dair-ai/Prompt-Engineering-Guide/main/pages/{pagePath}
3. Strips import statements, export statements, and YAML frontmatter
4. Returns cleaned markdown

GET /api/promptsFiles

Returns the complete Prompt Hub structure.

Response: Array of { folderKey, folderName, files: [{ slug, title }] }

Reads the prompts directory structure and returns category folders with their page listings.

Component Architecture

CopyPageDropdown

The most complex component — provides AI integration features.

Rendering logic: Injected into every English non-index page via theme.config.tsx's main wrapper.

State management:

• isOpen — dropdown visibility
• showMarkdownModal — markdown preview modal
• markdownContent — fetched page content
• copyStatus — idle | copying | success
• hoveredButton — hover state for styling

Clipboard implementation: Two-tier approach:

1. Modern navigator.clipboard.writeText() for HTTPS contexts
2. Fallback using document.execCommand('copy') with iOS-specific handling (selection range, 16px font to prevent zoom)

External redirects:

• Claude: https://claude.ai/new?q={encoded_prompt}
• ChatGPT: https://chatgpt.com/?prompt={encoded_prompt}

CourseCard System

Three exported components for course promotion:

• CourseCard — individual course card with tag, title, description, metadata
• CoursesSection — grid container for multiple CourseCards
• CoursePromo — single-card inline promotion with CTA button

All three support dark mode via a useDarkMode hook that observes document.documentElement.classList for the dark class.

Pre Component

Replaces Nextra's default <pre> element via theme.config.tsx:

components: {
  pre: Pre,
}

Features:

• Word-wrap toggle (persisted via document.documentElement.dataset.nextraWordWrap)
• Copy-to-clipboard (reads from the rendered <code> element's textContent)
• Optional filename header display

ContentFileNames and PromptFiles

Dynamic components that fetch navigation data from the API routes and render Nextra Cards:

• ContentFileNames — fetches /api/contentFiles and renders a card grid for a section
• PromptFiles — fetches /api/promptsFiles and renders categorized prompt listings with section headers

Internationalization Deep Dive

The i18n system has three layers:

1. Next.js i18n routing (next.config.js) — handles URL locale prefixes and detection
2. Nextra locale middleware (middleware.js) — export { locales as middleware } from 'nextra/locales'
3. Theme i18n labels (theme.config.tsx) — maps locale codes to display names for the language selector

Content resolution order:

1. Look for {slug}.{locale}.mdx in the current section
2. If not found, the page is not shown in the sidebar for that locale
3. There is no fallback to English — missing translations are simply absent

Metadata resolution:

1. Look for _meta.{locale}.json in the section directory
2. Pages without metadata entries are still accessible by URL but not shown in navigation

Code Patterns and Conventions

Note

The codebase uses two different icon systems (SVGR and FontAwesome) and two different clipboard implementations (the CopyToClipboard component and the CopyPageDropdown's inline implementation). This is a historical artifact, not a deliberate architectural choice.

Testing

No test files or test configuration were found in the repository. The package.json does not include a test script, and no testing framework (Jest, Vitest, Playwright, Cypress) is present in dependencies.

Warning

The project has no automated tests. Changes to components, API routes, or configuration should be manually verified in the development server across multiple locales before deployment.

Potential Improvements

Based on source analysis:

1. Input sanitization for API routes — the section parameter in /api/contentFiles should be validated against an allowlist of known section names
2. Consolidate icon systems — unify on either SVGR or FontAwesome, not both
3. Consolidate clipboard implementations — the CopyToClipboard component and CopyPageDropdown's inline clipboard code could share a utility
4. Add TypeScript to .jsx components — PromptFiles.jsx and screenshot/index.jsx lack type annotations
5. Arabic content directory — consider migrating ar-pages/ into the standard pages/ directory with .ar.mdx suffixes for consistency
6. Stale GitHub fetch in getPageContent — fetching from GitHub's main branch at request time means the "Copy page" content may differ from the deployed version; consider reading from the local filesystem instead
7. Add automated testing — at minimum, smoke tests for API routes and critical component rendering

9. Integration Points

External Services

Content Pipeline

MDX files → Nextra MDX compiler → React pages → Static HTML (build)
                                                → Server-rendered (API routes)

The content pipeline is entirely file-based:

1. Authors write or edit .mdx files
2. Navigation structure is defined in _meta.*.json files
3. Nextra compiles MDX to React components at build time
4. The search index is built automatically by Nextra
5. Git timestamps provide "last updated" dates

Adding New Sections

To add a top-level section (e.g., "Benchmarks"):

1. Create the directory: pages/benchmarks/
2. Add metadata for each supported locale:

   // pages/benchmarks/_meta.en.json
   { "overview": "Benchmarks Overview" }
   

3. Add content files: pages/benchmarks/overview.en.mdx
4. Register in the top-level navigation metadata:

   // pages/_meta.en.json (add the key)
   { "benchmarks": "Benchmarks" }
   

5. Repeat metadata entries for other locales as translations become available

10. Contributing

Prerequisites

• Node.js 16+
• Git
• Familiarity with MDX (Markdown + JSX)

Development Workflow

1. Fork and clone the repository
2. Install dependencies: npm install
3. Create a feature branch
4. Make changes
5. Test locally: npm run dev
6. Verify across at least 2 locales (English + one other)
7. Submit a pull request

Content Contribution Guidelines

• Write content in MDX format
• Follow existing page structure for consistency
• Add _meta.*.json entries for new pages
• Include images in the appropriate img/ subdirectory
• Test LaTeX rendering if mathematical notation is used

Component Contribution Guidelines

• Use TypeScript (.tsx) for new components
• Follow the existing inline-style pattern (or propose a migration to CSS modules)
• Support dark mode using the useDarkMode pattern from CourseCard.tsx
• Test in both light and dark modes
• Verify mobile responsiveness

Open Community Issues

From GitHub issues (as of source commit):