string.markdown 库模块帮助文档

说明

string.markdown（Sundown）解析器默认规则

列表解析默认使用宽松规则。无论一级列表还是二级列表（无论类型是否相同），都不要求前面有或没有空行。
标题的开始标记 # 号后面必须有空格。
强调语法对于下划线使用严格模式，其他标记使用宽松模式
- 所有强调标记内侧都不能紧邻空白字符
- 强调标记为 *、 *、~~ 时对外侧紧邻字符不作要求。
- 强调标记为下划线 _ 时，如果指定了 _MD_MKDEXT_NO_INTRA_EMPHASIS 选项（默认设置）：
  - 首尾标记内侧都不能有空白字符
  - 开始标记外侧不能是字母或数字。
  - 结束标记如果是单下划线则要求尾部紧邻的字符不能是字母或数字。
  目前主流的 Markdon 解析器 *、 *、~~ 的要求与上面相同（宽松规则）。但对下划线强调语法多采用严格规则，要求首尾外侧有空白字符或标点符号（一些解析器识别中文标点）。 _MD_MKDEXT_NO_INTRA_EMPHASIS 对下划线强调的要求则更为宽松（仅检测英文字母数字）。
  
  目前主流的写法基本都不会使用下划线表示强调。但基本所有解析器都对下划线强调语法保持了兼容。
  
  文档中下划线开头的常量或变量可以置入内联代码块。例如 `_CMDLINE `，代码块内不会解析其他 Markdown 语法（包括强调标记）。或者用在下划线前面加上 Markdown 转义符（反斜杆）。例如 \_CMDLINE 。
默认启用删除线扩展，示例： ~~这里显示删除线~~ 。
默认启用表格扩展。
默认启用围栏代码块（Fenced Code Blocks）扩展。多行围栏代码块支持嵌套，可使用 3 个以上的反引号，要点：
- 首尾反引号数目要配对。
- 首尾反引号都必须是单独一行。
- 开始的反引号标记后面可以写语言名称，尾部反引号标记后面不能有其他非空白字符。
NCR 编码的 Font Awesome 字符将输出为 span 标签并添加 fa 类。 web.form.simpleMarkdown/web.form.chat 也在 CSS 中声明了 fa 类，但需要提前导入 fonts.fontAwesome 库。
默认支持可选列表（checklist）扩展。

可选列表（checklist）除了兼容只读的任务列表格式，也可以设为可选状态，并支持自动识别与转换字符序号。方便用于 AI 生成试题（答案可用 details,summary 标签折叠显示。

HTML 渲染选项指定 0x400/*_MD_HTML_TASK_ENABLED*/ 则复选框显示为启用状态。也可以调用 setTaskCheckboxEnabled 方法设置复选框是否显示为启用状态，默认显示为禁用状态。
支持字母排序列表。
- 如果列表项列表项以 +、-、* 开始，而列表内容以“大写字母 + 圆点 + 空格”的大写字母序号开始则转换为字母排序列表。
- 如果同时指定了复选框，复选框标记必须在字母序号之前。
示例：
```
- A. 列表项 1
- B. 列表项 2
    - [ ] A. 选项一
    - [ ] B. 选项二
```
可识别并跳过 Front Matter 。

string.csv 解析 Markdown 表格

使用 string.csv 并将列分隔符指定为 | 可解码编码 Markdown 表格，但 string.csv 并不解析 Markdown 转义符，并且默认会将每列的首尾双引号识别为引用段。

高频 KaTeX 符号

以下 KaTeX 单符号内联公式自动转换为 NCR 编码：

$\rightarrow$ → $\Rightarrow$ ⇒ $\to$ → $\Leftarrow$ ⇐ $\leftarrow$ ← $\Leftrightarrow$ ⇔ $\leftrightarrow$ ↔ $\cdot$ · $\times$ × $\pm$ ± $\approx$ ≈ $\neq$ ≠ $\leq$ ≤ $\geq$ ≥ $\equiv$ ≡ $\ldots$ … $\infty$ ∞ $\alpha$ α $\beta$ β $\lambda$ λ $\pi$ π $\theta$ θ $\mu$ μ $\sigma$ σ $\Delta$ Δ

内联 KaTeX 公式要求：

开始的 $ 前不能紧跟字母或数字，不能有反斜杆
尾部的 $ 后不能紧跟字母或数字

string 成员列表 #

string.markdown() #

返回对象:stringMarkdownObject

string.markdown(extensions,maxNesting,htmlRenderFlags) #

创建 MARKDOWN 解析器,所有参数可选。

参数 @extensions 用 MD_MKDEXT 前缀常量组合自定义需要启用的扩展。参数 @maxNesting 指定最大嵌套级别，默认为 16，一般不必修改。
参数 @htmlRenderFlags 指定 HTML 渲染选项（多个选或用 | 连接），
如果指定 0x400/*_MD_HTML_TASK_ENABLED*/ 则任务列表中的复选框显示为启用状态。
@htmlRenderFlags 如果指定 1/*_MD_HTML_SKIP_HTML*/ 则丢弃所有 HTML 标签。

string.markdown(extensions,maxNesting,htmlRenderFlags,useCallbacks) #

string.markdown(8,,,{  
    blockcode = function(ob, text, lang, opaque){    
        ob = string.markdown.buffer(ob);  
        text = string.markdown.buffer(text);  
        ob.put( tostring(text) )  
    };   
} );

string.markdown(markdown,extensions,maxNesting,htmlRenderFlags) #

直接解析字符串参数 @markdown 并返回 HTML。
其他参数用法请参考用法参考下面。

string.markdown 成员列表 #

string.markdown.buffer() #

返回对象:stringMarkdownBufObject

string.markdown.buffer(缓冲区初始大小) #

创建 string.markdown 专用的缓冲区,参数可选（返回字符串首尾加空行）。
返回结构体（返回值不是 buffer 类型，不要混淆）。
aardio 的 string 与 buffer 类型在尾部有 2 个不可见的 NUL 字符以防御越界。
并且操作 string,buffer 的函数基本都会检查越界操作。
但 string.markdown.buffer 结构体尾部没有这些防御越界的措施。
因此操作它要非常谨慎，如无必要，尽量不要直接创建或使用这个对象。

string.markdown.codeBlock #

安全构造围栏式代码块。
此函数指向类库函数 string.fencedCodeBlock

string.markdown.codeBlock(code,lang,tag,newline) #

将 @code 参数指定的代码首尾加上围栏式代码块标记（返回字符串首尾有换行）。
可选用 @lang 指定编程语言名称。
可选用 @tag 指定标记（默认为三重反引号）。
如果代码已经包含 @tag ，则会加长标记直到没有冲突。
可选用 @newline 指定换行符，默认使用 LF，
如果 @code 包含了 CR+LF 则使用 CR+LF

stringMarkdownBufObject 成员列表 #

stringMarkdownBufObject.data() #

返回缓冲区指针

stringMarkdownBufObject.grow(增加大小) #

增加缓冲区大小

stringMarkdownBufObject.printf("%s",其他格式化参数) #

写放格式化字符串,
格式化语法与 string.format相同

stringMarkdownBufObject.put(写入数据,长度) #

写入数据到缓冲区,长度为可选参数

stringMarkdownBufObject.size() #

返回缓冲区数据大小

stringMarkdownBufObject.totring() #

返回缓冲区文本

stringMarkdownObject 成员列表 #

stringMarkdownObject.render(markdownText) #

解析参数 @markdownText 指定的 Markdown 文本并返回 HTML。
自动调用 tostring 函数将参数 @markdownText 转换为字符串。

stringMarkdownObject.renderCode(code,lang) #

将 @cdode 参数指定的编程代码置入 Markkdown 围栏代码块中，
然后转换并返回为 HTML 代码，自动处理嵌套的 Markkdown 代码块标记。
可选用 lang 参数指定编程语言名称

stringMarkdownObject.renderFile(markdownFilePath) #

解析参数 @markdownFilePath 指定的 Markdown 文件并返回 HTML

stringMarkdownObject.setRenderFlags(flags,disabled) #

设置 HTML 渲染选项。

参数 @1 指定一个或多个（按位或） MD_HTML 前缀的选项数值。
参数 @2 为 true 则禁用指定的选项，否则启用。

stringMarkdownObject.setTaskCheckboxEnabled() #

任务列表中显示的复选项是否显示为启用状态。
参数 @1 指定是否启用，默认显示为禁用状态。

自动完成常量

_MD_HTML_ESCAPE=0x200
_MD_HTML_EXPAND_TABS=0x10
_MD_HTML_HARD_WRAP=0x80
_MD_HTML_SAFELINK=0x20
_MD_HTML_SKIP_HTML=1
_MD_HTML_SKIP_IMAGES=4
_MD_HTML_SKIP_LINKS=8
_MD_HTML_SKIP_STYLE=2
_MD_HTML_TASK_ENABLED=0x400
_MD_HTML_TOC=0x40
_MD_HTML_USE_XHTML=0x100
_MD_MKDA_EMAIL=2
_MD_MKDA_NORMAL=1
_MD_MKDA_NOT_AUTOLINK=0
_MD_MKDEXT_AUTOLINK=8
_MD_MKDEXT_FENCED_CODE=4
_MD_MKDEXT_LAX_SPACING=0x100
_MD_MKDEXT_NO_INTRA_EMPHASIS=1
_MD_MKDEXT_SPACE_HEADERS=0x40
_MD_MKDEXT_STRIKETHROUGH=0x10
_MD_MKDEXT_SUPERSCRIPT=0x80
_MD_MKDEXT_TABLES=2
_MD_MKD_TABLE_ALIGNMASK=3
_MD_MKD_TABLE_ALIGN_CENTER=3
_MD_MKD_TABLE_ALIGN_L=1
_MD_MKD_TABLE_ALIGN_R=2
_MD_MKD_TABLE_HEADER=4

Markdown 格式