Implement Markdown Callouts for Enhanced Documentation Clarity #12426

New Issue

GiteaMirror · 2025-11-02T10:09:22-06:00

GiteaMirror commented

2025-11-02 10:09:22 -06:00

Originally created by @miztizm on GitHub (Feb 3, 2024).

Feature Description

I propose the implementation of Markdown callouts in Gitea to enhance the clarity and effectiveness of documentation, issue discussions, and markdown files within repositories. Callouts, such as notes, tips, warnings, and cautions, are crucial for emphasizing important information, guiding users successfully through documentation, and ensuring critical warnings are not overlooked.

Markdown callouts would allow users to highlight various types of information distinctly, making it easier for readers to find and heed advice, warnings, and tips. The proposed syntax follows an intuitive format, leveraging Markdown's extensibility to include custom identifiers for different callout types:

Note (!NOTE): Highlights information that users should take into account, even when skimming.
Tip (!TIP): Provides optional information to help users be more successful.
Important (!IMPORTANT): Marks crucial information necessary for users to succeed.
Warning (!WARNING): Signals critical content that demands immediate attention due to potential risks.
Caution (!CAUTION): Indicates negative potential consequences of an action.

Note

This is a note.

Tip

This is a tip.

Important

This is an important note.

Warning

This is a warning.

Caution

This is a caution.`

Benefits

Enhanced Documentation Quality: By making it easier to create visually distinct, categorized informational blocks, we can improve the overall quality and user-friendliness of documentation in Gitea.
Increased User Success: Callouts can guide users more effectively through complex documentation, increasing their success and reducing frustration.
Improved Safety and Awareness: Clearly marked warnings and cautions can prevent users from making mistakes that could have serious consequences.

Screenshots

No response

Originally created by @miztizm on GitHub (Feb 3, 2024). ### Feature Description I propose the implementation of Markdown callouts in Gitea to enhance the clarity and effectiveness of documentation, issue discussions, and markdown files within repositories. Callouts, such as notes, tips, warnings, and cautions, are crucial for emphasizing important information, guiding users successfully through documentation, and ensuring critical warnings are not overlooked. Markdown callouts would allow users to highlight various types of information distinctly, making it easier for readers to find and heed advice, warnings, and tips. The proposed syntax follows an intuitive format, leveraging Markdown's extensibility to include custom identifiers for different callout types: - **Note (`!NOTE`)**: Highlights information that users should take into account, even when skimming. - **Tip (`!TIP`)**: Provides optional information to help users be more successful. - **Important (`!IMPORTANT`)**: Marks crucial information necessary for users to succeed. - **Warning (`!WARNING`)**: Signals critical content that demands immediate attention due to potential risks. - **Caution (`!CAUTION`)**: Indicates negative potential consequences of an action. > [!NOTE] > This is a note. > [!TIP] > This is a tip. > [!IMPORTANT] > This is an important note. > [!WARNING] > This is a warning. > [!CAUTION] > This is a caution.` #### Benefits - **Enhanced Documentation Quality**: By making it easier to create visually distinct, categorized informational blocks, we can improve the overall quality and user-friendliness of documentation in Gitea. - **Increased User Success**: Callouts can guide users more effectively through complex documentation, increasing their success and reducing frustration. - **Improved Safety and Awareness**: Clearly marked warnings and cautions can prevent users from making mistakes that could have serious consequences. ### Screenshots _No response_

GiteaMirror added the type/proposal label 2025-11-02 10:09:22 -06:00

GiteaMirror closed this issue

2025-11-02 10:09:23 -06:00

GiteaMirror commented

2025-11-02 10:09:23 -06:00

@yardenshoham commented on GitHub (Feb 3, 2024):

Duplicate of https://github.com/go-gitea/gitea/issues/28316

@yardenshoham commented on GitHub (Feb 3, 2024): Duplicate of https://github.com/go-gitea/gitea/issues/28316

GiteaMirror commented

2025-11-02 10:09:23 -06:00

@yardenshoham commented on GitHub (Feb 10, 2024):

It's ready. It will be part of version 1.22.0

@yardenshoham commented on GitHub (Feb 10, 2024): It's ready. It will be part of version 1.22.0

GiteaMirror commented

2025-11-02 10:09:23 -06:00

@github-actions[bot] commented on GitHub (Feb 28, 2024):

Automatically locked because of our CONTRIBUTING guidelines

@github-actions[bot] commented on GitHub (Feb 28, 2024): Automatically locked because of our [CONTRIBUTING guidelines](https://github.com/go-gitea/gitea/blob/main/CONTRIBUTING.md#issue-locking)

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#12426