Implementation:Langgenius Dify Gen Doc Paths

Knowledge Sources	Langgenius_Dify
Domains	Frontend, Build_Tools
Last Updated	2026-02-12 07:00 GMT

Overview

TypeScript code generator that fetches the Dify documentation navigation structure from GitHub and produces strongly-typed TypeScript path definitions for use in the frontend.

Description

gen-doc-paths.ts automates the creation of TypeScript type definitions representing every valid documentation path in the Dify docs site. It performs the following steps:

1. Fetches the docs.json navigation manifest from the langgenius/dify-docs repository on GitHub.
2. Extracts page paths by recursively traversing the navigation tree (handling pages, groups, dropdowns, languages, and versions).
3. Extracts OpenAPI specs referenced in the navigation, fetches each spec, and generates API reference paths from operation summaries and tags for English, Chinese, and Japanese locales.
4. Groups paths by section (e.g., use-dify, getting-started) after stripping the language prefix.
5. Generates TypeScript type definitions including per-section union types, a combined DocPathWithoutLang type with optional anchor support, a full DifyDocPath type with language prefix, and an apiReferencePathTranslations constant mapping English API paths to their Chinese and Japanese equivalents.
6. Writes the output to web/types/doc-paths.ts.

The generated types enable compile-time validation of documentation links throughout the Dify frontend, preventing broken documentation references.

Usage

Run this script whenever the upstream dify-docs repository updates its navigation structure or OpenAPI specifications, to regenerate the path types and keep frontend documentation links type-safe.

Code Reference

Source Location

• Repository: Langgenius_Dify
• File: web/scripts/gen-doc-paths.ts
• Lines: 1-442

Signature

function summaryToSlug(summary: string): string
function getFirstPathSegment(apiPath: string): string
function extractOpenAPIPaths(item: NavItem | undefined, paths?: Set<string>): Set<string>
async function fetchOpenAPIAndExtractPaths(openapiPath: string): Promise<EndpointPathMap>
function extractPaths(item: NavItem | undefined, paths?: Set<string>): Set<string>
function groupPathsBySection(paths: Set<string>): Record<string, Set<string>>
function sectionToTypeName(section: string): string
function generateTypeDefinitions(
  groups: Record<string, Set<string>>,
  apiReferencePaths: string[],
  apiPathTranslations: Record<string, { zh?: string; ja?: string }>,
): string
async function main(): Promise<void>

Import

// CLI script - run via pnpm
pnpm gen-doc-paths

I/O Contract

Inputs

Name	Type	Required	Description
(none -- no CLI arguments)	--	--	The script fetches all data from remote GitHub URLs automatically
docs.json (remote)	JSON	Yes	Navigation manifest fetched from https://raw.githubusercontent.com/langgenius/dify-docs/refs/heads/main/docs.json
OpenAPI specs (remote)	JSON	Yes	OpenAPI specification files referenced in the navigation, fetched from the dify-docs repository

Outputs

Name	Type	Description
web/types/doc-paths.ts	TypeScript file	Generated type definitions including DocLanguage, per-section path types, ApiReferencePath, DocPathWithoutLang, DifyDocPath, and apiReferencePathTranslations
stdout	string	Progress messages showing fetch status, path counts, section groupings, and output file location
exit code 0	number	Successful generation
exit code 1	number	Failed to fetch docs.json or encountered an error

Usage Examples

Generate documentation path types

pnpm gen-doc-paths

Run directly with tsx

cd web
npx tsx scripts/gen-doc-paths.ts

Related Pages

• Principle:Langgenius_Dify_Type_Safety
• Principle:Langgenius_Dify_Documentation