使用github RESTful API快速将markdown渲染为html

## 简介

现在 `Markdown` 编辑文本越来越主流，很多系统希望集成 Markdown 编辑器，编辑Markdown后，自然少不了渲染的事，但是渲染往往各自平台不同。如果你不知道选择哪家的渲染效果，又没有过多的特效要求，可以使用 GithubAPI 快速实现 Markdown 渲染。

本文就教会你如何使用 GithubAPI 渲染 Markdown。

<!-- more -->

## Github API

Github提供了很多其平台的开放API，并配有完整的文档：[GitHub REST API documentation](https://docs.github.com/en/rest?apiVersion=2022-11-28)，其中有 Markdown 相关的接口：[markdown](https://docs.github.com/en/rest/markdown/markdown?apiVersion=2022-11-28#render-a-markdown-document)，使用该接口可以将 `Markdown` 文本内容转换为 `Html`文本内容，当然是Github风格的。

文档中有接口详细的参数说明和相应示例代码，详情可自行查阅文档，本文推荐使用官方API工具 [Octokit](https://www.npmjs.com/package/octokit)。

> Octokit是一个适用于`Browsers`、`Node.js` 和 `Deno` 的全包 `GitHub SDK`，可通过 Npm 直接引用。

以Node项目为例，使用以下命令可以快速安装最新版 `Octokit`

```shell
# npm
npm install octokit
# yarn
yarn add octokit
```

安装成功后即可使用：
> 注意：`YOUR-TOKEN` 处可以设置一个你的Github Token，该接口使用的Token无需任何权限；不设置也可以调用接口，但是有频率限制。

```javascript
import { Octokit } from '@octokit/rest'
// Octokit.js
// https://github.com/octokit/core.js#readme
const octokit = new Octokit({
  auth: 'YOUR-TOKEN'
})

await octokit.request('POST /markdown', {
  // 要转换的Markdown文本
  text: 'Hello **world**',
  headers: {
    'X-GitHub-Api-Version': '2022-11-28'
  }
})
```

调用成功后的返回数据如下，其中`data`即转换结果：
```json
{
    "status": 200,
    "url": "https://api.github.com/markdown",
    "headers": {
        "cache-control": "public, max-age=60, s-maxage=60",
        "content-type": "text/html;charset=utf-8",
        "etag": "xxx",
        "x-github-media-type": "github.v3; format=json",
        "x-github-request-id": "xxx",
        "x-ratelimit-limit": "60",
        "x-ratelimit-remaining": "48",
        "x-ratelimit-reset": "xxx",
        "x-ratelimit-resource": "core",
        "x-ratelimit-used": "12"
    },
    "data": "<p>Hello <strong>world</strong></p>"
}
```

## 样式渲染

通过以上 API 将 Markdown 转换为 Html 后，你还需要有相应的CSS样式，才能后将Html内容渲染为和Github一样的页面，这里推荐一个CSS仓库：[github-markdown-css](https://github.com/sindresorhus/github-markdown-css)。

使用该仓库的CSS，可以将HTML渲染为和Github一样的页面效果。

使用发放也很简单：
1. CDN引用该CSS（`或者将CSS下载到本地后引入项目中`）；
2. 将对应的HTML父容器设置一个class：`markdown-body`。

## Vue3完整示例

```html
<template>
  <div id="markdown-container" class="markdown-body"></div>
</template>

<script setup type="ts">
// 引用 css
import 'https://cdnjs.cloudflare.com/ajax/libs/github-markdown-css/5.5.1/github-markdown.min.css'

import { onMounted } from 'vue'
import { GITHUB_API_TOKEN } from '@/stores/store.ts'
// 引用Octokit
import { Octokit } from '@octokit/rest'

// github api client
const octokit = new Octokit({
  auto: GITHUB_API_TOKEN
})
// 显示Markdown内容
const showMarkdown = () => {
  let downDiv = document.getElementById('markdown-container')
  // 小心这里不要死循环哦
  while (downDiv === null) {
    downDiv = document.getElementById('markdown-container')
  }

  octokit.request('POST /markdown', {
    text: 'Hello **world**'
  }).then((res) => {
    console.log(res)
    downDiv.innerHTML = res.data
  })
}

onMounted(() => {
  showMarkdown()
})

</script>

<style scoped>
</style>

```
## 赞助请求

 **建站不易，以下是一个广告，还请动动您的小拇指，点击一次以示鼓励，谢谢！**

<!-- 文章内嵌广告位 -->
<div class="article-ads"></div>

> 就目前的访问量，即便每个访客都点一次广告，收入也不足以支付运营成本，`如果看不到广告，可能是网络原因或被拦截了，那就算了吧。祝你生活愉快~~`