舍弃传统文档阅读吧！～新一代代码文档神器code-hike

以你之姓@ 2023-09-24 23:04 5阅读 0赞

## 起因 ##

相信不少小伙伴阅读过一篇文章：[build-your-own-react][]

这是一篇通俗易懂的从头开始讲述如何创建一个react过程的文章，其中最吸引我的就是这个文章的代码排版方式。将所有代码放置在左侧，随着文档的滚动，左侧代码不断发生变化，不断提示我哪些代码发生了变动。这样的文档方式，是我之前没体验过的船新版本。去作者的gayhub看到正好有开源工具，于是自己搭建了demo，马上惊为天人。`所以在这里我要做一个违背祖宗的决定`，将其分享给大家。

## code-hike简介 ##

[codehike.org/][codehike.org] code-hike是一个 mdx的插件，专注于文档写作的组件库。专注于代码的展示，具有以下几个功能：

### 代码块的展示 ###

![format_png][]

支持134种不同的编程语言，基本涵盖了目前市面上的编程语言。

### 批注和对代码的交互体验 ###

![format_png 1][]

可以看到在code-hike中可以对部分代码进行高亮显示，这部分主要通过force和mark来操作。同时它还允许你在代码块中进行链接，可以点击跳转到页面的其他位置。也可以自定义自己的样式显示。

### 一系列的code组件 ###

一系列帮你优化code展示的组件，在本文中，将主要使用`CH-scrollycoding`作为展示。

## 安装 ##

我们这里以`Docusaurus`为例作为展示，当然你也可以使用React，vite或其他任意模版或者docs框架作为开始。

我们首先安装docusaurus

npx create-docusaurus@latest my-website classic
    复制代码

然后安装hike的相关依赖

cd my-website  
    
    npm i @mdx-js/react@2 docusaurus-theme-mdx-v2 @code-hike/mdx
    复制代码

### 配置 ###

首先配置`docusaurus.config.js`，插入`mdx-v2`主题

// docusaurus.config.js
    
    const config = {
        ...
        themes: ["mdx-v2"],
        ...
    }
    
    复制代码

然后插入code-hike插件

// docusaurus.config.js
    const theme = require("shiki/themes/nord.json")
    const {
      remarkCodeHike,
    } = require("@code-hike/mdx")
    
    const config = {
        presets: [
          [
            "classic",
            {
              docs: {
                beforeDefaultRemarkPlugins: [
                  [remarkCodeHike, { theme }],
                ],
                sidebarPath: require.resolve("./sidebars.js"),
              },
            },
          ],
        ],
        ...
     }
    
    复制代码

再设置下style

// docusaurus.config.js
     ... 
    const config={
    
        theme: {
            customCss: [
              require.resolve("@code-hike/mdx/styles.css"),
            ],
          },
        }
    }
    复制代码

至此所有配置完成，我的完整配置如下:

// @ts-check
    // Note: type annotations allow type checking and IDEs autocompletion
    
    const lightCodeTheme = require("prism-react-renderer/themes/github");
    const darkCodeTheme = require("prism-react-renderer/themes/dracula");
    
    const theme = require("shiki/themes/nord.json");
    const { remarkCodeHike } = require("@code-hike/mdx");
    
    /** @type {import('@docusaurus/types').Config} */
    const config = {
      title: "css and js",
      tagline: "read everyday",
      url: "https://your-docusaurus-test-site.com",
      baseUrl: "/",
      onBrokenLinks: "throw",
      onBrokenMarkdownLinks: "warn",
      favicon: "img/favicon.ico",
    
      // GitHub pages deployment config.
      // If you aren't using GitHub pages, you don't need these.
      organizationName: "facebook", // Usually your GitHub org/user name.
      projectName: "docusaurus", // Usually your repo name.
    
      // Even if you don't use internalization, you can use this field to set useful
      // metadata like html lang. For example, if your site is Chinese, you may want
      // to replace "en" with "zh-Hans".
      i18n: {
        defaultLocale: "en",
        locales: ["en"],
      },
    
      presets: [
        [
          "classic",
          /** @type {import('@docusaurus/preset-classic').Options} */
          ({
            
            docs: {
              beforeDefaultRemarkPlugins: [[remarkCodeHike, { theme }]],
              sidebarPath: require.resolve("./sidebars.js"),
              // Please change this to your repo.
              // Remove this to remove the "edit this page" links.
              editUrl:
                "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
            },
            blog: {
              showReadingTime: true,
              // Please change this to your repo.
              // Remove this to remove the "edit this page" links.
              editUrl:
                "https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/",
            },
            theme: {
              customCss: [
                require.resolve("@code-hike/mdx/styles.css"),
                require.resolve("./src/css/custom.css"),
              ],
            },
          }),
        ],
      ],
      themes: ["mdx-v2"],
    
      themeConfig:
        /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
        ({
          navbar: {
            title: "My Site",
            logo: {
              alt: "My Site Logo",
              src: "img/logo.svg",
            },
            items: [
              {
                type: "doc",
                docId: "intro",
                position: "left",
                label: "阅读",
              },
              
              { to: "/blog", label: "Blog", position: "left" },
              {
                href: "https://github.com/facebook/docusaurus",
                label: "GitHub",
                position: "right",
              },
            ],
          },
          footer: {
            style: "dark",
            links: [
              {
                title: "Docs",
                items: [
                  {
                    label: "Tutorial",
                    to: "/docs/intro",
                  },
                  
                ],
              },
              {
                title: "Community",
                items: [
                  {
                    label: "Stack Overflow",
                    href: "https://stackoverflow.com/questions/tagged/docusaurus",
                  },
                  {
                    label: "Discord",
                    href: "https://discordapp.com/invite/docusaurus",
                  },
                  {
                    label: "Twitter",
                    href: "https://twitter.com/docusaurus",
                  },
                ],
              },
              {
                title: "More",
                items: [
                  {
                    label: "Blog",
                    to: "/blog",
                  },
                  {
                    label: "GitHub",
                    href: "https://github.com/facebook/docusaurus",
                  },
                ],
              },
            ],
            copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
          },
          prism: {
            theme: lightCodeTheme,
            darkTheme: darkCodeTheme,
          },
        }),
    };
    
    module.exports = config;
    
    复制代码

### 特别注意 ###

因为code hike使用的是mdx2，在此版本有一个破坏性更新，如果遇到以下问题

![format_png 2][]

请找到``，将其删除

## 开始自己的demo ##

将docs下的一个md文件，改为如下的数据

![format_png 3][]

`为啥不在掘金贴代码块呢，因为跟掘金的markdown冲突了。。。`

你得到了如下的效果

![format_png 4][]

![format_png 5][]

这就是一个简单的如我开头展示的效果。

## 代码标记 ##

这里主要有两个点需要注意 ： 第一个是

---
    复制代码

三条横线，作为每段展示文档的分割，所以你可以看到我们的每一段都有这个标记

![format_png 6][]

第二个是 focus

![format_png 7][]

这个标记表明了你有哪些代码需要高亮，在demo中使用的是行高亮。一共有两种用法：

你可以写在文件开头，例如\`\`\`js statement.js focus=6:8，这表示将从文件的开头进行计算，第6-8行 你也可以写在文件内，例如

// focus(1,1)
        const result=[]
    复制代码

这表示，从标记位置开始的后面的1-1行，也就是第一行

除了这种按照行进行标记，你也可以标记列，例如

// focus[7:12]
          result = 40000;
    复制代码

它表示从下一行的第7-12个字符。 效果为

![format_png 8][]

## 最后享受你的代码，并且关注，点赞，收藏转发吧 ##

[build-your-own-react]: https://link.juejin.cn?target=https%3A%2F%2Fpomb.us%2Fbuild-your-own-react%2F
[codehike.org]: https://link.juejin.cn?target=https%3A%2F%2Fcodehike.org%2F
[format_png]: https://img-blog.csdnimg.cn/img_convert/52f47c083b6f9be16bcb2cac25c5c1db.webp?x-oss-process=image/format,png
[format_png 1]: https://img-blog.csdnimg.cn/img_convert/83cf2b93d45819ca0221324f9d3ce9a5.webp?x-oss-process=image/format,png
[format_png 2]: https://img-blog.csdnimg.cn/img_convert/b5246c0b760df237b917821701b3eb60.webp?x-oss-process=image/format,png
[format_png 3]: https://img-blog.csdnimg.cn/img_convert/a3b41d2c3d97d0e8d5aa070506d4ca73.webp?x-oss-process=image/format,png
[format_png 4]: https://img-blog.csdnimg.cn/img_convert/d5d0f366ca28de78948e3aff1e94d430.webp?x-oss-process=image/format,png
[format_png 5]: https://img-blog.csdnimg.cn/img_convert/6271aba258ff26b0368e2928410e5d3b.webp?x-oss-process=image/format,png
[format_png 6]: https://img-blog.csdnimg.cn/img_convert/b02981b18c183d135dc3dca24fd3c2e6.webp?x-oss-process=image/format,png
[format_png 7]: https://img-blog.csdnimg.cn/img_convert/1223285e440de31d4e434ff40b30a3a9.webp?x-oss-process=image/format,png
[format_png 8]: https://img-blog.csdnimg.cn/img_convert/81fc04148fe8b1fc8285c79b4c7e6a63.webp?x-oss-process=image/format,png