# 模板变量 Markdown 导出配置 .md 格式

Published at: 2026-04-08 17:12:48

## 标题

模板变量 Markdown 导出配置 .md 格式

## 内容

Baklib 模板目前都支持 .md 格式的变体，也就说当你浏览任何页面，都可以在 URL 后面添加 .md 从而打开 MD 格式的文本。

👋

例如当前页面的链接为： [https://dev.baklib.cn/faqs/267588](https://dev.baklib.cn/faqs/267588)

则 MD 格式链接为： [https://dev.baklib.cn/faqs/267588.md](https://dev.baklib.cn/faqs/267588.md)

## **配置方式**


### **1. 模板 Schema 配置**


在模板 JSON Schema 中，通过添加 `to_markdown: true` 标记需要导出的变量：

```json
{
 "id": "content",
 "type": "richtext",
 "label": "正文内容",
 "to_markdown": true
}
```


### **2. 批量配置示例**


```json
{
 "settings": [
 {
 "id": "title",
 "type": "text",
 "label": "标题",
 "to_markdown": true
 },
 {
 "id": "summary",
 "type": "textarea",
 "label": "摘要",
 "to_markdown": true
 },
 {
 "id": "body",
 "type": "richtext",
 "label": "正文",
 "to_markdown": true
 },
 {
 "id": "cover_image",
 "type": "image_picker",
 "label": "封面图",
 "to_markdown": true
 }
 ]
}
```


## **支持的字段类型映射**


| <strong>类型分类</strong> | <strong>具体类型</strong> | <strong>Markdown 输出行为</strong> |
| --- | --- | --- |
| <strong>富文本类型</strong> (<code>RICH_TYPES</code>) | <code>richtext</code>, <code>html</code> | 通过 <code>FragmentValue.to_markdown</code> 转换 |
| <strong>纯文本类型</strong> (<code>PLAIN_TEXT_TYPES</code>) | <code>text</code>, <code>textarea</code>, <code>paragraph</code> | 直接输出字符串 |
| <strong>代码类型</strong> (<code>CODE_TYPES</code>) | <code>code</code> | 包裹为代码块，支持 <code>language</code> 指定语法 |
| <strong>选项类型</strong> (<code>CHOICE_TYPES</code>) | <code>select</code>, <code>radio</code>, <code>checkbox</code>, <code>link</code> | 直接输出值 |
| <strong>简单值类型</strong> (<code>SIMPLE_VALUE_TYPES</code>) | <code>number</code>, <code>range</code>, <code>date</code>, <code>color</code>, <code>font_picker</code>, <code>color_background</code> | 直接输出字符串 |
| <strong>资源选择器</strong> (<code>PICKER_TYPES</code>) | <code>image_picker</code>, <code>file_picker</code>, <code>video_picker</code>, <code>dam_picker</code> | 生成 20 分钟有效期的前端访问地址 |
| <strong>标签选择器</strong> (<code>TAG_PICKER_TYPE</code>) | <code>tag_picker</code> | 输出标签名称列表 |

## **输出格式**


### **标准段落格式**


每个启用了 `to_markdown: true` 的变量输出为：

```markdown
## {label}

{转换后的内容}
```


其中 `label` 优先取 `setting["label"]`，否则使用 `id.humanize`。

### **各类型详细输出示例**


#### **富文本类型**


输入 HTML 内容：

```html
<p>这是一段<strong>加粗</strong>的文本。</p>
```


输出：

```markdown
## 正文

这是一段**加粗**的文本。
```


#### **代码类型**


Schema 配置：

```json
{
 "id": "script",
 "type": "code",
 "label": "脚本代码",
 "language": "javascript",
 "to_markdown": true
}
```


输出：

```markdown
## 脚本代码

```javascript
const x = 1;
```


    #### 图片选择器
    
    输出 Markdown 图片语法：
    ```markdown
    ## 封面图
    
    ![图片名称](https://portal.example.com/signed-url?expires=...)


#### **文件/视频选择器**


仅输出 URL 字符串（无 Markdown 包裹）：

    ## 附件
    
    https://portal.example.com/signed-url?expires=...


#### **标签选择器**


根据标签 IID 输出名称列表：

```markdown
## 标签

技术, 文档, 教程
```


## **资源链接有效期配置**


资源选择器生成的 URL 有效期默认为 20 分钟，可通过修改常量调整：

```ruby
# app/models/page/to_markdown.rb
PORTAL_URL_EXPIRES_IN = 20.minutes
```