Penn' blog

Penn Wang


# TL;DR

- mdast（markdown 语法树） 中保存了 markdown node position（位置信息），起始行，结束行。
- remark-rehype 在将 mdast 转化为 hast（html 语法树）的过程中丢失了 position。
- 自定义 handler 配置给 remark-rehype，寻回 position。
- 枯燥的同步 scroll 逻辑。

# 引子

前阵时间在 junjin 看了篇文章 [markdown 编辑器实现双屏同步滚动](https://juejin.cn/post/7129743753023062052), 意识到自己造的很多轮子，都缺少这个关键的体验。非常惭愧，于是计划赶紧加上。但是研究了文章作者的代码，发现并不容易。当然，不容易的部分并不在于滚动本身，而在于滚动之前`确定关联关系` - 即确定 markdown 和 html 之间的对应关系。严格来说，就是哪一行 markdown 对应哪一行 html。

本文重点记录“确定关联关系”的探索过程。

我使用的技术栈是 remark + react，关键的 npm package：

- remark-parse: markdown 转 mdast，mdast 是 markdown 语法树
- remark-rehype： mdast 转 hast，hast 是 html 语法树
- rehype-react： hast 转 react

# mdast 的 position 信息

刚开始，我写了个小脚本，将一段 markdown 转化为 mdast，分析了它的结构，意外的发现 mdast 里保存了 position 信息。

test.ts

```javascript
import { unified } from 'unified';
import remarkParse from 'remark-parse';

const processor = unified().use(remarkParse);

const markdown = `
![calm](https://images.unsplash.com/photo-1691264122434-3b5a1dac81d5?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=1856&q=80)
`;

console.log(processor.parse(markdown));
```

```bash
$ npx ts-node --esm test.ts
{
  type: 'root',
  children: [ { type: 'paragraph', children: [Array], position: [Object] } ],
  position: {
    start: { line: 1, column: 1, offset: 0 },
    end: { line: 3, column: 1, offset: 177 }
  }
}
```

如上，position 里保存了每个 mdast 原始的行（开始，结束）。如果这个信息能够 expose 到 react 组件，我们的问题不就解决一大半了吗？

那么，问题来了，到底是哪一步丢掉了 position 信息呢？
我们上面列举了关键的三个 package，remarkjs 这里，生成 position。那么，问题在下游的两个 package 喽。

按顺序先读 remark-rehype 的源码。remark-rehype 几乎是个空壳子，逻辑都在 mdast-util-to-hast，它的主要任务就是根据 mdast 的类型，用不同的 handler，将 mdast node 转化为 hast。这是 image handler 的代码：

```javascript
export function image(state, node) {
  /** @type {Properties} */
  const properties = { src: normalizeUri(node.url) };

  if (node.alt !== null && node.alt !== undefined) {
    properties.alt = node.alt;
  }

  if (node.title !== null && node.title !== undefined) {
    properties.title = node.title;
  }

  /** @type {Element} */
  const result = { type: 'element', tagName: 'img', properties, children: [] };
  state.patch(node, result);
  return state.applyData(node, result);
}
```

如上，它采集了 title，alt，src 等属性，然后组装 hast。的确没有收集 position。
如果加上 position 呢？remark-rehype 支持自定义 handler，我们改一下 image handler 试试：

```javascript
function gatherPosition(node) {
  return {
    [`data-startline`]: node.position.start.line,
    [`data-startcolumn`]: node.position.start.column,
    [`data-startoffset`]: node.position.start.offset,
    [`data-endline`]: node.position.end.line,
    [`data-endcolumn`]: node.position.end.column,
    [`data-endoffset`]: node.position.end.offset,
  };
}
export function image(state, node) {
  /** @type {Properties} */
  const properties = { src: normalizeUri(node.url) };

  if (node.alt !== null && node.alt !== undefined) {
    properties.alt = node.alt;
  }

  if (node.title !== null && node.title !== undefined) {
    properties.title = node.title;
  }

  /** @type {Element} */
  const result = {
    type: 'element',
    tagName: 'img',
    properties: { ...gatherPosition(node), ...properties },
    children: [],
  };
  state.patch(node, result);
  return state.applyData(node, result);
}
```

rehype-react 这里也要改一下对应的 image 组件，把 position 放在 html prop 里（直接 rest 了，哈哈）：

```javascript
function Img({ src, alt, ...rest }: { src: string, alt: string }) {
  return <img src={src} alt={alt} {...rest} />;
}
```

成功了，image html 里完美的保留了 position 信息：
![position properties of markdown image](/markdown-editor-scroll-image-position-value.png)

图片不够清楚的话：

```html
<img
  src="https://images.unsplash.com/photo-1691264122434-3b5a1dac81d5?ixlib=rb-4.0.3&amp;ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&amp;auto=format&amp;fit=crop&amp;w=1856&amp;q=80"
  alt="calm"
  data-startline="55"
  data-startcolumn="1"
  data-startoffset="2668"
  data-endline="55"
  data-endcolumn="176"
  data-endoffset="2843"
/>
```

实验成功，接下来就是简单的体力活

1. 自定义所有的 handler，保留 position，然后配置给 remark-rehype。我的办法是直接复制了 mdast-util-to-hash 的 handlers，放在自己代码库下。
2. 自定义 rehype-react 所有 tag 对应的组件，将 position 存放在 html 属性上。

# 滚动部分的逻辑

解决了 position 的保存问题，剩下来的就是如何监测 A 滚动，同步滚动 B。分为两部分：

1. 编辑器滚动时，同步滚动预览；
2. 预览滚动时，同步滚动编辑器。

为了保证滚动的即时性，也为了避免使用 state 保存状态引起的回环依赖（滚动编辑器 to 滚动预览界面），滚动逻辑统统做到一个 effect 里。 逻辑比较直观，所以直接上代码：

注：编辑器底层用了 [codemirror](https://codemirror.net)。部分代码和 html 层级有关系，最好参考完整代码和实际渲染结果阅读，详见 [wxformat](https://github.com/wangpin34/wxformat/blob/main/src/App.tsx)，部署在 [https://wangpin34.github.io/wxformat/](https://wangpin34.github.io/wxformat/)

```javascript
 useEffect(() => {
    let isScrollEditorScrolling = false
    let isScrollPreviewerScrolling = false

    const editorContainer = document.querySelector('#editor-container')
    const previewContainer = document.querySelector('#preview-container')

    const scrollPreviewerByLine = (lineNumber: number, totalLines: number) => {
      console.debug(`scroll preview to line[${lineNumber}], totalLines: ${totalLines}`)
      if (previewContainer) {
        if (lineNumber === 1) {
          previewContainer.scrollTop = 0
          return
        }
        if (lineNumber >= totalLines) {
          previewContainer.scrollTop = previewContainer.scrollHeight
          return
        }

        let desiredScrollTop = -1
        const children = previewContainer.querySelectorAll('.preview > [data-startline]')
        for (const child of children) {
          const start = child.getAttribute('data-startline')
          const end = child.getAttribute('data-endline')

          if (start && end) {
            const startNum = parseInt(start)
            const endNum = parseInt(end)

            if (startNum <= lineNumber && endNum >= lineNumber) {
              let percent = 0
              if (startNum !== endNum) {
                percent = (lineNumber - startNum) / (endNum - startNum)
              }
              const styles = getComputedStyle(child)
              const height = parseFloat(styles.height)
              //@ts-ignore
              desiredScrollTop = child.offsetTop + percent * height
              break
            }
          }
        }
        if (desiredScrollTop < 0) {
          return
        }
        previewContainer.scrollTop = desiredScrollTop
      }
    }

    const editorScrollListener = (e: Event) => {
      if (isScrollPreviewerScrolling) {
        isScrollPreviewerScrolling = false
        return
      }
      isScrollEditorScrolling = true
      const node = e.target as HTMLDivElement
      const { top: pTop, bottom: pBottom } = node.getBoundingClientRect()
      const lines = node.querySelectorAll('.cm-line')
      const last = lines[lines.length - 1]
      const { top, bottom } = last.getBoundingClientRect()
      if (top >= pTop && bottom <= pBottom) {
        scrollPreviewerByLine(lines.length, lines.length)
        return
      }
      for (let i = 0; i < lines.length; i++) {
        const line = lines[i]
        const { top, bottom } = line.getBoundingClientRect()

        if (top >= pTop && bottom <= pBottom) {
          scrollPreviewerByLine(i + 1, lines.length)
          break
        }
      }
    }

    const previewScrollListener = (e: Event) => {
      if (isScrollEditorScrolling) {
        isScrollEditorScrolling = false
        return
      }
      isScrollPreviewerScrolling = true

      const node = e.target as HTMLDivElement
      const scrollTop = node.scrollTop
      if (scrollTop === 0) {
        return
      }
      if (scrollTop + node.clientHeight >= node.scrollHeight) {
        return
      }
      const children = node.querySelectorAll('.preview > [data-startline]')
      for (const child of children) {
        //@ts-ignore
        if (scrollTop >= child.offsetTop && scrollTop <= child.offsetTop + child.clientHeight) {
          //@ts-ignore
          const percent = (scrollTop - child.offsetTop) / child.clientHeight
          const startLine = parseInt(child.getAttribute('data-startline') as string)
          const endLine = parseInt(child.getAttribute('data-endline') as string)
          let targetLine = startLine
          if (startLine !== endLine) {
            targetLine = startLine + Math.ceil((endLine - startLine) * percent)
          }

          if (editorContainer && targetLine > 0) {
            const lines = Array.from(editorContainer.querySelectorAll('.cm-line'))
            const line = lines[targetLine - 1]

            //@ts-ignore
            editorContainer.scrollTop = line.offsetTop
          }

          break
        }
      }
    }

    if (editorContainer && previewContainer) {
      editorContainer!.addEventListener('scroll', editorScrollListener, false)
      previewContainer!.addEventListener('scroll', previewScrollListener, false)
      return () => {
        editorContainer!.removeEventListener('scroll', editorScrollListener)
        previewContainer!.removeEventListener('scroll', previewScrollListener)
      }
    }
  }, [])
```

简单概括下：

1. editor 端，根据滚动行数，在预览界面遍历，找到 position 符合的 dom，scroll 到 dom 位置。
2. 预览界面端，查找第一个在屏幕的 dom，拿到 position 里的 start line，end line，结合滚动的百分比，计算出一个合理的 line number，滚动 editor 到此行。

这里的逻辑应该还有优化空间，比如对 editor 同步滚动时一行的具体百分比。有空再做哈。

# 相关资料

- [wxformat 代码仓库](https://github.com/wangpin34/wxformat)


没有双屏同步滚动的 markdown 编辑器是没有灵魂的。

如何为基于 remarkjs 的 markdown 编辑器添加同步滚动


# 问题

我负责的一个 NextJS 文档项目最近发现了诡异的问题：文档中引用的图片已替换成新图，但是用户浏览器始终无法看到新图。debug 一番，找到直接原因：Nginx 将图片的缓存时间设置为 1 年，对应的 HTTP 响应头为

```
Cache Control: max-age=36540000
```

所以，缓存未失效前，浏览器只从本地提取缓存，不去服务器下载新图片。所以用户只能看到老图片。解决的办法是主动的作废用户端缓存。

# `content hash` 与 `invalide cache`？

`content hash` 指的是对文件内容计算得到一个独一无二 `hash` 值。不同的图片自然有不同的 hash。因此，当图片的内容被修改，hash 会变化。在 webpack，rollup 等打包工具中，常利用 hash 值来组织资源文件名。比如，原图片为 `NextJS.png`，`hash` 为 `abcd`，最终文件名是 `NextJS.abcd.png`（此文件名会替换引用此图片的 js，css，以便程序正常）。
当文件内容变更，hash 也会变化。比如 hash 为 `efgh`，那么资源文件名就从 `NextJS.abcd.png` 变化为 `NextJS.efgh.png` 。

`content hash` 能够保证新图片得到一个新名字，`html` 引用新图片，用户看到新图片，相当于作废（invalidate）老图片。

所以我们接下来会引入 `content hash` 来完善 `cache` 策略。

# static import image

我搜索了官方文档，只在 [image minimumcachettl](https://NextJS.org/docs/pages/api-reference/components/image#minimumcachettl) 搜到与 hash 有关的线索。

> You can configure the Time to Live (TTL) in seconds for cached optimized images. In many cases, it's better to use a Static Image Import which will automatically hash the file contents and cache the image forever with a Cache-Control header of immutable.
> 所谓 static import image，即：

```javascript
import ImageSrc from './NextJS.png';
```

MDX 中的确可以这么做：

```markdown
import imageSrc from './NextJS.png';

# Any title

<ImageSrc src={imageSrc} />
```

但我更喜欢的方式是 markdown image 的写法：

```markdown
# Any title

![alt](/NextJS.png)
```

# CustomComponent，限制，规则，以及疑问

> 坦白来说，当 `NextJS` 的表述是 `static import image` 才可能有 `content hash`，我就应该放弃了。因为无论如何，我也无法将 `markdown image` 写法转化为 `static import`（正则匹配，自动生成 `import` 代码，然后再用 `NextJS` 处理，应该能成，但不是我喜欢的方式）。

我尝试了下面这个办法，然后“居然”成功了。思路是，用 `require` 或者 `dynamic import` 来获得 `imgsrc`，然后用 `next/image` 渲染 image。

具体做法：

pages/posts/[slug].js

```javascript
function CustomImage({ src, alt, ...rest }) {
  const imgSrc = useMemo(() => require(`../../public${src}`), [src]);
  return (
    <Image
      {...rest}
      src={imgSrc}
      alt={alt ?? src.subsring(src.lastIndexOf('/') + 1, src.lastIndexOf('.'))}
    />
  );
}
```

posts/test-post.MDX

```markdown
---
title: test post
description: show image that will be rendered with content hash in path
date: Jan 2 2021
---

This is an example post.

![ladybug](/pexels-pixabay-36485.jpg)
```

图片存放在 `public/pexels-pixabay-36485.jpg`。（尝试过存放在 posts 目录，但是 build 失败，也许我该提个 issue 问问 NextJS team？）

请打开浏览器调试工具查看下面图片的路径，图片原名 `pexels-pixabay-36485.jpg` 。
![ladybug](/pexels-pixabay-36485.jpg)

# Conclusion

为 MDX 或者 markdown 中的图片生成 hash 文件名需要具备的条件：

1. 自定义 MDX 的 image component，使用 require image 并且用 next/image 渲染图片。
2. 图片存放在 public 目录，MDX 中使用绝对路径（相对于 public 目录）引用图片。（我也许会花点时间搞清楚这个限制的根本原因，更理想的存放 image 的地方绝对不是 public）

其他限制：

1. next-remote-watch 启动项目，会报 `Unhandled Runtime Error
TypeError: _jsx is not a function` 错误。
2. 目前只在 next-mdx-remote 方案中验证成功。已知无法在成功的有 remark processor。

ps: NextJS 根据资源的引用方式配置不同的 Cache 策略，1 年，或者 no cache，所以，我暂时移除 Nginx 中配置的 Cache 规则，避免无谓的覆盖。


MDX 中引用的图片变动时，应该自动的更新图片路径，从而使得用户端缓存失效。如何利用 NextJS 的内置特性实现这个功能呢？

如何为 MDX 中引用的图片生成 hash 文件名


This is an example post. There's another one [here](/posts/example-post).

![ladybug](/pexels-pixabay-36485.jpg)


Consider that for a moment: everything we see around us is assumed to have had a cause and is contingent upon.

Penn' blog

如何为基于 remarkjs 的 markdown 编辑器添加同步滚动

如何为 MDX 中引用的图片生成 hash 文件名

Design critiques at Figma