Problem Documentation Format

Relevant source files

Purpose and Scope

This document describes the standardized format used for documenting individual LeetCode problems in the repository. Each problem has bilingual documentation (Chinese and English) following a consistent structure with YAML front matter, problem descriptions, solution explanations, tabbed code examples, and complexity analysis.

For information about the directory structure and naming conventions, see Directory Structure and Naming. For information about the different problem series (solution/, lcof/, lcci/, etc.), see Problem Series.

Document Structure Overview

Each problem README follows a standardized markdown structure with HTML comment markers for section delimiters. Both Chinese (README.md) and English (README_EN.md) versions use identical structural patterns.

File System Pattern

Markdown Document Structure

Example from solution/0000-0099/0001.Two Sum/README.md1-226:

Core Structural Elements

Element	Marker	Lines (typical)	Purpose
Front matter	`---` delimiters	1-9	Metadata for site generation
Problem wrapper	`<!-- problem:start/end -->`	10, last line	Entire problem scope
Description	`<!-- description:start/end -->`	~18, ~66	Problem statement HTML
Solution	`<!-- solution:start/end -->`	~70, ~224	Per-solution wrapper
Code tabs	`<!-- tabs:start/end -->`	~80, ~222	Multi-language code blocks

Sources: solution/0000-0099/0001.Two Sum/README.md1-226 solution/0000-0099/0003.Longest Substring Without Repeating Characters/README.md1-187

Front Matter Schema

Every README starts with YAML front matter (lines 1-9) delimited by ---. This metadata is consumed by MkDocs during site generation (see Documentation Site Generation).

Front Matter Fields

Field	Type	Required	Populated From	Example
`comments`	boolean	Yes	Hardcoded `true`	`true`
`difficulty`	string	Yes	`result.json` `difficulty` field, translated	`简单` (CN) / `Easy` (EN)
`edit_url`	string	Yes	Generated from file path	`https://github.com/doocs/leetcode/edit/main/solution/...`
`tags`	array	Yes	`result.json` `topicTags` array	`- 数组` `- 哈希表`

Example from solution/0000-0099/0001.Two Sum/README.md1-9

Common Tag Values

Tags are fetched from LeetCode's API and stored in result.json. Common Chinese tags include:

数组, 哈希表, 双指针, 字符串, 动态规划
树, 深度优先搜索, 广度优先搜索, 二分查找
贪心, 位运算, 栈, 队列, 链表
回溯, 分治, 滑动窗口, 排序, 矩阵

English equivalents use the same structure: Array, Hash Table, Two Pointers, etc.

Sources: solution/0000-0099/0001.Two Sum/README.md1-9 solution/0000-0099/0002.Add Two Numbers/README.md1-9 solution/result.json1

HTML Comment Markers

The documentation uses HTML comments as structural markers to delimit different sections. These markers enable automated processing and consistent parsing:

Marker Pairs

Start Marker	End Marker	Purpose
`<!-- problem:start -->`	`<!-- problem:end -->`	Wraps entire problem documentation
`<!-- description:start -->`	`<!-- description:end -->`	Wraps problem statement (HTML)
`<!-- solution:start -->`	`<!-- solution:end -->`	Wraps each solution method
`<!-- tabs:start -->`	`<!-- tabs:end -->`	Wraps multi-language code blocks

These markers allow the content generation pipeline (see Content Generation Pipeline) to extract and process specific sections independently.

Sources: solution/0100-0199/0125.Valid Palindrome/README.md10-304 solution/0200-0299/0289.Game of Life/README.md12-305

Problem Title and Metadata

Immediately after the front matter, each problem includes:

Problem Title with LeetCode link (Chinese site for Chinese READMEs, English site for English READMEs)
Language Version Link pointing to the alternate language README

Format Pattern

For English versions:

The problem number in the title matches the directory name, ensuring consistency. Links use relative paths within the repository structure.

Sources: solution/0100-0199/0125.Valid Palindrome/README.md12-14 solution/0100-0199/0125.Valid Palindrome/README_EN.md12-14

Problem Description Section

The description section wraps HTML content from LeetCode's API within comment markers.

Section Structure

HTML Content Characteristics

The HTML is fetched by get_question_detail_en() and get_question_detail_cn() in solution/main.py87-161 via GraphQL queries:

Typical HTML elements:

<p> - Paragraph text
<pre> - Example inputs/outputs
<code> - Inline code
<strong> - Bold headers like "示例 1:", "提示:"
<ul> / <ol> / <li> - Lists
<img> - Diagrams (re-hosted on fastly.jsdelivr.net/gh/doocs/leetcode@main/)

Example from solution/0000-0099/0001.Two Sum/README.md20-64:

Sources: solution/0000-0099/0001.Two Sum/README.md18-64 solution/main.py87-161

Solution Documentation Pattern

The solutions section (## 解法) contains one or more solution methods, each following this pattern:

Method Header Format

Each solution method uses a level 3 heading with the pattern:

Common algorithm names include:

双指针 (Two Pointers)
哈希表 (Hash Table)
动态规划 (Dynamic Programming)
深度优先搜索 (Depth-First Search)
二分查找 (Binary Search)
原地标记 (In-place Marking)

Sources: solution/0100-0199/0125.Valid Palindrome/README.md68 solution/0200-0299/0289.Game of Life/README.md80

Algorithm Explanation Format

Each solution method begins with a detailed explanation of the algorithm:

Explanation Structure

Algorithm Overview - One or two sentences describing the approach
Step-by-step Process - Numbered or bulleted steps explaining the algorithm
Implementation Details - Variable names, data structures used
Complexity Analysis - Time and space complexity with reasoning

Example from solution/0100-0199/0125.Valid Palindrome/README.md70-78:

Mathematical Notation

Variables and mathematical expressions use LaTeX notation with $ delimiters:

Inline: $i$ , $j$ , $O(n)$
Complex expressions: $i \geq j$ , $live \lt 2$

Complexity Format

Complexity analysis always follows this pattern:

时间复杂度 $O(expression)$，其中 $var$ 是description。空间复杂度 $O(expression)$。

Or in English:

The time complexity is $O(expression)$, where $var$ is description. The space complexity is $O(expression)$.

Sources: solution/0100-0199/0125.Valid Palindrome/README.md70-78 solution/0200-0299/0289.Game of Life/README.md82-88

Tabbed Code Examples

Multi-language implementations follow the algorithm explanation within  /  markers.

Tab Structure Pattern

Example from solution/0000-0099/0001.Two Sum/README.md80-222:

Tab Markdown Format

Each language section:

Level 4 heading: #### LanguageName
Code fence with language identifier: ```language
Complete solution code
Closing fence: ```

Example:

Java


### Language Coverage

Standard order (matches formatting pipeline in <FileRef file-url="https://github.com/doocs/leetcode/blob/86225ea1/solution/.prettierrc" undefined  file-path="solution/.prettierrc">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/86225ea1/solution/package.json" undefined  file-path="solution/package.json">Hii</FileRef>):
1. Python3
2. Java
3. C++
4. Go
5. TypeScript
6. Rust
7. JavaScript
8. C#
9. PHP
10. Swift
11. Additional: Ruby, Nim, Kotlin, Dart, Scala

Not all problems have implementations in all languages. Newer problems typically have Python, Java, C++, Go, TypeScript, and Rust.

Sources: <FileRef file-url="https://github.com/doocs/leetcode/blob/86225ea1/solution/0000-0099/0001.Two Sum/README.md#L80-L222" min=80 max=222 file-path="solution/0000-0099/0001.Two Sum/README.md">Hii</FileRef> <FileRef file-url="https://github.com/doocs/leetcode/blob/86225ea1/solution/0000-0099/0003.Longest Substring Without Repeating Characters/README.md#L80-L187" min=80 max=187 file-path="solution/0000-0099/0003.Longest Substring Without Repeating Characters/README.md">Hii</FileRef>

---

## Code Implementation Pattern

All solution files follow the naming pattern `Solution.<ext>` and implement a `Solution` class/struct.

### Class Structure by Language

| Language | File | Class Pattern | Method Pattern |
|----------|------|---------------|----------------|
| Python3 | `Solution.py` | `class Solution:` | `def methodName(self, ...): ...` |
| Java | `Solution.java` | `class Solution` | `public ReturnType methodName(...)` |
| C++ | `Solution.cpp` | `class Solution` | `ReturnType methodName(...)` in public section |
| Go | `Solution.go` | `// No class` | `func methodName(...) ReturnType` |
| TypeScript | `Solution.ts` | `// No class` | `function methodName(...): ReturnType` |
| Rust | `Solution.rs` | `impl Solution` | `pub fn method_name(...) -> ReturnType` |
| JavaScript | `Solution.js` | `// No class` | `var methodName = function(...) {...}` |
| C# | `Solution.cs` | `public class Solution` | `public ReturnType MethodName(...)` (PascalCase) |
| PHP | `Solution.php` | `class Solution` | `function methodName(...)` |

### Implementation Examples

**Python3** <FileRef file-url="https://github.com/doocs/leetcode/blob/86225ea1/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>:
```python
class Solution:
    def twoSum(self, nums: List[int], target: int) -> List[int]:
        d = {}
        for i, x in enumerate(nums):
            if (y := target - x) in d:
                return [d[y], i]
            d[x] = i

Java solution/0000-0099/0001.Two Sum/Solution.java1-11:

TypeScript solution/0000-0099/0003.Longest Substring Without Repeating Characters/Solution.ts1-13:

PHP solution/0000-0099/0001.Two Sum/Solution.php1-14:

Sources: solution/0000-0099/0001.Two Sum/Solution.py1-7 solution/0000-0099/0001.Two Sum/Solution.java1-11 solution/0000-0099/0001.Two Sum/Solution.php1-14 solution/0000-0099/0003.Longest Substring Without Repeating Characters/Solution.ts1-13 solution/0000-0099/0003.Longest Substring Without Repeating Characters/Solution.rs1-19

Bilingual Documentation

Every problem has parallel documentation in Chinese (README.md) and English (README_EN.md) with identical structure:

Language-Specific Elements

Element	Chinese (README.md)	English (README_EN.md)
Problem URL	`leetcode.cn`	`leetcode.com`
Front matter difficulty	`简单`, `中等`, `困难`	`Easy`, `Medium`, `Hard`
Section headers	`题目描述`, `解法`	`Description`, `Solutions`
Language link	`[English Version]`	`[中文文档]`
Tags	Chinese names	English names

Both versions contain identical code examples - the code itself is language-agnostic and doesn't change between Chinese and English documentation.

Sources: solution/0100-0199/0125.Valid Palindrome/README.md1-307 solution/0100-0199/0125.Valid Palindrome/README_EN.md1-303

Series-Specific Documentation Patterns

Different problem series have unique organizational structures while maintaining the core README format.

Problem Series Comparison

Series Index Table Formats

solution/README.md solution/README.md12-14:

lcof/README.md lcof/README.md18-22:

lcci/README.md lcci/README.md16-20:

Database problems solution/DATABASE_README.md11-14:

Directory Structure Differences

Series	Directory Pattern	Problem ID Format	Example
solution	`0000-0099/`, `0100-0199/`	`0001`, `0125`, `3749`	solution/0000-0099/0001.Two Sum/
lcof	`面试题03. 数组中重复的数字/`	`面试题03`	URL-encoded in index
lcci	`01.01.Is Unique/`	`01.01`, `08.13`	lcci/01.01.Is Unique/
lcp	`LCP 01. 猜数字/`	`LCP 01`, `LCP 44`	lcp/LCP 01. 猜数字/

Premium Problem Indicators

Premium (paid-only) problems marked with 🔒 in the "备注" column:

Example from solution/README.md169:

Determined by paid_only field in solution/result.json1

Sources: solution/README.md12-14 lcof/README.md18-22 lcci/README.md16-20 lcp/README.md14-16 solution/DATABASE_README.md11-14

Series Index README Format

Each series has an index README that lists all problems in a table:

Table Structure

Example from lcof/README.md20-23:

Column Definitions

Column	Chinese	English	Content
Problem #	题号	#	LeetCode problem number with link to problem
Solution	题解	Solution	Link to problem's README in repository
Tags	标签	Tag	Algorithm/data structure tags
Difficulty	难度	Difficulty	`简单`/`中等`/`困难` or `Easy`/`Medium`/`Hard`

The series README provides a searchable index of all problems, with instructions to use Control + F (or Command + F) for quick searching.

Sources: lcof/README.md1-88 lcci/README.md1-133 lcp/README.md1-102

Content Generation Integration

The documentation format integrates with solution/main.py which orchestrates data fetching and README generation.

Spider Class Methods

Data Model: result.json Schema

solution/result.json1 contains array of problem objects:

Field	Type	Example	Used In
`question_id`	string	`"4140"`	Internal ID
`frontend_question_id`	string	`"3749"`	Display number in README title
`question_title_slug`	string	`"evaluate-valid-expressions"`	URL path component
`title_cn`	string	`"计算有效表达式"`	Chinese README title
`title_en`	string	`"Evaluate Valid Expressions"`	English README title
`content_cn`	string	HTML	`<!-- description:start -->` section
`content_en`	string	HTML	`<!-- description:start -->` section
`paid_only`	boolean	`true`	🔒 indicator in index tables
`difficulty`	string	`"Easy"`	YAML `difficulty` field
`category`	string	`"Algorithms"`	Problem type (Algorithms/Database/Concurrency)
`url_cn`	string	`"https://leetcode.cn/problems/..."`	Problem link in Chinese README
`url_en`	string	`"https://leetcode.com/problems/..."`	Problem link in English README
`relative_path_cn`	string	`"/solution/.../README.md"`	File path for Chinese README
`relative_path_en`	string	`"/solution/.../README_EN.md"`	File path for English README

README Generation Flow

Index Table Generation

The main index solution/README.md12-13 is generated from result.json:

Each row maps to a result.json entry:

Column 1: frontend_question_id with link to url_cn
Column 2: title_cn with link to relative_path_cn
Column 3: Comma-joined topicTags array
Column 4: Translated difficulty (Easy → 简单)
Column 5: 🔒 if paid_only is true

Sources: solution/main.py30-161 solution/result.json1 solution/README.md12-14

Document Validation

The repository uses automated validation to ensure documentation consistency:

Format Checkers

YAML Front Matter Validator - Ensures all required fields present
HTML Comment Marker Validator - Checks for proper marker pairs
Link Validator - Verifies internal links point to existing files
Tab Structure Validator - Ensures proper tab opening/closing

Code Formatting (see Code Formatting System)

Prettier - Formats Markdown, code blocks
lint-staged - Runs formatting on changed files
GitHub Actions - Automated format checking on PRs

These validation steps run as part of the CI/CD pipeline (see GitHub Actions Workflows) before deployment to ensure all documentation follows the standardized format.

Sources: .github/workflows/ workflows, package.json lint-staged configuration