Protocol: API 문서화 사이트를 위한 아름다운 시작점
- Date
Adam Wathan
몇 달 동안 준비해온 끝에, 우리의 다음 웹사이트 템플릿인 Protocol을 드디어 출시하게 되어 기쁩니다. Protocol은 멋진 API 참조 웹사이트를 구축하기 위한 아름다운 스타터 키트입니다.
Next.js와 MDX로 구동되며 Tailwind CSS로 스타일링된 이 템플릿은 우리가 직접 API 참조 문서를 구축하는 방식 그대로 만들어졌습니다.
라이브 데모를 통해 직접 체험해보거나, Tailwind UI 올액세스 라이선스를 보유하고 있다면 소스 코드를 다운로드할 수 있습니다. 올액세스 고객에게는 무료 업데이트로 제공됩니다.
디자인 디테일로 가득한 페이지
평소처럼 디자인에 몰두하며 사이트를 탐색하는 즐거움을 더하기 위해 추가적인 디테일을 더했습니다.
엔드포인트의 요청과 응답 세부 정보를 스크롤할 때 화면에 고정되는 스틱키 고정 코드 블록을 구현했습니다:
홈페이지 카드에 적용된 아름다운 호버 효과도 있습니다. 마우스 커서를 따라 움직이는 그라데이션 빛이 미묘한 배경 패턴을 드러냅니다:
하지만 가장 마음에 드는 디테일은 사이드바 네비게이션입니다. 페이지 콘텐츠를 추적하면서 “미니맵” 전략을 사용해 모든 보이는 페이지 섹션을 강조합니다:
페이지를 스크롤할 때 이 애니메이션을 보는 것은 정말 감동적입니다. Framer Motion이 여기서 중요한 역할을 해주었습니다. React를 정말 싫어하더라도 이 라이브러리를 사용하기 위해 React를 쓸 정도로 훌륭합니다.
우리가 원하는 개발자 경험
이번에는 실제 콘텐츠를 어떻게 구성할지 결정하는 데 많은 시간을 들였습니다. 다양한 표준을 사용해 문서를 자동 생성하는 여러 옵션을 탐색했지만, 제 개인적인 취향으로는 다소 제한적이라고 느꼈습니다.
개인적으로는 정확히 원하는 문서를 작성할 수 있기를 바랍니다. 그래서 Protocol에서는 최대한의 제어권을 확보하면서도, 원하는 내용을 빠르고 쉽게 작성할 수 있는 다양한 편의 기능을 제공하도록 최적화했습니다.
여러분은 MDX로 엔드포인트 문서를 작성하며, 빠르게 구조를 잡을 수 있도록 제공된 몇 가지 작은 컴포넌트를 활용할 수 있습니다:
## 메시지 생성 {{ tag: 'POST', label: '/v1/messages' }}
<Row>
<Col>
특정 대화에 새로운 메시지를 게시합니다.
### 필수 속성
<Properties>
<Property name="conversation_id" type="string">
메시지가 속한 대화의 고유 식별자입니다.
</Property>
<Property name="message" type="string">
메시지 내용입니다.
</Property>
</Properties>
</Col>
<Col sticky>
<CodeGroup title="요청" tag="POST" label="/v1/messages">
```bash {{ title: 'cURL' }}
curl https://api.protocol.chat/v1/messages \
-H "Authorization: Bearer {token}" \
-d conversation_id="xgQQXg3hrtjh7AvZ" \
-d message="You're what the French call 'les incompetents.'"
```
```js
import ApiClient from '@example/protocol-api'
const client = new ApiClient(token)
await client.messages.create({
conversation_id: 'xgQQXg3hrtjh7AvZ',
message: 'You're what the French call 'les incompetents.'',
})
```
</CodeGroup>
```json {{ title: '응답' }}
{
"id": "gWqY86BMFRiH5o11",
"conversation_id": "xgQQXg3hrtjh7AvZ",
"message": "You're what the French call 'les incompetents.'",
"reactions": [],
"created_at": 692233200,
}
```
</Col>
</Row>이렇게 작성된 문서는 다음과 같이 생성됩니다:
작성 경험을 더욱 완벽하게 만들기 위해, mdx-annotations라는 새로운 라이브러리도 개발했습니다. 이 라이브러리는 Markdoc 작업 시 좋아했던 주석 기능을 MDX로 가져옵니다.
이 기능을 사용하면 MDX 콘텐츠에서 객체를 통해 태그에 props를 전달할 수 있습니다. 예를 들어 다음과 같은 제목이 있다면:
## 메시지 생성 {{ tag: 'POST', label: '/v1/messages' }}이것은 다음과 같은 JSX로 변환됩니다:
<Heading level={2} tag="POST" label="/v1/messages">메시지 생성</Heading>이를 통해 추가 데이터를 전달하기 위해 raw JSX로 전환할 필요 없이 마크다운을 계속 작성할 수 있어 작업 속도를 크게 높일 수 있습니다.
적응형 디자인
이 템플릿은 많은 사람들에게 바로 사용할 수 있을 만큼 유용할 것이라고 생각합니다. 그래서 여러분의 브랜드에 맞게 디자인을 쉽게 커스텀할 수 있도록 만드는 것이 중요했습니다.
사이트에서 사용한 일러스트레이션 배경 패턴은 의도적으로 누구에게나 “브랜드에 맞는” 느낌을 주도록 디자인했습니다. 전문 디자이너의 작품이라는 느낌을 주면서도 단순하고 “기술적” 모티프를 강조했습니다. 이는 모든 API 레퍼런스 사이트가 공통적으로 가지고 있는 특징이기도 합니다.
이 패턴은 모든 색상이 고정된 에셋으로 내보내는 대신 코드로 구현했습니다. 그래서 여러분의 색상 체계에 맞게 쉽게 조정할 수 있습니다.
구문 강조를 위해 Shiki를 사용하고 있으며, css-variables 테마를 적용했습니다. 이 테마는 단 9가지 색상을 선택하여 구문 강조를 브랜드에 맞게 업데이트할 수 있게 해줍니다.
:root {
--shiki-color-text: theme('colors.white');
--shiki-token-constant: theme('colors.emerald.300');
--shiki-token-string: theme('colors.emerald.300');
--shiki-token-comment: theme('colors.zinc.500');
--shiki-token-keyword: theme('colors.sky.300');
--shiki-token-parameter: theme('colors.pink.300');
--shiki-token-function: theme('colors.violet.300');
--shiki-token-string-expression: theme('colors.emerald.300');
--shiki-token-punctuation: theme('colors.zinc.200');
}이 방법은 처음부터 테마를 직접 만드는 것보다 훨씬 적은 작업량으로 원하는 결과를 얻을 수 있습니다.
데모에서 사용한 4개의 아이콘 외에도, 일반적인 API 리소스 타입을 위한 24개의 추가 아이콘을 포함했습니다.
ConvertKit에서 이 템플릿을 사용하여 API 레퍼런스를 만든 것처럼 적용한 스크린샷을 확인해보세요.
첫눈에 보기에는 많이 달라 보이지만, 자세히 살펴보면 실제로 변경된 부분은 많지 않습니다. 버튼과 링크 색상, 로고, 일러스트레이션의 그라데이션 조정, 그리고 구문 강조 색상을 선택한 정도입니다.
다크 모드
당연히 이 사이트는 다크 모드를 지원합니다. 개발자를 위한 사이트인데, 우리가 그렇게 무지할 거라고 생각하셨나요? 여러분이 절대 용서하지 않을 거라는 걸 잘 알고 있습니다.
다크 모드 버전도 독특한 디자인 요소가 많습니다. 예를 들어, 기본 버튼의 스타일이 달라진 점이 특히 마음에 듭니다.
Algolia DocSearch가 통합된 커맨드 팔레트
우리는 문서 검색을 위해 Algolia를 좋아하며, Tailwind CSS 웹사이트와 Syntax 템플릿에서도 사용하고 있습니다.
이번에는 Protocol에도 Algolia를 적용했는데, Algolia의 헤드리스 autocomplete 라이브러리를 사용해 검색 UI를 완전히 제어할 수 있도록 했습니다:
이 방식의 장점은 이미 스타일이 적용된 위젯을 커스텀 CSS로 스타일링하는 대신, 일반적인 유틸리티 클래스를 사용해 모든 것을 스타일링할 수 있다는 점입니다. 이는 Tailwind CSS 프로젝트에서 훨씬 더 자연스럽게 느껴집니다.
그리고 이것으로 2022년을 마무리하는 마지막 Tailwind UI 템플릿이 완성되었습니다! 또 다른 템플릿도 거의 준비가 되었으니, 새해에 주목해 주세요. 곧 Tailwind CSS v4.0에 대한 매우 흥미로운 소식도 공유할 예정입니다!