Feishu Docx

Feishu Docx is an implementation that supports converting Feishu Docx document formats to any other format.

This is an independent NPM library that you can freely import and use in your own front-end projects. The feishu-pages tool internally uses feishu-docx to achieve content conversion. This document only introduces the formatting details of the exported feishu-docx document.

Currently supported formats:

• Markdown (GFM)

Installation

💡

If you use feishu-pages, you can skip the installation and usage section. The feishu-pages has already been integrated internally.

yarn add feishu-docx

Usage

import { MarkdownRenderer } from 'feishu-docx'

// Load docx JSON from file
const docx = fs.readFileSync('test.json')
const render = new MarkdownRenderer(docx)
const text = render.parse();
const imageTokens = render.imageTokens;

Feishu Block Type

See: Supported Formats

Markdown GFM

The vast majority of content document output will be in the format of Markdown GFM output, basically compatible performance of 99% restore.

Special HTML

You may see that the final Markdown output is actually mixed with some HTML code. This is due to some special document formats of Feishu (such as Callout), which require us to add some custom HTML + self-implemented CSS in Markdown to achieve the corresponding layout effect.

Don't worry, the vast majority of Markdown tools support Markdown and HTML mixed formatting. If the tool you are currently using cannot support it, please check their HTML switch.

Because the outside is HTML, so the all contents inside that is also output as HTML, otherwise Markdown cannot recognize it correctly.

Image

Originally, Markdown supported images, but in Feishu Docs we have more detailed details such as resizing, image alignment, etc.

As the current Feishu API does not provide the adjusted image scaling size, we cannot restore the adjusted size in Feishu Docs. It is recommended to set the image width to 100% in the document to use. This issue has been returned to the Feishu API team and needs to wait for them to improve.

The Markdown code for exporting images may look like this:

<img src="M9hDb8WXzo7TU5xg4xtcvArPnxe" src-width="410" src-height="404" align="center"/>

• Src-width and src-height - the width and height of the original image
• Align - is the alignment of the document within the original document, [left, center, right]

Callout

Callout is used on Feishu Docs to identify some key content.

For example, this style:

🐸

This block is a Callout with green color.

The HTML generated after exporting is:

<div class="callout callout-bg-3 callout-border-3">
🐸 This block is a Callout with green color.
</div>

Wherein callout-bg-3 and callout-border-3 respectively represent the background color and border color, 3 is green, the number range is 1-17, respectively represent different colors.

Color correspondence table, see Feishu Docs: CalloutBackgroundColor , CalloutBorderColor

It is recommended to refer to CSS (note that Tailwind CSS is used here):

.callout {
  padding: 0.5em 1em;
  margin: 1.5em 0;
  border: 2px solid #ccc;
  border-radius: 5px;
  font-size: 1em;

  &-bg-1,
  &-bg-8 {
    @apply bg-red-50 dark:bg-red-950;
  }
  &-bg-2,
  &-bg-9 {
    @apply bg-orange-50 dark:bg-orange-950;
  }
  &-bg-3,
  &-bg-10 {
    @apply bg-yellow-50 dark:bg-yellow-950;
  }
  &-bg-4,
  &-bg-11 {
    @apply bg-green-50 dark:bg-green-950;
  }
  &-bg-5,
  &-bg-12 {
    @apply bg-blue-50 dark:bg-blue-950;
  }
  &-bg-6,
  &-bg-13 {
    @apply bg-purple-50 dark:bg-purple-950;
  }
  &-bg-7,
  &-bg-14 {
    @apply bg-gray-50 dark:bg-gray-950;
  }

  &-border-1,
  &-border-8 {
    @apply border-red-200 dark:border-red-800;
  }
  &-border-2,
  &-border-9 {
    @apply border-orange-200 dark:border-orange-800;
  }
  &-border-3,
  &-border-10 {
    @apply border-yellow-200 dark:border-yellow-800;
  }
  &-border-4,
  &-border-11 {
    @apply border-green-200 dark:border-green-800;
  }
  &-border-5,
  &-border-12 {
    @apply border-blue-200 dark:border-blue-800;
  }
  &-border-6,
  &-border-13 {
    @apply border-purple-200 dark:border-purple-800;
  }
  &-border-7,
  &-border-14 {
    @apply border-gray-200 dark:border-gray-800;
  }

  @apply text-gray-800 dark:text-gray-200;
}

Grid

Grid is used in Feishu Docs to achieve vertical column layout, which we cannot restore with Markdown. However, it is quite commonly used in actual document writing. For example, we may use Grid to arrange three images in a row.

The HTML generated by the above structure looks like this:

<div class="grid gap-3 grid-cols-3">
<div>
<img src="Bwk8bcQH6oLQn1xjzdacPBckn8d" src-width="1000" src-height="500" align="center"/>
</div>
<div>
<img src="DkwibdF3ooVi0KxttdocdoQ5nPh" src-width="400" src-height="354" align="center"/>
</div>
<div>
<img src="M9hDb8WXzo7TU5xg4xtcvArPnxe" src-width="410" src-height="404" align="center"/>
</div>
</div>

Iframe

The embedded web pages in Feishu will be output using Ifream HTML tags.

For example:

<iframe src="https://www.bilibili.com/video/BV1L94y1t7Yb/"/>

License

MIT