Docusaurus 사이트 만들기 및 사용자 정의(블로그 기능 포함)

경량 웹 사이트, 애플리케이션 및 기타 소규모 프로젝트의 경우 점점 더 많은 개발자가 WordPress 또는 기타 콘텐츠 관리 시스템(CMS)을 통해 정적 사이트 생성기를 사용하고 있습니다. 정적 사이트는 빠르고 안전하며 유지 관리하기 쉬운 웹 사이트 및 응용 프로그램을 만드는 간단하고 효과적인 방법을 제공합니다.

Docusaurus는 그러한 정적 사이트 생성기 중 하나이며 개발 커뮤니티에서 빠르게 인기를 얻고 있습니다. 느린 콘텐츠 관리 시스템에 지치셨습니까? 도큐사우르스를 만나다! 속도를 늦추지 않고 작업을 완료하는 정적 사이트 생성기. 자세히 알아보려면 계속 읽어보세요. 트윗하려면 클릭하세요.

이 게시물에서는 Docusaurs를 정적 사이트 생성기로 사용할 때의 이점과 Docusaurs가 개발자들 사이에서 인기를 얻고 있는 이유에 대해 자세히 살펴보겠습니다.

도쿠사우루스란?

Docusaurus는 페이지 생성을 위한 UI 라이브러리로 최고의 JavaScript 라이브러리 중 하나인 React를 사용하는 인기 있는 정적 사이트 생성기입니다. 다른 생성기와 마찬가지로 설정 및 수정이 쉽고 가장 중요한 것은 정적 웹 사이트를 시작하는 데 필요한 모든 것을 제공한다는 것입니다.

그러나 Docusaurus가 다른 점은 콘텐츠가 중요한 역할을 하는 웹사이트를 만들고 관리하는 데 도움이 된다는 점입니다. 처음부터 콘텐츠를 강조하는 블로그 기능을 갖춘 전체 웹 사이트를 쉽고 빠르게 구축할 수 있습니다.

콘텐츠는 Docusaurus의 초점이기 때문에 Wiki와 같은 문서 사이트를 만드는 데 적합합니다. 또한 git 리포지토리의 협업 및 저장 모두에 이상적인 마크다운을 활용합니다. 게다가 i18n, 검색, 맞춤 테마와 같은 수많은 놀라운 기능이 있습니다. 이에 대해서는 나중에 자세히 설명하겠습니다.

다음은 Docusaurus를 확실한 옵션으로 만드는 몇 가지 뛰어난 기능입니다.

• React를 사용하여 구축
• MDX v1 지원
• Markdown을 통한 React 구성 요소 임베딩 지원
• 문서 버전 관리
• 문서 번역 및 대량 또는 개별 배포를 위한 Git, Crowdin 및 기타 번역 관리자와의 호환성

누가 도큐사우르스를 사용합니까?

Docusaurus는 Facebook에서 만들었기 때문에 현재 웹을 통해 많은 대형 브랜드와 회사에서 사용되고 있다는 것은 놀라운 일이 아닙니다.

다음은 오늘날 Docusaurus를 사용하는 가장 큰 브랜드 중 일부입니다(Docusaurus의 인기가 계속 증가함에 따라 더 많은 브랜드가 곧 출시될 예정입니다).

• Algolia DocSearch
• 농담
• 네이티브 반응
• 수파베이스

그리고 매일 더 많은 사람들이 그들의 대열에 합류하고 있습니다.

도큐사우르스 설치 방법

Docusaurus는 설치가 매우 간단하며 몇 분밖에 걸리지 않습니다. 이 자습서에서는 블로그가 포함된 설명서 사이트를 구축하고 웹 사이트의 모양을 사용자 지정합니다.

가장 멋진 부분은 다음과 같습니다. 모든 것을 가동하는 데 1시간도 채 걸리지 않습니다.

다이빙하자!

요구 사항

Docusarus에는 Node.js 16.14 이상이 필요합니다. 플랫 파일 SSG이므로 추가 데이터베이스가 필요하지 않습니다.

Node.js 16.14+를 아직 사용할 수 없는 경우 Node.js를 설치하거나 현재 버전을 업그레이드하여 시작해야 합니다. 그런 다음 아래의 도큐사우르스 설치 과정으로 넘어갈 수 있습니다.

또한 이 GitHub 리포지토리의 샘플 Docusaurus 사이트를 사용할 것입니다. 이 자습서에서는 Docusaurus를 사용하거나 새로 설치할 수 있습니다.

설치 과정

Docusaurus 설치 프로세스를 시작하려면 먼저 다음 명령을 실행해야 합니다.

 npx [email protected] classic

이렇게 하면 프로젝트용 폴더가 생성되고 그 안에 클래식 테마가 스캐폴딩됩니다. 클래식 테마에는 이미 블로그, 사용자 정의 페이지 및 CSS 프레임워크와 같은 일부 사전 구성된 기능이 포함되어 있습니다.

설치 후 다음 명령을 실행하여 로컬 서버를 시작해야 합니다.

 npm start

배포할 준비가 된 최적화된 버전을 빌드하려면 대신 다음을 실행해야 합니다.

 npm run build

구조

Docusaurus 인스턴스를 설치하면 프로젝트 디렉토리를 열고 새 사이트의 "골격"을 자세히 살펴볼 수 있습니다.

파일 구조는 다음과 같습니다.

 my-website ├── blog │ ├── 2019-05-28-hola.md │ └── 2020-05-30-welcome.md ├── docs │ ├── doc1.md │ └── mdx.md ├── src │ ├── css │ │ └── custom.css │ └── pages │ ├── styles.module.css │ └── index.js ├── static │ └── img ├── docusaurus.config.js ├── package.json ├── README.md ├── sidebars.js └── yarn.lock

이러한 파일 및 폴더 중 일부와 관련하여 주의해야 할 몇 가지 세부 정보가 있습니다.

• /blog : 블로그와 관련된 모든 파일을 포함합니다.
• /docs : 문서와 관련된 모든 파일을 포함합니다. sidebar.js 파일에서 순서를 사용자 정의할 수 있습니다.
• /src : 페이지 또는 사용자 지정 구성 요소와 같은 모든 비문서 파일을 포함합니다.
• /src/pages : 모든 JSX/TSX/MDX 파일이 페이지로 변환됩니다.
• /static : 최종 빌드 폴더에 복사될 정적 파일.
• docusaurus.config.js : 도큐사우르스 설정 파일.
• packaged.json : 각 Docusaurus 사이트는 React 앱이므로 여기에서 React에 사용하는 모든 종속성 및 스크립트를 찾을 수 있습니다.
• sidebar.js : 여기에서 사이드바의 문서 순서를 지정할 수 있습니다.

Docusaurus 설치 커스터마이징

파일 구조의 단순함에서 알 수 있듯이 Docusaurus는 사용 및 탐색이 쉽습니다. 마찬가지로 Docusaurus 사이트를 사용자 지정하는 것도 쉽습니다. 선호하는 텍스트 편집기 또는 IDE를 사용하여 이러한 파일을 열고 편집할 수 있습니다.

즉시 사용할 수 있는 몇 가지 사용자 지정 옵션을 살펴보겠습니다.

홈페이지

가장 먼저 하고 싶은 일은 자신의 프로젝트를 표시하도록 기본 홈페이지를 사용자 지정하는 것입니다. 다행스럽게도 Docusaurus 홈페이지에서 원하는 대로 변경하는 것은 복잡하지 않습니다.

홈페이지를 변경하려면 src/pages/index.js 파일을 열고 바로 조정하십시오. 일반적인 React 페이지이므로 콘텐츠를 변경하거나 사용자 지정 React 구성 요소를 만들어 변경하거나 다시 빌드할 수 있습니다.

구성 파일

다음으로 중요한 docusaurus.config.js 파일을 살펴보고 인스턴스에 대한 몇 가지 중요한 세부 정보를 변경합니다.

이름 및 설명

구성 파일에서 다음을 찾을 수 있습니다.

 const config = { title: 'My Site', tagline: 'Dinosaurs are cool', url: 'https://your-docusaurus-site.com', baseUrl: '/',

사이트의 요구 사항에 맞게 이러한 세부 정보를 변경한 다음 파일을 저장하기만 하면 됩니다.

탐색 표시줄

탐색 모음을 편집하려면 navbar 항목을 찾습니다.

여기의 예에서는 Kinsta에 대한 링크를 추가하고 "자습서" 항목의 이름을 "시작 문서"로 바꾸고 Kinsta 로고를 추가하려고 합니다.

방법은 다음과 같습니다.

 navbar: { title: 'Kinsta starters', logo: { alt: 'Kinsta Logo', src: 'img/kinsta-logo-alpha-purple.png', }, items: [ { label: 'Kinsta starters', to: '/docs/intro', }, {to: '/blog', label: 'Blog', position: 'left'}, { href: 'https://github.com/kinsta', label: 'GitHub', position: 'right', }, ], },

보행인

Docusaurus의 바닥글 사용자 지정은 바닥글 콘텐츠 자체와 바닥글 링크의 두 섹션으로 구성됩니다.

바닥글 콘텐츠

바닥글 콘텐츠의 주요 부분(링크 목록 제외)은 themeConfig.footer 파일에 배치할 수 있습니다. 로고와 저작권 표시를 추가하기에 이상적인 위치입니다.

바닥글 구성을 수정한 방법은 다음과 같습니다.

 module.exports = { themeConfig: { footer: { logo: { alt: 'Kinsta Logo', src: 'img/kinsta-logo.png', href: 'https://kinsta.com', width: 160, height: 51, }, copyright: `Copyright ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`, }, }, };

바닥글 링크

바닥글 링크를 변경하는 것은 상단 탐색 모음을 변경하는 것과 유사합니다. docusaurus.config.js 에서 footer 섹션을 찾아 필요에 맞을 때까지 편집합니다.

footer 섹션을 다음과 같이 변경했습니다.

 footer: { style: 'dark', links: [ { title: 'Docs', items: [ { label: 'Kinsta starters', to: '/docs/intro', }, ], }, { title: 'Talk with us', items: [ { label: 'Discord', href: 'https://discord.gg/vjRPMhFaBA', }, { label: 'Support', href: 'https://kinsta.com/kinsta-support/', }, { label: 'Twitter', href: 'https://twitter.com/kinsta', }, ], }, { title: 'More', items: [ { label: 'Application Hosting', href: 'https://kinsta.com/application-hosting/', }, { label: 'Database Hosting', href: 'https://kinsta.com/database-hosting/', }, { label: 'WordPress Hosting', href: 'https://kinsta.com/wordpress-hosting/', }, { label: 'DevKinsta', href: 'https://kinsta.com/devkinsta/', }, ], }, ], };

색상 및 CSS

Docusaurus의 클래식 사전 설정은 Infima CSS 프레임워크를 사용합니다. 이를 염두에 두고 Docusaurus 제작자는 색상 및 기타 CSS 요소와 선언을 변경하는 데 도움이 되는 매우 유용한 웹 도구를 만들었습니다.

페이지에 기본 설정을 입력하면 이 도구는 몇 초 만에 멋진 보완 톤 모음으로 완성된 custom.css 파일을 생성합니다. 그런 다음 참조를 위해 이 새 CSS 파일을 프로젝트의 /src/css 디렉토리에 복사할 수 있습니다.

선적 서류 비치

새 웹사이트의 모든 문서는 /docs 폴더에 저장됩니다. 물론 docusaurus.config.js 에서 폴더 이름을 변경할 수 있습니다.

텍스트 또는 HTML 편집기에서 마크다운 파일을 만들고 해당 폴더에 드롭하기만 하면 됩니다. 각 파일은 다음과 같아야 합니다.

 --- id: the-id title: Title --- # Rest of the document

ID를 기반으로 Docusaurus는 해당 하위 폴더( yourdomain.com/docs/{id} 에 있는 기사의 URL을 구축합니다.

설명서를 서로 다른 논리적 섹션으로 나누려는 경우 하위 폴더를 만들 수도 있습니다. 그러나 이러한 하위 디렉터리가 예상대로 작동하려면 약간의 추가 작업이 필요합니다.

"Starters"라는 새 문서 폴더를 만든다고 가정합니다. 그런 다음 홈페이지를 새로 고치고 사이드바에 자동으로 추가된 새 "시작" 링크를 클릭하면 새 폴더에 아직 인덱스 페이지가 없기 때문에 오류가 발생합니다.

이 문제를 해결하는 가장 쉬운 방법은 이 폴더에 저장된 모든 페이지의 색인을 생성하는 _category_.json 파일을 만드는 것입니다. 다음 코드만 추가하면 됩니다.

 { "label": "Starters", "position": 2, "link": { "type": "generated-index", "description": "All Kinsta Starters" }, };

보시다시피 사이드바가 재생성되어 파일 구조와 일치합니다. sidebar.js 파일에 다음 tutorialSidebar 포함되어 있기 때문입니다. [{type: 'autogenerated', dirName: '.'}],

직접 처리하고 싶다면 다음과 같이 변경할 수 있습니다.

 tutorialSidebar: [ 'intro', 'hello', { type: 'category', label: 'Tutorial', items: ['tutorial-basics/create-a-document'], }, ],

블로그

Docusaurus에는 매끄러운 블로그 모듈이 포함되어 있습니다. 기본 웹 사이트 옆에 블로그를 배치하면 프로젝트에서 발생하는 변경 사항을 사용자 기반에 알리거나 변경 로그 형식으로 프로젝트 노트를 계속 실행하는 데 매우 유용할 수 있습니다.

각 게시물은 다음과 같이 앞부분으로 구성됩니다.

 --- slug: docusaurus-starter title: Docusaurus Starter authors: palmiak tags: [starters, docusaurus] ---

… 그리고 물론 콘텐츠 자체도 마찬가지입니다. 또한 모든 게시물 목록에 표시되는 게시물 요약을 제한하는 데 도움이 되는 매우 유용한 <!--truncate--> 태그가 있습니다.

크레딧에 대한 authors.yml 파일을 만드는 것도 좋은 생각입니다. 파일은 다음과 같습니다.

 palmiak: name: Maciek Palmowski title: DevRel url: https://github.com/palmiak image_url: https://github.com/palmiak.png

이 파일 덕분에 쉽게 참조할 수 있도록 저자의 모든 데이터를 한 곳에 보관할 수 있습니다.

Kinsta에서 Docusaurus 웹사이트를 배포하는 방법

WordPress 사이트, 독립 실행형 애플리케이션 및 데이터베이스 위에 Kinsta는 정적 웹사이트를 호스팅할 수 있습니다.

즉, Docusaurs 사이트와 MyKinsta 대시보드에서 직접 모든 웹 프로젝트를 관리하는 데 적합합니다.

애플리케이션이 배포되면 다음과 같은 측정을 통해 애플리케이션의 실시간 및 과거 분석을 지속적으로 검토할 수 있습니다.

• 대역폭 사용량
• 구축 시간
• 실행 시간
• CPU 사용량
• 메모리 사용량

처음부터 끝까지 MyKinsta를 통한 배포 프로세스는 몇 분 밖에 걸리지 않습니다.

시작하자!

전제 조건: Docusaurus 프로젝트 구성

Kinsta의 애플리케이션 호스팅 플랫폼에서 Docusaurus 프로젝트를 호스팅하려면 다음이 필요합니다.

1. package.json 파일에 이름 필드를 포함합니다. (무엇이든 될 수 있으며 배포에 영향을 주지 않습니다.)
2. package.json 파일에 빌드 스크립트를 포함합니다. (당신의 Docusaurus 프로젝트는 이미 이것을 포함하고 있을 것입니다.)
3. serve npm 패키지를 설치하고 빌드를 제공하도록 시작 스크립트를 설정합니다.

확인이 완료되면 사이트를 실제로 배포할 수 있습니다.

Docusaurus 프로젝트 배포

다음의 간단한 단계에 따라 GitHub 계정에 연결하고 Docusaurus 사이트를 시작하세요.

1. MyKinsta 계정에 로그인하고 왼쪽 메뉴에서 애플리케이션 탭으로 이동합니다.
2. 파란색 서비스 추가 버튼을 클릭하고 드롭다운에서 애플리케이션을 선택합니다.

   

3. 아직 MyKinsta를 통해 GitHub 계정에 연결하지 않은 경우 연결을 권장하는 모달이 표시됩니다. 계속하려면 GitHub로 계속 버튼을 클릭합니다.

   

4. Kinsta가 GitHub 리소스에 액세스하고 관리할 수 있는 권한을 요청하는 새 창이 열립니다. 올바른 GitHub 계정에 로그인했는지 확인한 다음 하단 근처에 있는 녹색 Authorize Kinsta 버튼을 클릭합니다.

   

5. 이제 GitHub 통합 마법사에 왔습니다. 사이트를 배포하기 전 마지막 단계입니다. 제공된 필드를 신중하게 고려하고 GitHub 구성 및 프로젝트 요구 사항에 따라 입력하십시오. 리포지토리에 Dockerfile이 있는 경우 이를 사용하여 컨테이너 이미지를 설정할 수 있습니다. 그렇지 않으면 Kinsta가 자동으로 컨테이너 이미지를 설정합니다. 특히 이것이 Kinsta를 통한 첫 번째 배포인 경우 진행하기 전에 GitHub 권한을 편집해야 할 수 있습니다.

   

   모든 리포지토리 또는 특정 리포지토리에만 Kinsta 액세스 권한을 부여할지 여부를 선택할 수 있습니다. 이러한 권한은 GitHub 계정의 애플리케이션 설정에서 언제든지 조정할 수 있습니다.

   

6. 선택을 하고 선택 사항을 확인한 후에는 배포 세부 정보와 설정 변경 또는 재배포 옵션이 표시됩니다.

   

   여기에서 쉽게 해결할 수 있도록 오류의 원인에 대한 세부 정보와 함께 배포 중에 발생한 모든 오류를 볼 수 있습니다. 문제를 해결하는 데 어려움을 겪고 있는 경우 Kinsta 설명서에서 롤아웃 오류에 대한 추가 지침을 찾을 수 있습니다.

   

오류 없이 여기까지 왔다면 축하합니다. Kinsta를 통해 Docusaurus 사이트를 성공적으로 배포했습니다! 응용 프로그램(예: 정적 사이트)은 마법사를 완료하는 즉시 사용할 수 있습니다. 애플리케이션의 URL(일반적으로 https:// your-docusaurus-site .kinsta.app 에서 볼 수 있습니다.

Kinsta의 샘플 사이트에 대한 첫 번째 보기는 다음과 같습니다.

요약

놀라울 정도로 강력한 기능, 친근한 디자인, 직관적인 탐색 및 콘텐츠에 대한 집중을 통해 Docusaurus가 능률적이고 잘 구성된 정적 문서 사이트 및/또는 블로그. 웹 개발 게임을 바꿔보세요! 투박한 CMS에 작별을 고하고 Docusaurus를 만나보세요. 개발 게임을 변화시키는 간단한 정적 사이트 생성기입니다. 바로 여기에서 확인하세요 ️ 트윗하려면 클릭하세요

방문자가 가치 있게 여기는 콘텐츠로 사이트를 채우고 나면 편리한 추가 내장 기능에 주목하기 시작할 것입니다. 예를 들어, Docusaurus의 검색 엔진 최적화 기능은 SEO 순위를 높이기 위한 다른 기술을 연구하는 동안 더 많은 청중을 통해 향상된 가시성을 확보하는 데 완벽합니다.

도쿠사우르스로 무언가를 만들었나요? 아래 의견 섹션에서 프로젝트와 경험을 공유하십시오.