如何在GitHub Gist中创建一个样式化的Markdown警示框?

190
我正在尝试制作一个类似于GitHub Gist的Markdown提示框,比如注释框、警告框。我在Google上搜索了一些Python的Markdown提示,但这些提示似乎在GitHub Gist上不起作用。
我尝试了以下的Python警告提示,但这种Markdown语法在GitHub Gist上不起作用。
!!! Hello Admonition

我也尝试过像这样的引导框,但它的样式不如预期。
<div class="alert alert-danger" role="alert">
    <div class="row vertical-align">
        <div class="col-xs-1 text-center">
            <i class="fa fa-exclamation-triangle fa-2x"/>
        </div>
        <div class="col-xs-11">
            <strong>Error:</strong>
        </div>
    </div>
</div>

GitHub Gist有没有任何警告语法或HTML代码方法?

3
这是一个有关"警示语"的已关闭的GitHub问题 - toraritte
1
相关问题 - young_souvlaki
1
这在2022年得到了GitHub GFM的支持(https://dev59.com/elUL5IYBdhLWcg3wUWit#72327818)。 - VonC
11个回答

304

5
值得一提的是,要获取Unicode警告符号的黄色/表情符号版本,请在其后面加上“变量选择器-16”字符(例如,通过HTML实体引用:&#x26a0;&#xfe0f;)。 - anthonyrisinger
9
不必费时寻找、复制和粘贴表情符号本身,你可以直接使用:warning: - Swivel
2
@Swivel 感谢您的建议,我已经更改了我的答案,以便具有 GitHub Markdown。 - Tiago Mendes
4
如果你使用的是不支持 GitHub 表情符号的其他 Markdown 处理器,那么这只能在 GitHub Markdown 中使用。 - Swivel
2
不要这样做。> 是用于块引用的。根据 W3C,“blockquote” 元素表示引用自另一个来源的部分。由于您没有引用任何内容,因此这是错误的元素。如果您想要警告,AsciiDoc 和 reStructured Text 都支持警告。CommonMark 中也有一个开放的 RFC 用于警告。 - toastal
显示剩余6条评论

121

2023年7月

我们根据您的反馈进行了几项改进:
- 输出现在将呈现为一个 div 而不是一个 blockquote。 - 文本颜色已从之前的柔和版本更改为主要颜色。 - 我们已经加强了解析规则,以防止与其他 Markdown 或 HTML 冲突。 因此,标题后面现在需要一个换行符。 - 我们引入了一个新的警告类型 "IMPORTANT"。 - 添加了一种新的语法 "[!NOTE]",逐渐取代旧的语法。然而,旧的语法将继续使用一段时间。
注意: 在 Markdown 文件中,可以通过两个空格 "[!NOTE] ",反斜杠 "[!NOTE]\" 或 html "
" 来实现硬换行。
以下是三种类型的示例(在 "] " 后面有两个空格): > [!NOTE] > 强调用户在浏览时应该考虑的信息。 > [!IMPORTANT] > 用户成功所必需的关键信息。 > [!WARNING] > 由于潜在风险,需要立即引起用户注意的关键内容。
以下是它们的显示方式: highlights
2022年5月,原始答案:
虽然不完全是一种警告,但自2022年5月以来,这一点得到了支持(进行了测试),正如Diego Haz所报道的,并在讨论16925中描述的那样。

To better highlight and separate certain information from the rest in your documentation on GitHub, we now render a special and accessible note or warning blockquote in Markdown documents.

We are using the existing syntax for blockquote and bold text.

The first line must be exactly as shown below.
The first letter is case sensitive. The second line can contain your content.

This input:

> **Note**
> This is a note

> **Warning**
> This is a warning

Becomes:

Note / This is a note and Warning / This is a warning

警告:语法可能仍在演变中,并在讨论中进行辩论。例如,Brenton M. Wiernik comments

除了其他人提出的语法问题和语义网问题之外,我还担心这会在GitHub-Flavored Markdown和pandoc markdown或CommonMark之间引入重大的不兼容性。

许多R开发人员使用RMarkdown编写README和其他文档,通常使用pandoc进行处理。

这个改变意味着当用户的软件包文档在GitHub上显示和其他地方显示时,无法以相同的语法获得一致的渲染。

以这种方式重载引用块会在不同的markdown风格中创建一个意义上的不透明差异,对开发人员来说很难解决。


使用 VSCode, Ian Sanders 提出了以下建议:

这里有一些 VSCode 代码片段,可以帮助你更容易地记住它们

{
    "Note": {
        "prefix": "note",
        "body": [
            "> [!NOTE]",
            "> $1"
        ],
        "description": "GFM Note block"
    },
    "Important": {
        "prefix": "important",
        "body": [
            "> [!IMPORTANT]",
            "> $1"
        ],
        "description": "GFM Important block"
    },
    "Warning": {
        "prefix": "warning",
        "body": [
            "> [!WARNING]",
            "> $1"
        ],
        "description": "GFM Warning block"
    }
}

1
你需要在 **Warning** 后面添加 <br> 以使其分成两行。 - Ramtin
4
@Ramtin 如果它遵循Markdown约定,那么在“Warning”后添加两个尾随空格应该可以启用br。 - VonC
截至2023年7月中旬,以上任何一种都可以。 - Christian
1
请注意,自上述内容撰写以来,语法已发生变化。请参阅帖子了解详细信息。新的语法是 [!WARNING] (是的,括号后面有两个空格 - 这些是必需的)。 - scode
@scode 谢谢您的反馈和更新。我已经编辑答案,包括新的语法和新的关键词。 - VonC
1
请注意,在编辑 markdown 文件时,预览器中可能不会显示警告框。只有在提交更改后,它们才会出现在我的 README 文件中。 - undefined

100

您可以使用表格来制作带有加粗文本的框,例如:

| WARNING: be careful to baz the quux before initializing the retro encabulator! |
| --- |

这样呈现:

一个单元格表格的图像,其中包含文本“WARNING: be careful to baz the quux before initializing the retro encabulator!”

这有点滥用语法,但它能起作用。如Chris所指出的那样,不幸的是无法应用其他格式比如颜色。


由于某种原因,连接符数量会决定盒子的宽度!(我通过添加许多连接符来解决了这个问题) 但是,为什么会发生这种情况呢? - nilon
1
一个带有表情符号“图标”的单元格表格非常好看,例如<table><td>:warning: 不要那样做!</td></table>非常简单直观且好看。您还可以在内部包含常规的markdown文本。 - patricksurry
滥用Markdown语法,但表格没有太多的语义意义(还记得在CSS之前我们用表格来做_所有_的事情吗?)。输出的HTML足够“好”。如果你必须因为限制而使用Markdown和/或无法控制平台的CSS,这是一个不错的选择。 - undefined

71

我参与过的大多数代码仓库都使用块引用来模拟警示信息:

> **WARNING**: Be careful, or else!
下面是一个示例,它在顶部和内部都被使用了:

enter image description here


这不是语义化标记,应该避免使用。 - toastal
有几个值得考虑的选项:1.使用AsciiDoc或reStructuredText,因为两者都内置了警告语法。如果需要在forge/snippets上呈现,则Codeberg、GitLab和GitHub等流行的forge都支持这两种语言——Gitea只需添加少量配置即可,而SourceHut可以将任意HTML POST到README中,因此可以脚本化转换。2.全大写也可以(例如DANGER: text);如果需要,可以加粗。3.如果GitHub将忽略CommonMark RFC指令并通过不合理的块引用在其分支中推出警告(在GitHub之外没有支持),则不要使用GitHub。 - toastal
1
真正让人烦恼的是,RST 有警告,但 GitHub 并不会将它们呈现为警告。然而,当在 RST 中输入时,beta 功能确实会呈现这些 blockquote 警告。 - Nick K9

34

使用UTF8符号的标准Markdown看起来非常好:

> **⚠ WARNING: Aliens are coming.**  
> A description of the colour, smell and dangerous behaviour of the aliens.

呈现效果如下:

⚠ 警告:外星人正在接近。
对外星人的颜色、气味和危险行为的描述。


注意:外观好看 ≠ 语义正确 - toastal

8
GitHub Flavored Markdown没有类似的功能,而且其HTML(生成或内联)会被严格过滤
你可能只能使用基础功能,例如:
_**Warning:** Be very careful here._

或者

### Warning

Be very careful here

6

最简单的方法:

| This project was moved and hosted on Render. |
|----------------------------------------------|

将会产生以下结果:

此项目已迁移到 Render 并由其托管。

1
这有点聪明 :) - webketje
保持简单 :) - Vidarshan Rathnayake

5
你可以使用表格或引用(仅在Gitlab和Github上测试过):

使用表格

| ⚠️ Warning                               | 
|------------------------------------------|
| You shouldn't. This is irreversible!     |

| ❌ Error                                 | 
|------------------------------------------|
| Don't do that. This is irreversible!     |

| ℹ️ Information                           | 
|------------------------------------------|
| You can do that without problem.         |

| ✅ Success                               | 
|------------------------------------------|
| Don't hesitate to do that.               |

|  New line support                       | 
|-------------------------------------------|
| It supports new lines:<br/>.. simply use `<br/>` for new lines|

Abominations using tables

使用引号

> **⚠️ Warning**
>
> You shouldn't. This is irreversible!

> **❌ Error**
>
> Don't do that. This is irreversible!

> **ℹ️ Information**
>
> You can do that without problem.

> **✅ Success**
>
> Don't hesitate to do that.

> ** New line support**
> 
> It supports new lines:
>
> .. simply use an empty `>` line
>

Abominations using quotes


1

您可以使用带有适当颜色图标和文本的SVG。例如,代码

> <picture>
>   <source media="(prefers-color-scheme: light)" srcset="https://github.com/Mqxx/GitHub-Markdown/blob/main/blockquotes/badge/light-theme/warning.svg">
>   <img alt="Warning" src="https://github.com/Mqxx/GitHub-Markdown/blob/main/blockquotes/badge/dark-theme/warning.svg">
> </picture><br>
>
> Warning

产生

enter image description here

这里可以找到更多的例子这里

Github的beta解决方案相比,如果Github回退了提议的语法,这个解决方案不会出现问题。然而,如果仓库崩溃,它将会出现问题;当然你可以克隆它。另外,由于它是SVG格式,你不能使用ctrl + f搜索warning


-1

MkDocs的材料提供了几种不同类型的警告,并允许包含和嵌套任意内容。

首先,您应该配置

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

然后,您可以在Markdown中使用警告

!!! note

  Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
  nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
  massa, nec semper lorem quam in massa.

来源:https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types


1
虽然这个链接可能回答了问题,但最好在此处包含答案的基本部分并提供参考链接。如果链接页面更改,仅有链接的答案可能会失效。-【来自审查】 - alparslan mimaroğlu
2
该链接指向的是 mkdocs-material 的文档,而不是 GitHub Flavored Markdown 的文档。 - Adrian Schmidt
但我在Markdown文件中使用类似这样的方式,它可以正常工作。:::提示 信息Lorem Ipsum只是虚拟文本:::: - ufukcam
这与MkDocs有关,但根据ufukcam的评论,我决定保留此帖子。 - boj

网页内容由stack overflow 提供, 点击上面的
可以查看英文原文,
原文链接