몇 달 동안 준비해온 끝에, 드디어 새로운 웹사이트 템플릿인 Protocol을 출시하게 되어 기쁩니다. 이는 멋진 API 참조 웹사이트를 구축하기 위한 아름다운 스타터 키트입니다.
Next.js와 MDX로 구동되며 Tailwind CSS로 스타일링된 이 템플릿은, 우리가 직접 API 참조 문서를 구축하는 방식 그대로 만들어졌습니다.
라이브 데모를 체험해 보거나, Tailwind UI 올액세스 라이선스를 보유하고 있다면 소스 코드를 다운로드할 수 있습니다. 올액세스 고객에게는 무료 업데이트로 제공됩니다.
디자인 디테일로 가득한 사이트
평소처럼 우리는 디자인에 푹 빠져서 사이트를 탐색하는 즐거움을 더하기 위해 추가적인 꾸밈을 더했습니다.
엔드포인트의 요청과 응답 세부 정보를 스크롤할 때 화면에 고정되는 스틱키 고정 코드 블록을 구현했습니다:
또한 홈페이지 카드에 마우스 커서를 따라가는 아름다운 호버 효과가 있습니다. 그라데이션 빛이 배경 패턴을 드러내는 효과입니다:
하지만 제가 가장 좋아하는 디테일은 사이드바 네비게이션입니다. 이 네비게이션은 "미니맵" 전략을 사용하여 현재 보이는 페이지 내용을 추적하며, 모든 보이는 페이지 섹션을 강조합니다:
페이지를 스크롤할 때 이 애니메이션을 보는 것은 정말 감동적입니다. 여기서는 Framer Motion이 큰 역할을 했습니다. React를 정말 싫어하더라도 이 라이브러리를 사용하기 위해 React를 쓸 정도로 정말 훌륭합니다.
우리가 원하는 개발자 경험
이번에는 실제 콘텐츠를 어떻게 구성할지 결정하는 데 많은 시간을 들였습니다. 다양한 표준을 사용해 문서를 자동 생성하는 여러 옵션을 탐색했지만, 개인적으로는 모든 것이 약간 제한적으로 느껴졌습니다.
개인적으로는 원하는 문서를 정확히 작성할 수 있기를 원합니다. 그래서 Protocol에서는 최대한의 제어력을 유지하면서도 원하는 내용을 빠르고 쉽게 작성할 수 있는 다양한 편의 기능을 제공하도록 최적화했습니다.
여러분은 엔드포인트 문서를 MDX로 작성하며, 빠르게 구조를 잡을 수 있도록 제공된 몇 가지 작은 컴포넌트를 혼합하여 사용할 수 있습니다:
## Create a message {{ tag: 'POST', label: '/v1/messages' }}<Row> <Col> 특정 대화에 새로운 메시지를 게시합니다. ### 필수 속성 <Properties> <Property name="conversation_id" type="string"> Unique identifier for the conversation the message belongs to. </Property> <Property name="message" type="string"> The message content. </Property> </Properties> </Col> <Col sticky> <CodeGroup title="Request" 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: 'Response' }} { "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>이렇게 하면 추가 데이터를 전달하기 위해 원시 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 레퍼런스를 구동하기 위해 Protocol 템플릿을 사용한 것처럼 적응한 이 스크린샷을 확인해보세요:
첫눈에 보기에는 많이 달라 보이지만, 실제로는 버튼과 링크 색상, 로고, 일러스트레이션의 그라데이션 조정, 그리고 구문 강조 색상을 선택하는 것 외에는 크게 변경된 것이 없습니다.
다크 모드
당연히 이 사이트는 다크 모드를 지원합니다. 개발자를 위한 사이트인데, 우리가 그렇게 무지할 거라고 생각하셨나요? 여러분은 절대 우리를 용서하지 않을 겁니다.
다크 모드 버전도 멋진 디자인 요소가 많습니다. 예를 들어, 기본 버튼의 처리 방식이 달라서 마음에 듭니다.
Algolia DocSearch 통합 커맨드 팔레트
우리는 문서 검색을 위해 Algolia를 좋아하며, Tailwind CSS 웹사이트와 Syntax 템플릿에서도 사용하고 있습니다.
이번에는 Protocol에도 Algolia를 적용했는데, 이번에는 Algolia의 헤드리스 autocomplete 라이브러리를 사용하여 검색 UI를 완전히 제어할 수 있도록 했습니다:
이 방식의 장점은 이미 스타일이 적용된 위젯을 커스텀 CSS로 스타일링하는 대신, 일반적인 유틸리티 클래스를 사용하여 모든 것을 스타일링할 수 있다는 점입니다. 이는 Tailwind CSS 프로젝트에서 훨씬 더 자연스럽게 느껴집니다.
그리고 이것으로 2022년을 마무리하는 마지막 Tailwind UI 템플릿이 완성되었습니다! 또 다른 템플릿도 거의 준비가 되었으니, 새해에 주목해 주세요. 곧 Tailwind CSS v4.0에 대한 매우 흥미로운 소식도 공유할 예정입니다!