React展示markdown文件

• 概述
• 实现方式
  • 依赖的主要 package
  • 前端页面
  • markdown 文件位置
• 实现效果

概述

markdown 文件虽然可以转成 html 文件再展示在浏览器中， 但多了一层转换总觉得有些麻烦，特别是对于需要频繁改动的 markdown 文件。

所以，这里探索了一种直接在 React 工程中显示 Markdown 内容的方式。 把 markdown 文件当成静态 html 一样来展示，只要编辑保存 markdown 文件之后，就可以直接在浏览器中查看。

实现方式

这里主要记录如何在 React 工程中实现直接展示 markdown 文件，对于 React 工程的创建和运行不再赘述。

依赖的主要 package

首先下载这 3 个 npm package。

yarn add react-markdown   # 这是主要的package
yarn add remark-gfm       # 这个是插件，为了识别gfm格式的markdown
yarn add markdown-navbar  # 这个是为了生成目录

前端页面

前端页面 2 部分，一个 jsx，一个 css

import React, { useState, useEffect } from 'react';
import ReactMarkdown from 'react-markdown';
import gfm from 'remark-gfm';
import MarkNav from 'markdown-navbar';
import 'markdown-navbar/dist/navbar.css';
import './index.css';

const Help = () => {
  const [md, handleMD] = useState('loading... ...');

  useEffect(() => {
    fetch('/help-doc/help.md')
      .then((resp) => resp.text())
      .then((txt) => handleMD(txt));
  }, [md]);

  return (
    <div>
      <div className="nav-container">
        <MarkNav className="article-menu" source={md} headingTopOffset={80} ordered={false} />
      </div>
      <div className="article-container">
        <ReactMarkdown plugins={[[gfm, { singleTilde: false }]]} allowDangerousHtml>
          {md}
        </ReactMarkdown>
      </div>
    </div>
  );
};
export default Help;

.article-container {
  width: 960px;
  max-width: 100%;
  margin: 60px auto;
  padding: 20px 40px;
  background: #fff;
  box-shadow: 0 0 8px 0 rgba(0, 0, 0, 0.1);
}

.nav-container {
  position: fixed;
  right: 20px;
  top: 60px;
  background-color: #fff;
  border-radius: 5px;
  border: 1px solid #eee;
  box-shadow: 0 0 8px 0 rgba(0, 0, 0, 0.1);
  transform: translate(0, 0);
  transition: transform 500ms ease;
}

markdown 文件位置

markdown 文件静态文件目录下，本例中，放在了 public/help-doc 文件夹下面了。

$ tree help-doc
help-doc
├── chap2-1.mp4
├── chap2-2.mp4
├── chap2-3.mp4
├── chap2-4.mp4
├── help.md
└── modules.png

markdown 中引用图片的地方，比如：

## 1. 概要
目前整个平台包含如下几个模块: (**绿色**是已完成部分, **红色**是未完成部分)

![模块](/help-doc/modules.png)

引用视频的地方，比如：

### 2.1 定义数据类型

数据类型代表了某种类型的数据. 它们都有相同的字段.

<video width="500" height="300" controls>
<source src="/help-doc/chap2-1.mp4" type="video/mp4">
</video>

### 2.2 定义数据类型中的字段

实现效果

部署工程之后，只要修改静态目录下的 help.md 再保存，页面就会变化，不需要发布和转换 markdown 文件。

显示效果如下，此文档包括文字，图片和视频，均能正常显示。