Backstage) Install 4. TechDocs 에서 PlantUML Plugin 사용하기

https://backstage.io/docs/features/techdocs/

TechDocs Documentation | Backstage Software Catalog and Developer Platform

 

TechDocs는 Spotify가 자체 개발한 문서형 코드 솔루션으로, Backstage에 내장되어 있습니다. 엔지니어는 마크다운 파일로 문서를 작성하고, 이 파일은 코드와 함께 저장되며, 간단한 설정만으로 Backstage에서 보기 좋은 문서 사이트를 만들 수 있습니다.

이 TechDocs를 사용하는데 있어서 다음과 같은 규칙을 따라야 Backstage는 인식하고 표시합니다.

 

아래는 Component에서 해당 document를 reference 할 때 입니다.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: microservice-a
  description: description
  annotations:
    backstage.io/techdocs-ref: dir:../   ## 만약 해당 Catalog가 위치한 Repository에 document가 있는 경우
spec:
  type: service
...

 

 

만약 document가 원격 repository에 있는 경우 다음의 syntax로 대체할 수 있습니다.

    backstage.io/techdocs-ref: url:<https://~~~(path for the mkdocs)>

 

참조 소스코드
https://github.com/armyost/backstage-sample/tree/main

GitHub - armyost/backstage-sample

 

 

그리고 document의 file tree는 다음을 따라야 합니다.

├── catalogs
│   ├── sample-component.yaml
├── docs
│   ├── index.md
├── mkdocs.yml

 

여기서 mkdocs는 navigation과 전반적인 document overlay를 담당합니다.

site_name: Backstage Sample
site_description: Example MkDocs site for backstage-sample
site_author: Your Name
repo_url: https://github.com/your/repo

nav:
  - Home: index.md
  - Getting Started: getting-started.md
  - Reference:
      - Overview: reference.md

plugins:
  - search
  - techdocs-core

이때 사용할 플러그인을 정의합니다. 저의 경우에는 PlantUML  Code를 바로 Rendering 하기 위하여 techdocs-core 플러그인을 추가하였습니다.

 

이렇게 techdocs-core 플러그인을 통해 아래와 같이 바로 PlantUML Code를 rendering 할수 있습니다.

실제 MarkDown file은 다음과 같습니다.

 

```plantuml 이라는 footer를 통하여 이 Markdown은 PlantUML 코드를 인지합니다.

## This is index

```plantuml
@startuml
title User signup sequence
actor User
participant "Frontend" as FE
participant "Backend API" as API
database "Users DB" as DB

User -> FE: Open signup page
FE -> API: POST /signup {name,email,password}
API -> DB: INSERT user
DB --> API: 201 Created
API --> FE: 201 Created
FE --> User: Show welcome page
@enduml

@startuml
title Simple domain class diagram
class User {
  +id: UUID
  +name: String
  +email: String
  +register(): void
...
@enduml
```

 

결과는 다음과 같이 바로 MarkDown에서 Rendering하는 것입니다.