GitHub Pages中README.md的<details>下拉框内Markdown格式渲染异常如何修复

修复方案 #

根本原因 #

GitHub Pages默认使用的kramdown Markdown解析器规则中，块级HTML标签内部的Markdown内容不会被自动解析，因此<details>标签内的列表、行内代码等格式都会失效，而GitHub自身的Markdown解析器对该场景做了兼容处理，所以在仓库README中可以正常展示。

具体修复步骤 #

1. 给<details>标签添加markdown="1"属性，显式告知kramdown需要解析该标签内部的Markdown内容
2. 确保<summary>闭合标签与内部Markdown内容之间保留至少一个空行
3. 如果<summary>内部需要使用Markdown格式（比如行内代码、加粗），可以额外给<summary>标签添加markdown="span"属性

修改后代码示例 #

### Adding a student: `student -a`
<details markdown="1">
<summary>Adds a student to the students list.</summary>

Format: `student -a -n NAME [-c CONTACT] [-em EMAIL] [-s DAY/STARTTIME/ENDTIME]​`

* Adds a student with the specified `NAME`
* `-a` refers to the add command
* Commands in `[ ]` are optional
* `DAY` takes in the following inputs: `MON TUE WED THU FRI SAT SUN` while `STARTTIME` and `ENDTIME` takes in the time in 24 hour format, for example 0800 for 8am.

Examples:
* `student -a -n John -c 12345678 -em john@mail.com -s TUE/1600/1800`<br>
  adds a student with the name John, contact number 12345678, email john@mail.com and a lesson every tuesday from 4pm to 6pm
* `student -a -n Barbara -c 12344321`<br>
  adds a student with the name Barbara and contact number 12344321

</details>

修改后重新推送到GitHub，触发Pages构建即可正常渲染<details>内部的所有Markdown格式。

内容的提问来源于stack exchange，提问作者hkcode