본문 바로가기

테크니컬 라이팅

도큐사우루스에서 지원하는 마크다운 기능 (6)

반응형

도큐사우루스는 기본 마크다운 명세를 지원하며 몇 가지 추가 기능을 사용할 수 있습니다.

 

프런트 매터

문서 URL이라든지 제목, 상세 설명 등의 메타 데이터를 처리하기 위해 YFM(YAML front matter) 형식을 지원합니다.

https://assemble.io/docs/YAML-front-matter.html

사용할 수 있는 전체 필드는 plugin-content-docs 문서에서 참고할 수 있습니다.

https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter

 

필드 중 제목과 관련된 필드는 우선순위에 따라 적용됩니다.

기본적으로 제목은 파일명이 적용되며 그다음에는 마크다운 문서 내 # hello 처럼 작성한 제목이 반영됩니다. 프런트 매터에 아무런 설정이 없다면 이 제목이 문서 제목, 사이드바 제목으로 설정됩니다. 프런트 매터 내 필드에서도 id, title이 기본적으로 적용되고 pagination_label, sidebar_label이 적용됩니다.

 

우선순위를 다시 정리하면 아래와 같습니다(높은 숫자가 덮어쓰는 구조입니다).

1. 파일명

2. 마크다운 내 # 제목

3. id

4. title

5. sidebar_label (사이드바에 표시되는 제목)

6. pagination_label (페이징 영역에 표시되는 제목)

 

링크 및 이미지

링크 동작은 기본 마크다운 문법과 크게 다르지 않습니다. 다만 링크 또는 파일을 지정할 수 있다는 것이 좀 다릅니다.

파일은 상대 경로로 지정하며 연결되는 URL은 파일 확장자로 연결되는 것이 아니라 해당 파일 내 설정에 따라 자동으로 변환되어 처리됩니다.

 

이미지는 static 폴더 내 img 폴더에 있는 파일에 접근할 수 있습니다.

 

 

코드 블록

3개의 억음부호(`)로 감싼 형태로 작성합니다.

문장 내에서 속성이나 클래스명 등을 표기할 때는 억음부호 1개로 감싸서 표현할 수 있습니다. 코드 블록은 코드를 복사하거나 언어에 따라 하이라이트를 처리하는 등의 기능이 추가됩니다.

 

 

준수사항(Admonitions)

문서를 읽다보면 팁이나 위험 뭐 그런 문구를 볼 수 있습니다.

Admonitions은 "경고"로 번역하기도 하는데 팁 같은 경우에는 맞지 않으니 "준수사항"이라는 용어를 사용했습니다.

콜론(:) 3개 다음에 지정된 문자열을 지정합니다.

사용할 수 있는 문자열은 다음과 같습니다. 기능이 따로 있는 건 아니고 색상이나 아이콘 정도가 달라집니다.

:::note
:::tip
:::info
:::caution
:::danger

 

MDX와 리액트 컴포넌트

MDX는 마크다운 확장 기능입니다. 정확한 약자의 의미가 애매한데 markdown extention 이 아닐까 싶네요. 리액트 컴포넌트를 만들고 JSX 구문을 사용해 마크다운 내에서 리액트 컴포넌트를 사용할 수 있습니다. 문서의 규모가 커지고 다양한 기능을 공통으로 지원하기 위해서 필요한 것이죠. 간단한 스타일 정도라면 어렵지 않게 CSS만 알면 할 수 있을 것 같은데 실무에서는 좀 더 다양한 기능을 원할 수 있으니 관련 개발자가 참여하거나 잘 만들어진 공개된 컴포넌트를 활용하는 것이 좋을 듯합니다.

https://docusaurus.io/ko/docs/markdown-features/react

https://mdxjs.com/

 

MDX는 도큐사우루스에서만 지원하는 기능은 아닙니다. 개츠비에서도 MDX를 지원하고 있습니다. 다만 개츠비보다 도큐사우루스에서 좀 더 직관적으로 쉽게 활용할 수 있도록 기능을 제공하는 듯합니다.

https://www.gatsbyjs.com/docs/glossary/mdx/

 

* 이전 글에서 블로그 전용으로 변환한 후 이를 다시 원복하면 아래와 같이 오류가 나기도 합니다.

이럴 때는 당황하지 말고 도큐사우루스를 멈추고 다시 시작하면 됩니다.

내부적으로 뭔가 꼬이는 현상인 듯합니다.

 

 

728x90