Problem Documentation Format

Relevant source files

Purpose and Scope

This document describes the standardized format for documenting individual LeetCode problems in the repository. Each problem follows a consistent structure with bilingual documentation (Chinese and English) and multi-language solution implementations. This standardization enables automated processing, site generation, and easy navigation across 10,000+ problems.

For information about how problems are organized into directories and series, see Directory Structure and Naming. For details on the multi-language solution implementations themselves, see Multi-Language Support.

Problem Directory Structure

Each problem resides in its own directory following a strict naming convention and file organization pattern.

Directory Layout

Sources: solution/0000-0099/0001.Two Sum/README.md solution/0000-0099/0001.Two Sum/README_EN.md solution/0000-0099/0001.Two Sum/Solution.py solution/0000-0099/0001.Two Sum/Solution.java solution/0000-0099/0001.Two Sum/Solution.cpp

Naming Conventions

Component	Format	Example
Directory Name	`NNNN.Problem Title`	`0001.Two Sum`
Chinese README	`README.md`	`README.md`
English README	`README_EN.md`	`README_EN.md`
Solution Files	`Solution.<ext>`	`Solution.py`, `Solution.java`

The directory name includes the zero-padded problem number (4 digits) followed by the English problem title with spaces preserved.

Sources: solution/0000-0099/0001.Two Sum/README.md1-14 solution/0000-0099/0001.Two Sum/README_EN.md1-14

README Documentation Structure

Each problem has two README files: one in Chinese (README.md) and one in English (README_EN.md). Both follow identical structural conventions.

YAML Front Matter

Every README begins with YAML front matter enclosed in --- markers:

Sources: solution/0000-0099/0001.Two Sum/README.md1-8 solution/0000-0099/0001.Two Sum/README_EN.md1-8

Field	Purpose	Example Values
`comments`	Enable/disable comments	`true`, `false`
`difficulty`	Problem difficulty level	`简单`, `中等`, `困难` (Chinese) `Easy`, `Medium`, `Hard` (English)
`edit_url`	Link to edit source	GitHub edit URL
`tags`	Algorithm categories	`数组`, `哈希表`, `动态规划`, etc.

Document Sections

The README structure follows a consistent hierarchy marked by HTML comments:

Sources: solution/0000-0099/0001.Two Sum/README.md10-409 solution/0000-0099/0001.Two Sum/README_EN.md10-406

Problem Title Section

The title appears as an H1 heading with a link to the problem on LeetCode:

Chinese:

English:

Each version cross-links to the other language using a relative path.

Sources: solution/0000-0099/0001.Two Sum/README.md12-14 solution/0000-0099/0001.Two Sum/README_EN.md12-14

Description Section

Wrapped in  and  comments, this section contains:

Problem Statement: The core problem description in HTML or Markdown
Examples: Formatted with input/output/explanation
Constraints: Bullet list of problem constraints

Sources: solution/0000-0099/0001.Two Sum/README.md18-64 solution/0000-0099/0001.Two Sum/README_EN.md18-61

Solutions Section

Wrapped in  and  comments. Contains:

Method Header: ### 方法一: or ### Solution 1:
Algorithm Explanation: Text description of the approach
Complexity Analysis: Time and space complexity notation
Code Tabs: Multi-language implementations

Sources: solution/0000-0099/0001.Two Sum/README.md67-408 solution/0000-0099/0001.Two Sum/README_EN.md64-405

Multi-Language Code Tabs

Solutions are presented using a special tab syntax that renders as language-specific code blocks on the website.

Tab Syntax Structure

Java


**Sources:** <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/README.md#L79-L221" min=79 max=221 file-path="solution/0000-0099/0001.Two Sum/README.md">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/README_EN.md#L76-L218" min=76 max=218 file-path="solution/0000-0099/0001.Two Sum/README_EN.md">Hii</FileRef>

### Supported Languages

The repository supports 10+ programming languages with standardized file extensions and tab labels:

| Language | Tab Label | File Extension | Example File |
|----------|-----------|----------------|--------------|
| Python | `#### Python3` | `.py` | `Solution.py` |
| Java | `#### Java` | `.java` | `Solution.java` |
| C++ | `#### C++` | `.cpp` | `Solution.cpp` |
| Go | `#### Go` | `.go` | `Solution.go` |
| TypeScript | `#### TypeScript` | `.ts` | `Solution.ts` |
| Rust | `#### Rust` | `.rs` | `Solution.rs` |
| JavaScript | `#### JavaScript` | `.js` | `Solution.js` |
| C# | `#### C#` | `.cs` | `Solution.cs` |
| PHP | `#### PHP` | `.php` | `Solution.php` |
| Swift | `#### Swift` | `.swift` | `Solution.swift` |
| Ruby | `#### Ruby` | `.rb` | `Solution.rb` |
| Nim | `#### Nim` | `.nim` | `Solution.nim` |
| C | `#### C` | `.c` | `Solution.c` |

**Sources:** <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.py" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.py">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.java" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.java">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.cpp" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.cpp">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.go" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.go">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.ts" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.ts">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.rs" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.rs">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.js" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.js">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.cs" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.cs">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.php" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.php">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.swift" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.swift">Hii</FileRef>

---

## Solution File Format

Each `Solution.<ext>` file contains only the solution code without additional documentation.

### Python Example

<FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.py#L1-L7" min=1 max=7 file-path="solution/0000-0099/0001.Two Sum/Solution.py">Hii</FileRef>

### Java Example

<FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.java#L1-L13" min=1 max=13 file-path="solution/0000-0099/0001.Two Sum/Solution.java">Hii</FileRef>

### Key Characteristics

1. **Class-based structure**: Most languages use a `Solution` class
2. **Method naming**: Follows LeetCode's API (e.g., `twoSum`, `isPalindrome`)
3. **Type signatures**: Include full type annotations where applicable
4. **Self-contained**: No imports beyond language standard library (unless required by problem)
5. **Formatted code**: Adheres to language-specific formatting standards

**Sources:** <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.py" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.py">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.java" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.java">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0000-0099/0001.Two Sum/Solution.cpp" undefined  file-path="solution/0000-0099/0001.Two Sum/Solution.cpp">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0100-0199/0125.Valid Palindrome/Solution.py" undefined  file-path="solution/0100-0199/0125.Valid Palindrome/Solution.py">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/ae35e0ed/solution/0100-0199/0125.Valid Palindrome/Solution.java" undefined  file-path="solution/0100-0199/0125.Valid Palindrome/Solution.java">Hii</FileRef>

---

## Documentation Generation Flow

The following diagram illustrates how problem documentation is generated and published:

```mermaid
flowchart LR
    subgraph "Source Files"
        RESULT["result.json<br/>(Problem metadata from Spider)"]
        SOLUTION_FILES["Solution.* files<br/>(Code implementations)"]
    end
    
    subgraph "Generation Process"
        MAIN["main.py preprocessing<br/>(Content transformation)"]
        README_GEN["README generation<br/>(From result.json)"]
        CODE_EMBED["Code embedding<br/>(From Solution files)"]
    end
    
    subgraph "Output Files"
        README["README.md<br/>(Chinese)"]
        README_EN["README_EN.md<br/>(English)"]
    end
    
    subgraph "Build & Deploy"
        MKDOCS["MkDocs build<br/>(Site generation)"]
        PAGES["GitHub Pages<br/>(Published site)"]
    end
    
    RESULT --> README_GEN
    SOLUTION_FILES --> CODE_EMBED
    README_GEN --> MAIN
    CODE_EMBED --> MAIN
    MAIN --> README
    MAIN --> README_EN
    README --> MKDOCS
    README_EN --> MKDOCS
    MKDOCS --> PAGES
    
    style RESULT fill:#fff9e6,stroke:#333,stroke-width:2px
    style README fill:#e6f7ff,stroke:#333,stroke-width:2px
    style README_EN fill:#e6f7ff,stroke:#333,stroke-width:2px
    style PAGES fill:#e6ffe6,stroke:#333,stroke-width:2px

Sources: Based on architecture diagrams and .github/workflows/deploy.yml (implied from Diagram 4)

Generation Steps

Spider Fetches Metadata: The Spider class retrieves problem descriptions, examples, and constraints from LeetCode APIs, storing them in result.json
Contributors Add Solutions: Developers submit Solution.<ext> files via pull requests
Preprocessing: main.py transforms content and combines metadata with solution code
README Generation: Both language versions are generated with proper structure, front matter, and embedded code tabs
MkDocs Build: The documentation site is built from README files
Deployment: Site is published to GitHub Pages at leetcode.doocs.org

Sources: Architecture overview from Diagrams 1-6, referencing data acquisition and content generation pipelines

Metadata and Cross-Linking

Problem Number Mapping

Every problem has multiple identifiers that must remain synchronized:

Identifier	Format	Example	Location
LeetCode ID	Integer	`1`	Problem title, URLs
Directory Name	Zero-padded	`0001.Two Sum`	Filesystem
LeetCode URL Slug	Kebab-case	`two-sum`	`leetcode.cn/problems/two-sum`
Edit URL	Full path	`github.com/doocs/leetcode/edit/main/solution/...`	YAML front matter

Sources: solution/0000-0099/0001.Two Sum/README.md1-14

Bi-directional Language Links

Each README contains a relative link to its translation:

In README.md (Chinese):

In README_EN.md (English):

These links enable seamless navigation between language versions on the generated site.

Sources: solution/0000-0099/0001.Two Sum/README.md14 solution/0000-0099/0001.Two Sum/README_EN.md14

Special Problem Types

Some problems have unique documentation requirements:

Database Problems

Database problems include SQL solutions with special formatting:


These are indexed separately in `DATABASE_README.md` files.

**Sources:** Referenced in Diagram 5 showing specialized indexes

### Design Problems

Object-oriented design problems (e.g., "Design SeatManager") document class structures:

```python
class SeatManager:
    def __init__(self, n: int):
        pass
    
    def reserve(self) -> int:
        pass
    
    def unreserve(self, seatNumber: int) -> None:
        pass

Sources: Page description references design patterns in section 4.7

Premium Problems

Problems from interview collections (lcof, lcci, lcp, lcs) follow the same documentation format but reside in separate directory hierarchies:

lcof/: 剑指 Offer (2nd Edition)
lcci/: Cracking the Coding Interview
lcp/: LeetCode Cup
lcs/: LeetCode Contest Series

Sources: Diagram 5 showing content organization hierarchy

Quality Standards

All documentation must adhere to quality standards enforced by CI/CD:

Code Formatting

Each language has automated formatting:

Language	Formatter	Configuration
Python	Black	`black -S` flag
JavaScript/TypeScript	Prettier	`.prettierrc`
C++/Java	clang-format	`.clang-format`
Rust	rustfmt	Default settings
Go	gofmt	Default settings

Sources: Diagram 3 showing code quality control, page 6.2 description

Validation Workflows

GitHub Actions validate all changes:

prettier.yml: Validates Markdown, SQL, JavaScript, TypeScript
black-lint.yml: Validates Python formatting
clang-format-lint.yml: Validates C++, Java formatting
pr-checker.yml: Validates contribution guidelines compliance

Sources: Diagram 4 showing CI/CD workflows, page 7.2 description

File Relationship Diagram

The following diagram shows how different file types relate within a problem directory:

Sources: solution/0000-0099/0001.Two Sum/README.md solution/0000-0099/0001.Two Sum/README_EN.md combined with architecture understanding from Diagrams 1-6

Summary

The problem documentation format provides:

Consistency: Identical structure across 10,000+ problems
Bilingual Support: Chinese and English versions maintained in parallel
Multi-Language Solutions: 10+ programming languages per problem
Automated Processing: Structured format enables CI/CD and site generation
Quality Assurance: Automated formatting and validation
Discoverability: Rich metadata, tags, and cross-links

This standardization allows the repository to scale efficiently while maintaining high quality and accessibility across languages and problem types.

Sources: All file examples and architecture diagrams provided