Editing References
Use cross-references to direct users to related information that might add to their understanding of the documentation content.
Try to write and edit so that you use cross-references only for information that is not essential to the task at hand. For example, users should not have to look up information to complete a procedure. If your content has too many cross-references, consider restructuring it.
Unless you have no other choice, do not make cross-references to information that is not within your control, especially hyperlinks. Websites are always being modified and reorganized, and few things are as frustrating to the user as an invalid cross-reference.
Structure and Style of Cross-references
Information about why a cross-reference might be of interest should precede the cross-reference itself.
Example
The guidelines for handling numbers in technical context can be found in Chapter Numbers of this manual.
For cross-references to figures, tables, sections, or chapters in another publication, provide only the title. The number may be updated without your knowledge.
Example
See Chapter Overview in ESP32 Datasheet.
Structure the cross-reference from the most general to the most specific reference.
Example
For pin layout of ESP32, see ESP32 Datasheet > Chapter Pin Definitions > Section Pin Layout.
For online cross-references that are formatted as hyperlinks, use descriptive text for the hyperlink; do not use blank expressions, such as “click here”.
Example
Preferred
Avoid
For more information about ESP32, please refer to ESP32 Datasheet.
For more information about ESP32-C6, click here.
Formatting of Cross-references
If the hyperlink comes at the end of a sentence, do not make the ending punctuation part of the hyperlink.
Example
Preferred
Avoid
For more information about ESP32, please refer to ESP32 Datasheet.
For more information about ESP32-S3, click ESP32-S3 Datasheet.
Use color blue and underline to indicate external hyperlinks. Do not rely on color by itself to indicate hyperlink text. Color-blind users will not be able to see the links.
In Pages and Word templates, use the Hyperlink character style, which underlines the characters and applies the color 0096FF (Hex Color #).
Example
For documents written in markup languages such as reStructuredText and Markdown, follow the existing style.
For other types of documents, please refer to their individual template.
Use color blue, underline, and italics when referring to the title of an article/book in English (see the example below). For documents written in markup languages such as reStructuredText and Markdown, follow the existing style.
Example
The font weight (e.g., light, medium, bold) of a cross-reference does not need to follow that of the sentence in which it appears.
Example
Download certificates for Espressif products from Espressif website.
For cross-references to document, chapter, or section titles, match the capitalization style of the document, chapter, or section title.
Cross-references in Chinese Text
Use book title marks (《…》) for Chinese titles of books, articles, newspapers, songs, films, etc.
Example
English
Chinese
Notes
For more information about ESP32, please refer to ESP32 Datasheet.
更多关于 ESP32 的信息请参考 《ESP32 技术规格书》。
There are no spaces around Chinese punctuation marks.
For cross-references to figures, tables, sections, or chapters in another publication, add one space before and after the title.
Example
建议参考 《ESP32-PICO-D4 技术规格书》 > 章节 外围设计原理图 了解更多信息。