AnyBlock Docusaurus Demo

该项目基于 Docusaurus V3.9.2

并以 pnpm + typescript 为例 (你也可以使用其他包管理器，以及不使用 typescript)

构建该demo项目

cd DocusaurusDemo
pnpm run start
# 然后查看 http://localhost:3000/docs/intro 页底部的 AnyBlock 块是否正常渲染

从零创建该项目

1. 先搭建 Docusaurus 项目

node -v     # >= v20.0
npm -v
npx -v

pnpm create docusaurus
# 在询问时输入项目名 DocusaurusDemo，和选择使用 typescript

# 你也可以使用你喜欢的包管理器 (npm/yarn/pnpm/bun) 来初始化新项目，详见官方文档，如 npx:
# npx create-docusaurus@latest DocusaurusDemo classic --typescript # --typescript 选项可选
# Ok to proceed? (y) y

cd DocusaurusDemo
# pnpm run start # (可选) 可测试一下                                                  

2. 添加示例内容 (方便查看是否成功)

echo -e "\n[list2table]\n\n- 1\n- 2\n  - 3\n  - 4\n" >> ./docs/intro.md

3. 安装使用 AnyBlock 的 Remark 插件

就像使用普通的 remark 插件那样使用

3.1. 安装依赖

pnpm install @anyblock/remark-any-block
# 后续如果编译时发现有依赖丢失再补充 npm install
将该项目的 `src/remark/` 文件夹内容复制到你项目中的相同位置

3.2. 启用插件

docusaurus.config.ts

import remark_anyblock_to_codeblock from './src/remark/anyblock2'; // [!code ++]
import remark_anyblock_render_codeblock from './src/remark/anyblock'; // [!code ++]

const config: Config = {
  presets: [
    [
      'classic',
      {
        docs: {
          remarkPlugins: [ // [!code ++]
            remark_anyblock_to_codeblock,
            remark_anyblock_render_codeblock,
          ],
        },
      } satisfies Preset.Options,
    ],
  ],
}
export default config;

3.3. 启用样式文件

src/css/custom.css 添加:

@import '../../node_modules/@anyblock/remark-any-block/styles';

/* 适配当前框架与 anyblock 样式 */
.ab-note {
  margin: 10px 0;
  table tr {
    border: none;
  }
}

Warning

注意，构建出来的只有对应的dom结构，而没有样式。因为纯markdown-it插件是不含样式的（除非用内联样式），自己引用一下就好

例如vuepress中可以创建/修改 src/.vuepress/styles/index.scss 并添加: @import '../../../node_modules/markdown-it-any-block/styles';

例如vitepress可以添加 theme 文件夹及里面的内容

4. 检查

pnpm run start
# 然后查看 http://localhost:3000/docs/intro 页底部的 AnyBlock 块是否正常渲染
# pnpm run build # 或编译检查