github / github/markup

Render AsciiDoc admonitions with the same style as Markdown alerts (NOTE/TIP/IMPORTANT/WARNING/CAUTION)

未關閉
#2,091 2 則留言 5 個 reaction 已指派 0 人 在 GitHub 檢視
主要語言
Ruby
星號
6k
分支
3.4k
PR 合併指標
30 天內沒有已合併 PR

描述

When an AsciiDoc file (e.g. `README.adoc`) is rendered by `github/markup`, admonition blocks (`NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`) produce Asciidoctor's default HTML5 markup, which is a bare, unstyled ``:

```asciidoc
NOTE: This is a note.
```

renders as:

```html


Note

This is a note.

```

Image

Since github.com doesn't load Asciidoctor's stylesheet, this shows up as a plain, borderless table cell with the word "Note", no color, no icon, no visual distinction from the surrounding paragraph.

Compare this to the equivalent **Markdown alert**:

```markdown
> [!NOTE]
> This is a note.
```

which GitHub renders as:

```html


Note


This is a note.



```

Image

This picks up GitHub's built-in `.markdown-alert*` CSS automatically (colored left border, icon, colored title). AsciiDoc's five admonition types map 1:1 onto the five Markdown alert types (NOTE, TIP, IMPORTANT, WARNING, CAUTION), so there's no semantic gap, just a rendering gap.

## Proposal

`github/markup` already isolates the AsciiDoc rendering call in `lib/github/markups.rb`:

```ruby
Asciidoctor.convert(content, :safe => :secure, :attributes => attributes)
```

Rather than changing anything in Asciidoctor itself, github/markup could register a small custom HTML5 converter (a subclass of the default `Html5Converter`) that overrides **only** `convert_admonition`, and pass it as the `:backend`/`:converter` for this call. The override would emit the same `markdown-alert markdown-alert-` / `markdown-alert-title` markup already used (and already styled) for Markdown alerts, instead of Asciidoctor's `admonitionblock` table:

```ruby
class GithubAdmonitionConverter < (Asciidoctor::Converter.for 'html5')
register_for 'html5'

def convert_admonition node
name = node.attr 'name' # note, tip, important, warning, caution
label = node.attr 'textlabel' # Note, Tip, Important, Warning, Caution
%(


#{label}


#{node.content}
)
end
end
```

(the appropriate inline SVG icon per type could be added to match the ones GitHub already uses for Markdown alerts)

This requires no change to Asciidoctor itself and no new CSS on GitHub's side. It just reuses the classes/styles GitHub already ships for Markdown alerts.

I'm happy to contribute this change (the converter + wiring it into the `.adoc` render path) as a PR if that's a direction you'd be open to. Just let me know!

貢獻指南

開啟貢獻指南

研究方向

從 lib/github/markups.rb 開始,檢查 Asciidoctor.convert 呼叫和現有的 .adoc 渲染路徑。當 AsciiDoc 的 NOTE、TIP、IMPORTANT、WARNING 和 CAUTION 區塊輸出 markdown-alert 類別和標題標記,讓 GitHub 現有的樣式套用時,即表示完成。

由索引模型根據 Issue 內容生成。

評估

技術堆疊
ruby
領域
documentation
Issue 類型
功能
難度
4/5
預估耗時
3-5 天
活躍度
冷清
描述清晰度
基本清楚
新手友好度
55/100

把新 issue 寄到你的電子郵件信箱

精選適合新手參與的 GitHub issue 摘要。