如何在Backstage中创建无需关联组件的独立文档？

可以实现无需关联组件、显示在侧边栏Documentation且能在首页引用的独立文档，以下是具体方案：

方案1：创建Markdown类型实体 #

无需注册组件，直接通过定义Markdown类型的catalog实体来实现独立文档：

• 在你的文档仓库根目录创建catalog-info.yaml，配置内容如下：

  apiVersion: backstage.io/v1alpha1
  kind: Markdown
  metadata:
    name: standalone-docs-example
    title: "独立文档示例"
    description: "不关联任何组件的独立文档"
    annotations:
      backstage.io/techdocs-ref: dir:. # 指向当前目录下的docs文件夹（存放你的md文档）
  spec:
    type: documentation
  

• 将该仓库添加到Backstage的catalog配置中，完成加载后，该文档会自动出现在侧边栏的Documentation菜单下。

方案2：配置静态文档入口 #

如果不想通过catalog实体管理，可直接修改app-config.yaml配置静态文档：

• 在techdocs节点下添加staticDocs配置：

  techdocs:
    builder: 'local'
    generator:
      runIn: 'docker'
    publisher:
      type: 'local'
    staticDocs:
      - title: "全局静态文档"
        path: "/static/docs/global-guides" # 指向Backstage静态资源目录下的文档路径
        url: "/docs/global-guides"
  

• 先用techdocs-cli generate生成静态文档，再将产物放到指定的静态目录，启动Backstage后就能在侧边栏Documentation看到该文档入口。

在首页引用文档 #

要在Backstage首页添加该文档的入口，可修改首页组件：

• 示例React代码（在HomePage组件中）：

  import { Link } from '@backstage/core-components';
  import { Card } from '@material-ui/core';
  
  // 插入到首页的合适位置
  <Link to="/docs/default/standalone-docs-example">
    <Card style={{ padding: '1rem', margin: '1rem' }}>
      <h3>独立文档示例</h3>
      <p>查看无需关联组件的独立文档内容</p>
    </Card>
  </Link>
  

• 若使用的是Markdown实体，也可直接用EntityCard组件引用：

  import { EntityCard } from '@backstage/plugin-catalog';
  
  <EntityCard entityRef="markdown:standalone-docs-example" />
  

官方的standalone documentation方案确实依赖组件关联，但上述两种方法均可完全脱离组件创建独立文档，满足你的需求。

内容的提问来源于stack exchange，提问作者Felipe