github / github/markup

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

Đang mở
#2,091 2 bình luận 5 reaction 0 người được giao Xem trên GitHub
Ngôn ngữ chính
Ruby
Star
6k
Fork
3.4k
Chỉ số merge pull request
Không có pull request nào được merge trong 30 ngày

Mô tả

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!

Hướng dẫn đóng góp

Mở hướng dẫn đóng góp

Hướng nghiên cứu

Start in lib/github/markups.rb and inspect the Asciidoctor.convert call and the existing .adoc rendering path. Done means AsciiDoc NOTE, TIP, IMPORTANT, WARNING, and CAUTION blocks emit the markdown-alert classes and title markup so GitHub's existing styling applies.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Đánh giá

Công nghệ
ruby
Lĩnh vực
documentation
Loại issue
Tính năng
Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức độ hoạt động
Ít trao đổi
Độ rõ ràng
Khá rõ ràng
Mức phù hợp với người mới
55/100

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.