Announcement, Technology, Tutorials, for Developer, for User, Tool support, News

Klaytn docs 2.0 출시 : 문서 간소화, 검색기능 지원, 커뮤니티 기여 강화

#Blockchain #Klaytn #Technology

Klaytn docs가 강력한 새 문서 플랫폼 위에 간소화된 모습으로 다시 찾아왔습니다!

Klaytn의 공식 문더 플랫폼이 대대적으로 업그레이드되어 Klaytn Docs 2.0으로 출시되었습니다. 이번 버전에서는 검색 기능이 강화되었고, 정보 탐색이 용이해 졌으며, 커스터마이징 기능이 크게 개선되었습니다. 이제, 진화한 Klaytn docs 2.0을 길잡이 삼아 Klatyn 블록체인을 더욱 쉽게 익히고, 구축하고, 운용할 수 있게 되었습니다.

Docusaurus로의 이전 이유

Klaytn docs사이트는 출시 후 줄곧 Gitbook을 통해 호스팅되었고, 이는 초기 단계에 큰 도움이 되었습니다. 하지만 커뮤니티가 성장하고 문서 기여가 활발해지면서 검색, 버전 관리, 언어 전환 및 커스터마이징에 있어 여러 제약이 발생했습니다. 이에, 사용자와 기여자 모두에게 원활한 환경을 제공하기 위해 Docusaurus로 문서 플랫폼을 이전하게 되었습니다. Docusaurus는 아래와 같은 기능을 갖추고 있습니다. 

  • 다국어 지원
    같은 페이지에서 손쉽게 언어를 전환할 수 있습니다.
  • 향상된 검색
    Algolia 기반 검색으로 정보를 쉽게 찾을 수 있습니다.
  • 확장 유연성
    방대한 플러그인 생태계를 활용하여 필요에 맞게 사이트의 기능을 확장할 수 있습니다.
  • 커스터마이징 가능한 레이아웃
    사용자 친화적이고 직관적인 인터페이스를 구성할 수 있습니다.

명확성과 탐색 편의성을 위한 콘텐츠 재구성

플랫폼 마이그레이션과 더불어, 콘텐츠를 더 쉽게 탐색할 수 있도록 목차(TOC)도 재구성했습니다.

  • 네개의 Pillar
    Organize your learning journey with “Learn,” “Build,” “Nodes,” and “References” categories for intuitive navigation.
  1. 학습 – 클레이튼을 이해하기 위한 기본 개념입니다.
  2. 빌드 – 클레이튼에서 빌드하기 위한 튜토리얼과 가이드입니다.
  3. 노드 – 클레이튼 노드 운영과 관련된 문서입니다.
  4. 참조 – API 및 SDK 참조 및 자세한 기술 설명입니다.
  • 복잡성 감소
    하위 카테고리를 줄이고 정보를 다루기 쉬운 수준으로 간소화하였습니다.
  • 탐색 친화적 콘텐츠
    관련 리소스에 더 빠르게 액세스할 수 있도록 주제별, 연관성별로 콘텐츠를 다시 묶었습니다.

콘텐츠 기여자를 위한 변화

Klaytn Docs 2.0은 여전히 오프소스이며, 콘텐츠 기여자의 기여를 소중히 생각하고 있습니다. 앞으로도 Klaytn Docs는 콘텐츠 기여자의 헌신을 기반으로 유지될 것이며, 새로운 설정으로의 원활한 전환을 위해 아래와 같은 사항을 참고하세요.

콘텐츠의 변화

  • 마크다운 파일 위치
    각 콘텐츠의 위치가 바뀌었습니다. 파일 매핑 테이블을 참고하여 기존 콘텐츠가 어디로 옮겨졌고, 어느 위치에서 기여를 이어갈지 확인해 보세요.
  • 이미지 파일 위치
    이미지들 일관성과 관리의 용이성을 위해 한 곳에 모았습니다. (이미지 디렉터리 위치)
    • 변경 전: 이미지는 상대 경로를 사용하며 콘텐츠 파일과 함께 흩어져 있었습니다.
    • 변경 후: 이미지는 절대 경로를 사용하며 /static/img/ 디렉터리 아래 통합되어 카테고리별로 저장됩니다.
  • Github 리포지토리
    • 변경 전
      • 문서 저장소: klaytn-docs, klaytn-docs-vn, klaytn-docs-ko
      • 현지화 브랜치:klaytn-docs > l10n
    • 변경 후
      • 문서 리포지토리:  klaytn-docs (klaytn-docs-vn및 klaytn-docs-ko 는 더 이상 사용되지 않고 보관되었습니다.)
      • 현지화 브랜치: klaytn-docs > l10n_main
  • Crowdin을 통한 번역 기여
    번역자로서 Klaytn-docs 현지화 프로젝트에 계속 기여할 수 있습니다.

플랫폼의 변화 (Gitbook vs Docusaurus)

  • 프로젝트 구조
    Gitbook과 비교하여 Docusaurus가 디렉토리와 파일을 구성하는 방식을 이해하세요.
  • Gitbook
klaytn-docs
├── docs # 콘텐츠 파일
│    ├── dapp
│    ├── getting-started
│    ├── klaytn2
│    ├── misc
│    ├── …
│    ├── SUMMARY.md # 좌측 콘텐츠 내비게이션
│    └── README.md # Klaytn docs 랜딩 페이지
├── …
└── README.md # “This website is built using Gitbook”
  • Docusaurus
klaytn-docs
├── docs  # 영문 콘텐츠 파일
│    ├── build
│    ├── learn
│    ├── misc
│    ├── nodes
│    └── references
├── i18n  # 현지화된 콘텐츠 파일
│    ├── ko # 한국어
│    └── vi # 베트남어
├── docusaurus.config.js # 주요 구성 파일
├── sidebars.js # 좌측 콘텐츠 내비게이션
├── package.json # 필요한 패키지 정보
├── …
└── README.md # “This website is built using Docusaurus”
  • 다국어 관리
    두 플랫폼은 다국어를 관리하는 방식이 다릅니다.
    • Gitbook
      각 언어별로 별도의 리포지토리 또는 프로젝트가 필요합니다. (예: klaytn-docs, klaytn-docs-ko, klaytn-docs-vn)
    • Docusaurus
      단일 리포지토리(예: klaytn-docs)를 사용하며 언어는 하위 폴더에 존재하는 통합된 접근 방식을 취합니다.
  • 내비게이션 파일
    콘텐츠의 구조와 주제를 간략하게 설명하는 왼쪽 탐색 메뉴를 구성하는 파일이 다릅니다.
    • Gitbook: SUMMARY.md
    • Docusaurus: sidebars.js
  • README.md 사용 여부
    • Gitbook: 각 카테고리에는 시작점 역할을 하는 README.md가 있습니다.(예: /deployment/service-chain/README.md)
    • Docusaurus: 같은 역할을 파일명이 “README.md” 가 아닌 “상위 폴더명.md”입니다. (예: /nodes/service-chain/service-chain.md)
  • 마크다운 문법 변경 사항
    문법은 대체로 동일하지만 mdx 문법과 관련된 몇 가지 차이점이 있습니다. 그 중 몇 가지 중요한 사항은 다음과 같습니다:
  1. 첫 번째 레벨 제목
    모든 페이지에 첫 번째 수준의 제목을 넣어야 합니다. Gitbook에서는 SUMMARY.md에 정의된 경우 첫 번째 수준 제목을 건너뛸 수 있지만, Docusaurus에서는 적절한 문서화를 위해 모든 페이지에 첫 번째 수준의 제목이 있어야 합니다.

▪️ 잘못된 예

엔드포인트 노드는 JSON-RPC API를 노출합니다. 다음과 같이 API를 활성화/비활성화할 수 있습니다. 자세한 API 사양은 [JSON-RPC APIs](../../../dapp/json-rpc/README.md)를 참고하세요. 


## API 활성화하기 <a id="enabling-apis"></a>

▪️ 올바른 예

# JSON-RPC API


엔드포인트 노드는 JSON-RPC API를 노출합니다. API는 다음과 같이 활성화/비활성화할 수 있습니다. 자세한 API 사양은 [JSON-RPC APIs](../../references/json-rpc/json-rpc.md)를 참고하세요.


## API 활성화하기 <a id="enabling-apis"></a>

2. 섹션 ID
이전처럼 첫 번째 수준 제목에 섹션 ID를 수동으로 추가하면 사이드바의 각 제목에 섹션 ID까지 같이 표시됩니다.

▪️ 잘못된 예

# 시스템 요구 사항 <a id="system-requirements"></a>


## H/W 사양 <a id="h-w-specification"></a>

▪️ 올바른 예

# 시스템 요구 사항


## H/W 사양 <a id="h-w-specification"></a>

3. 기타 문법 관련 사항
일부 기존 Gitbook 문법은 더 이상 지원되지 않습니다.

a. 콜아웃 (NOTE, CAUTION, WARNING, TIPS)
: 해당되는 경우 Gitbook의 힌트 대신 Docusaurus의 콜아웃 문법을 사용하세요.

b. 표의 줄 바꿈
: 표에 줄 바꿈을 넣을 때는 <br> 또는 </br> 대신 <br/>을 사용합니다.

▪️ 잘못된 예

| 유형 | 설명 | 설명
| --- | --- |
| QUANTITY | 네트워크 식별자의 정수입니다.<br>- `"1001"`: Klaytn Baobab testnet.<br>- `"8217"`: Klaytn Cypress mainnet..|

▪️ 올바른 예

| 유형 | 설명 | 설명
| --- | --- |
| QUANTITY | 네트워크 식별자의 정수입니다.<br/>- `"1001"`: Klaytn Baobab testnet.<br/>- `"8217"`: Klaytn Cypress mainnet..|.|

c. { 또는 <의 잘못된 사용
: Klaytn Docs 2.0은 Docusaurus v3와 MDX v3를 사용하여 빌드되었기 때문에, 마크다운 파일에 {나 <를 잘못 사용하면 빌드 과정에서 컴파일 문제가 발생할 수 있습니다(MDX v3가 더 엄격하게 컴파일하기 때문). 일반적으로 “{“ 문자는 JavaScript 표현식을 여는 데 사용되고 “<” 문자는 JSX 태그를 여는 데 사용되는데 MDX에서 { } 또는 <> 안에 있는 표현식이 유효하지 않다고 판단하면 컴파일 오류가 발생합니다.

이러한 종류의 문제를 해결하는 방법 중 하나는 이스케이프 백슬래시(\)를 앞에 붙여 해당 문자를 이스케이프 처리하는 것입니다.

  • 잘못된 예
| \[\]{\*big.Int, \*big.Int, \*big.Int\} \(Go\) |
  • 올바른 예
| \[\]\{\*big.Int, \*big.Int, \*big.Int\} \(Go\) |
  • 잘못된 예
| Array<String\|Object\>\|Object|
  • 올바른 예
| Array\<String\|Object\>\|Object|

Klaytn docs 2.0은 클레이튼에 더 쉽게 접근하게 하고 사용자 친화적으로 만들고자 하는 노력의 일환입니다. 이를 통해 커뮤니티가 클레이튼 블록체인을 더욱 쉽게 탐구하고, 구축하고, 혁신하는데 중요한 역할을 할 것이라고 생각됩니다. 

더 원활한 학습과 커뮤니티 참여를 위해, 지금 Klaytn docs 2.0을 시작하세요!

*FAQ

Q: 이전 문서 사이트는 어디로 갔나요?
A: GitBook에 호스팅된 이전 문서 콘텐츠는 계속 사용할 수 있으며 다음 URL에 보관되어 있습니다.

– 영어: https://archive-docs.klaytn.foundation/
– 한국어: https://archive-ko.docs.klaytn.foundation/
– 베트남어: https://archive-vn.docs.klaytn.foundation/ 

또한 모든 이전 URL을 새 사이트로 리디렉션했기 때문에 기존 링크도 깨지지 않습니다.

Q: 이전에 다른 디렉토리에 있던 콘텐츠는 어디에서 찾을 수 있나요?
A: 이전 콘텐츠가 Docusaurus 구조에서 어디로 이동되었는지 보여주는 상세한 매핑 테이블을 만들었습니다.

Q: 이미지와 미디어 파일은 어떻게 처리하나요?
A: 이제 이미지는 일괄적으로 /static 폴더 아래 들어가야 합니다. 가령 마크다운 파일에서 /static/img/build/my-image.png와 같은 식으로 경로가 지정되며 다른 미디어도 여기에 넣을 수 있습니다. 과거의 이미지 위치와 새로운 이미지 위치를 알아보려면 이 표를 참조하세요.

Q: Docusaurus로 전환하는 동안 다운타임이 발생하나요?
A: 최대한 원활하게 전환할 수 있도록 노력하고 있지만 혹 다운타임이 예상되는 경우 공식 채널을 통해 미리 알려드리겠습니다.

관련 아티클

목록으로