1. 웅덩이 파는 데 포크레인 써보기 2. Design System 흉내를 위해 Figma 힐끗 보기 3. React 기초 훑어보고 Docusaurus 설치하기
5. Docusaurus config 톺아보기 (2) 6. Swizzle로 디자인 커스터마이징하기 7. Github Pages로 Docusaurus 웹사이트 호스팅하기 8. 구글 서치 콘솔 등록하고 사용자 인사이트 얻기
docusaurus.config.js에 추가할 수 있는 설정들
자주 쓰이는 필수 설정들은 설치 직후에 config 파일을 열어보면 이미 설정되어 있는 것을 확인할 수 있다. 그 외에도 내가 원하는 설정을 커스터마이징하거나 Docusaurus에서 제공하는 플러그인 같은 부가 기능을 추가할 때 config 파일을 편집하게 된다.
사이트 메타데이터
SEO에 대해 알아본 적이 있다면 웹사이트 메타데이터를 정확히 설정해야 한다는 것을 들어봤을 것이다. 사이트 제목, 설명, 주요 키워드 등 검색 확률을 높이는 데 도움이 되는 정보를 config에 설정할 수 있다. 여기서 설정된 정보는 build할 때 Docusaurus가 알아서 적절한 포맷의 메타데이터로 변환해준다.
배포 설정
배포 때 사용하는 설정값을 config에 추가할 수 있다. 특히 Github pages로 호스팅을 한다면 config 파일 편집이 필수적이다.
플러그인
Docusaurus에서는 몇 가지 고급 기능을 플러그인 형태로 제공하고 있다. Google Analytics 설정도 여기에 포함되는 데, 꼭 통계 데이터가 필요하지 않더라도 나중에 구글 검색 노출을 위한 사이트 등록을 진행할 때 Google Analytics 플러그인을 사용하면 더 편리해지는 측면이 있다.
디자인 설정
사이트에 어떤 내용을 담을지, 어떤 레이아웃으로 내용을 표시할지를 설정할 수 있다. 구체적인 디자인 커스터마이징은 CSS나 별도의 프론트 프로그래밍으로 진행해야 하지만, GNB에 표시될 메뉴 등 주요 골격에 대한 내용은 config에서 설정하게 된다.
사이트 메타데이터 설정하기
/** @type {import('@docusaurus/types').Config} */
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
favicon: 'img/favicon.ico',
// Set the production url of your site here
url: 'https://your-docusaurus-test-site.com',
// Set the /<baseUrl>/ pathname under which your site is served
// For GitHub pages deployment, it is often '/<projectName>/'
baseUrl: '/',
// GitHub pages deployment config.
// If you aren't using GitHub pages, you don't need these.
organizationName: 'facebook', // Usually your GitHub org/user name.
projectName: 'docusaurus', // Usually your repo name.
onBrokenLinks: 'throw',
onBrokenMarkdownLinks: 'warn',
// Even if you don't use internalization, you can use this field to set useful
// metadata like html lang. For example, if your site is Chinese, you may want
// to replace "en" with "zh-Hans".
i18n: {
defaultLocale: 'en',
locales: ['en'],
},
...(중략)...
Docusaurus를 설치하고 나서 config 파일을 열어보면 위와 같은 기본값을 볼 수 있다.
favicon
const config = {
favicon : 'img/favicon.ico'
... (중략) ...
}
파비콘은 브라우저 주소창에서 웹사이트 주소 옆에 볼 수 있는 작은 아이콘을 말한다. static/img 폴더 안에 Docusaurus 로고 모양의 파비콘 이미지가 기본값으로 들어가있다. 내가 만든 이미지를 같은 경로에 같은 파일명으로 만들어서 덮어씌우면 간편하게 파비콘을 바꿀 수 있다. 이 때 일반적인 이미지 포맷인 png, jpg 등을 ico 포맷으로 바꾸려면 인터넷에서 쉽게 찾아볼 수 있는 포맷 변환 사이트를 활용하면 된다.
title, tagline
const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
... (중략) ...
}
사이트 제목과 설명 문구를 설정하는 곳이다. Docusaurus에서 기본값으로 제공하는 index 페이지를 편집없이 사용한다면 여기 설정한 title과 tagline이 화면 상단에 표시된다.
검색 노출 알고리즘이 사이트의 내용을 파악하는 데 참고하는 정보이기도 하다. Notion 처럼 웹사이트 메타데이터를 불러와서 링크를 만들어주는 기능에서는 사이트 제목과 함께 노출되는 서브 타이틀의 역할을 한다.
social card
조금 위에 노션 북마크 기능처럼 웹사이트 주소를 링크걸 때 메타데이터를 읽어들여서 같이 보여주는 경우가 있다. 이 때 사이트를 대표하는 썸네일 이미지가 같이 보여질 때가 있는데 해당 이미지를 social card라 한다. social card 이미지는 config 파일 스크롤을 조금 내리다보면 있는 themeConfig에서 설정할 수 있다.
... (중략) ...
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
// Replace with your project's social card
image: 'img/docusaurus-social-card.jpg',
... (중략) ...
})
마찬가지로 Docusaurus에서 만든 샘플 social card가 이미 포함되어 있기 때문에 같은 경로에 같은 파일명으로 덮어쓰면 쉽게 교체할 수 있다.
keywords
내 사이트에서 다루는 주요 내용을 keywords로 지정해두면 검색 노출에 도움이 된다. 사이트 전체적으로 적용되는 global keyword를 설정할 수도 있고, 각 콘텐츠별로 keyword를 따로 설정하는 것도 가능하다. global keywords는 config 파일에 추가해서 지정할 수 있다. 설치 직후의 config 파일 기본 내용에는 포함되어 있지 않기 때문에, 관련 가이드를 참고해서 직접 작성해야 한다. 나는 다음과 같이 keywords를 설정했다.
... (중략) ...
themeConfig:
/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
({
metadata: [{
name: 'keywords', content: '노션, 생산성, 블로그, 코딩 공부, 여행'
}],
... (중략) ...
})
배포 환경 설정하기
배포 환경 설정은 Github pages 기준으로 설정했다. 여기서는 어떻게 설정했는지만 간략히 포함하고, Github pages 사용법을 다룰 다른 포스트에서 더 자세히 설명할 예정이다.
url, baseUrl
url은 사이트 도메인을 뜻한다. 호스팅사에서 제공하는 무료 도메인을 쓴다면 해당 주소, 혹은 내가 구입한 유료 도메인 주소를 적으면 된다. Github pages를 쓴다면 github.io로 끝나는 주소가 도메인이므로 해당 주소를 적어야 한다. baseUrl은 사이트의 기본 경로값에 해당하는 위치가 어디인지를 지정하는 곳이다. 도메인 url 구조를 특별히 다르게 지정하는 경우가 아니라면 기본값인 '/'를 그대로 두면 된다. 그래서 내 config는 아래와 같이 설정되어 있다.
const config = {
url : 'https://winter-blanket.github.io/',
baseUrl : '/',
... (중략) ...
}
organizationName, projectName
Github pages를 쓰는 경우에만 설정하는 정보기 때문에 다른 호스팅사를 사용한다면 편집 없이 넘어가면 된다. organizationName은 Github에서 사용하는 organization 이름을 뜻하는데 개인이라면 자기 user name을 작성하면 된다. projectName은 repository 이름인데 Github pages는 repository 이름과 도메인이 같으므로 도메인 주소를 https:// 없이 적어주면 된다.
const config = {
... (중략) ...
// GitHub pages deployment config.
// If you aren't using GitHub pages, you don't need these.
organizationName: 'winter-blanket', // Usually your GitHub org/user name.
projectName: 'winter-blanket.github.io', // Usually your repo name.
... (중략) ...
}
플러그인 추가하기
plugin-google-gtag
gtag 플러그인은 Google Analytics를 쉽게 붙일 수 있게 도와주는 플러그인이다. 플러그인 목록을 보면 plugin-google-analytics도 있는데, 이는 구버전 Google Analytics 연동을 위한 플러그인이므로 무시하고 gtag 플러그인만 설치하면 된다. 플러그인 설치 전에 아래 명령어를 프로젝트 폴더 경로에서 실행해서 플러그인을 내려받아야 한다.
npm install --save @docusaurus/plugin-google-gtag
그리고 config를 아래와 같이 설정한다. themeConfig 하위 위치가 아니라 config 바로 아래 위치에 넣어야 한다. tracingID에는 Google Analytics에서 사이트를 등록하면서 생성한 아이디값을 적으면 된다.
const config = {
... (중략) ...
plugins: [
[
'@docusaurus/plugin-google-gtag',
{
trackingID: 'G-XXXXXXXXXX',
anonymizeIP: true,
},
],
],
... (중략) ...
}
Google Analytics 사이트에서 trackingID를 만드는 방법은 이 포스트에서 설명합니다.
사이트 내용 설정하기
사이트 언어(i18n)
Docusaurus에서 제공하는 유용한 부가 기능 중 하나가 다국어 설정을 지원한다는 점이다. 특히 사용자 가이드 용도로 사용한다면 글로벌 서비스인 경우 가이드 문서를 여러 언어별로 제공해야 할 때가 있다. Docusaurus에서는 화면 상단의 토글 버튼으로 간편하게 언어별 버전을 오고갈 수 있다. 내 사이트에서는 여러 언어를 쓸 일이 없으므로 검색 노출 최적화 차원에서 사용 언어를 지정해주는 정도로만 설정했다. 다국어 설정에 대한 보다 자세한 내용은 가이드 페이지에서 확인할 수 있다.
const config = {
... (중략) ...
i18n: {
defaultLocale: 'ko',
locales: ['ko'],
},
... (중략) ...
}
블로그 메타데이터
const config = {
... (중략) ...
presets: [
[
'classic',
/** @type {import('@docusaurus/preset-classic').Options} */
({
blog: {
blogTitle : '겨울이불의 아카이브',
blogDescription : '개인적인 공부 기록과 기억해둘만한 모든 정보를 모아두는 곳입니다.',
blogSidebarTitle: '최근 글 모음',
blogSidebarCount: 0,
postsPerPage : 'ALL',
showReadingTime: true,
sortPosts : 'descending',
// Please change this to your repo.
// Remove this to remove the "edit this page" links.
// editUrl:'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
},
... (중략) ...
}),
],
],
}
blog 기능을 사용하는 경우, 블로그 관련 메타데이터와 부가 기능을 따로 설정해줄 수 있다. blog 관련 설정은 presets 필드 안에 추가할 수 있는데, 설정할 수 있는 모든 옵션의 종류는 가이드 페이지에서 확인할 수 있다.
blogTitle, blogDescription
사이트 title, tagline과 같이 블로그의 내용을 설명하는 메타 데이터를 따로 설정하고 싶은 경우에 사용하는 값이다.
blogSidebarTitle
Docusaurus의 blog 기본 레이아웃은 화면 왼편에 포스트 목록이 쭉 나열되는 식이다. 사이드바 제목을 직접 설정할 수 있다.
blogSidebarCount
사이드바에 최대 몇 개의 포스트 제목을 노출시킬지를 지정하는 곳이다. 아라비아 숫자를 적거나 ALL 이라고 적을 수 있다. 포스트 개수가 아주 많을 경우 ALL을 쓰면 스크롤이 지나치게 길어지므로 적당한 숫자로 최대 개수를 제한시켜주는 것이 좋을 것이다. 나는 이런저런 커스터마이징 끝에 사이드바 자체를 노출시키지 않기로 해서 개수를 0으로 지정했다.
postsPerPage
블로그 화면에 진입했을 때 최대 몇 개의 포스트를 보여줄지를 지정하는 곳이다. pagination을 적용 하지 않을 거라면 ALL을 쓰면 되고, 특정 아라비아 숫자를 적으면 pagination이 적용된다.
showReadingTime
true로 켜두면 포스트 작성일 옆에 예상 완독 시간이 자동 계산되어 표시된다.
sortPosts
descending으로 설정하면 최근 작성 포스트가 위에, 옛날 포스트가 아래에 배치된다. 반대로 배치하고 싶다면 ascending이라고 적으면 된다.
editUrl
블로그 포스트 편집을 서버에 띄워져 있는 Docusaurus 웹페이지에서 바로 시작한다면 이 곳에 포스트를 편집하는 url을 지정하면 된다. 예를 들어, Docusaurus 샘플 사이트를 localhost에 띄워보면 포스트 상세 페이지 하단에 edit this page 버튼이 활성화되어 있는 것을 볼 수 있다. 여길 누르면 해당 포스트의 마크다운 파일이 있는 Github 링크로 이동한다. repository 주인이라면 여기서 마크다운 파일을 바로 편집할 수 있을 테고, 곧 블로그 포스트가 수정된다.
나는 모든 내용을 항상 로컬에서 프로그래밍 에디터로 편집할 생각이었기 때문에 이 옵션은 주석처리해두었다. 실제로 자주 쓰일 설정은 아닌지, config 기본 파일에 이미 삭제하라는 안내 주석이 포함되어 있다.
이어서
여기까지 진행했다면 이제 사이트에 어떤 내용을 담을지를 채워나갈 차례다. 다음 포스트에서는 GNB에 어떤 메뉴를 배치할지 부터 시작해서 레이아웃에 영향을 미치는 설정을 config 파일에 채우는 법을 다룰 예정이다.
1. 웅덩이 파는 데 포크레인 써보기 2. Design System 흉내를 위해 Figma 힐끗 보기 3. React 기초 훑어보고 Docusaurus 설치하기
5. Docusaurus config 톺아보기 (2) 6. Swizzle로 디자인 커스터마이징하기 7. Github Pages로 Docusaurus 웹사이트 호스팅하기 8. 구글 서치 콘솔 등록하고 사용자 인사이트 얻기