DrLeeWorks
한국어English
· 컴퓨팅 · DrLeeWorks

웹사이트 글 작성에 자주 사용하는 Markdown 문법

웹사이트 글 작성에 필요한 Markdown 문법, 이미지·영상 삽입, 상대 경로와 DrLeeWorks 전용 스타일을 복사 가능한 예제로 정리한 치트시트.

수정일:

#Astro#유지보수
Read in English →

게시물을 쓰면서 자주 찾아보는 Markdown 문법을 한곳에 모았다. 필요한 예제를 골라 복사하고, 파일명과 주소만 바꿔 쓰면 된다. 뒤쪽에는 DrLeeWorks에 맞춰 표현을 다듬은 CSS와 글이 제대로 표시되지 않을 때 확인할 내용을 정리했다.

편집은 VS Code로 해도 충분하다. 긴 글을 쓸 때는 Obsidian 같은 Markdown 편집기도 편하지만, 미리보기의 모양이 실제 사이트와 꼭 같지는 않다.

1. 자주 사용하는 Markdown 문법

제목

게시글 제목은 frontmatter의 title이 맡으므로 본문은 ##부터 시작한다. # 뒤를 한 칸 띄우고, 내용이 세분될 때마다 제목 단계를 하나씩 낮춘다.

## 큰 주제
### 세부 주제
#### 추가 구분

굵게·기울임·취소선

**중요한 내용**
*덧붙이는 설명*
_덧붙이는 설명_
~~취소한 내용~~

*…*와 _…_는 원래 기울임체 문법이다. DrLeeWorks에서는 덧붙이는 설명에 쓰기 위해 모양을 바꿨다. 이 차이는 4절에서 다룬다.

글머리 목록·번호 목록

항목 기호 뒤는 한 칸 띄운다. 목록 중간에 설명을 덧붙일 때는 아래 예제처럼 빈 줄과 들여쓰기로 같은 항목에 묶는다.

- 첫 번째 항목
- 두 번째 항목

1. 데이터를 준비한다.

   *원본 파일은 따로 보관한다.*

2. 결과를 확인한다.

링크

[GitHub](https://github.com/)
[같은 사이트의 다른 글](/ko/computing/path-basics/)

인라인 코드

명령어나 파일명은 작은따옴표가 아닌 백틱으로 감싼다.

`index.md`를 열고 `npm run dev`를 실행한다.

코드 블록

여러 줄의 코드는 백틱 세 개로 감싸고, 첫 줄에 언어명을 붙인다.

```python
print("Hello")
```
```powershell
npm run dev
npm run build
```

언어명에는 python, javascript, typescript, powershell, bash, html, css, json 등을 쓴다. 단순한 텍스트라면 text로 적거나 비워 두면 된다. 이 자리는 코드의 제목을 적는 곳은 아니다.

이 글처럼 백틱 세 개가 포함된 작성 예제를 보여주려면 바깥쪽을 백틱 네 개로 감싼다.

표

| 항목 | 설명 |
| --- | --- |
| 원본 | 수정 전 데이터 |
| 결과 | 처리한 데이터 |

인용문

> 다른 자료에서 인용한 문장이나 구분해서 보여줄 내용.
>
> 여러 문단을 넣을 수도 있다.

2. 이미지와 영상 삽입

기본 이미지와 캡션

이미지를 넣는 기본 형식은 ![대체 텍스트](경로)다. 대괄호 안에는 무엇을 담은 그림인지 적고, 독자에게 보여줄 캡션은 그림 아래에 따로 쓴다.

![시편에 장착한 신률계](./extensometer.png)

*신률계의 칼날이 시편 표면을 따라가며 연신량을 측정한다.*

그림 아래 설명이라는 것을 알아보기 쉽도록 캡션 앞에는 ▲이 자동으로 붙게 해 두었다. 기호를 직접 적을 필요는 없다. 일반 이미지 뒤에는 빈 줄이 없어도 동작하지만, 편집할 때 구분하기 쉽도록 위처럼 한 줄을 비워 두는 편이 낫다. 중간에 다른 문단이나 제목이 끼면 캡션으로 인식되지 않는다.

실제로 표시하면 이런 모양이다.

제임스웹 망원경으로 촬영한 SMACS 0723 은하단

James Webb Space Telescope – Webb’s First Deep Field (SMACS 0723). Image Credit: NASA, ESA, CSA, STScI.

이미지 폭 조절

그림이 너무 크게 보일 때는 img-75로 감싼다. 본문 폭의 75% 이내로 줄여 가운데 놓도록 정의해 둔 클래스다. 복사할 때 HTML 앞뒤의 빈 줄도 유지해야 한다.

<div class="img-75">

![신률계 구조](./extensometer.png)

</div>

*각 부위의 명칭과 칼날의 위치.*

GIF

GIF도 이미지처럼 넣으면 된다. 파일이 커지면 페이지가 느려지므로 필요한 장면만 짧게 담는 편이 좋다.

![그립의 움직임](./jaw.gif)

*하중이 증가할 때 그립이 움직이는 모습.*

YouTube

새 글에 YouTube 영상을 넣을 때는 .mdx에서 기존 YouTube 컴포넌트를 불러오는 방식이 편하다. 아래 경로는 이 저장소의 게시글 폴더 구조에 맞춘 것이다. 확장자를 바꾼 뒤 같은 폴더에 index.md가 함께 남아 있지 않도록 확인한다.

import YouTube from '../../../../../components/YouTube.astro';

<YouTube id="kpTIeRqItoM" title="YouTube 영상" />

.md를 그대로 쓰려면 HTML로 넣는다. 기존 youtube-embed 스타일을 이용하면 영상 비율도 16:9로 맞춰진다.

<div class="youtube-embed">
  <iframe
    src="https://www.youtube-nocookie.com/embed/kpTIeRqItoM"
    title="YouTube 영상"
    loading="lazy"
    allowfullscreen>
  </iframe>
</div>

kpTIeRqItoM은 넣으려는 영상의 ID로 바꾼다. HTML 예제의 src 끝에 ?start=27을 붙이면 27초부터 재생된다. 다만 현재 YouTube 컴포넌트가 받는 값은 id와 title뿐이다.

MDX 컴포넌트는 Obsidian 미리보기에서 실행되지 않으니 사이트에서 확인해야 한다. 영상 파일은 용량이 큰 만큼 저장소에 직접 넣기보다 외부 영상 서비스에 두는 편이 관리하기도 낫다.

3. 파일 및 경로 관리

index.md와 이미지는 한 폴더에 모아 둔다. 글에 쓰는 파일을 함께 찾기 쉽고 경로도 짧아진다.

my-post/
├─ index.md
└─ figure.webp
경로의미
./figure.webp현재 Markdown 파일과 같은 폴더
./images/figure.webp현재 폴더 아래의 images 폴더
../figure.webp한 단계 위 폴더
/images/shared.webp사이트의 public/images/shared.webp에 대응하는 공개 URL

새 파일명은 공백 없이 영문 소문자와 하이픈으로 짓는 편이 무난하다. 이미 공백이 들어간 이름이라면 경로를 < >로 감싸면 된다.

![제임스웹 이미지](<./제임스웹 이미지.png>)

영어 번역본도 한국어 원본의 그림을 함께 사용한다. 파일을 다시 복사하지 않고 상대경로로 연결한 뒤 대체 텍스트와 캡션만 번역하는 방식이다.

![Extensometer](../../../ko/engineering/tensile-test-basics/extensometer.png)

*The knife edges follow the specimen surface.*

Obsidian에서는 Wikilinks 사용을 끄고, 링크 형식은 상대경로, 첨부파일 위치는 현재 파일과 같은 폴더로 맞춰 두면 편하다. 그러면 ![[image.png]] 대신 사이트에서 쓰는 ![설명](./image.png) 형식으로 관리할 수 있다.

4. DrLeeWorks에서 사용하는 커스텀 스타일

문법은 같아도 화면에 보이는 모양은 사이트마다 다르다. DrLeeWorks에서는 부가 설명이 본문과 구분되고 큰 그림이나 표도 읽기 편하도록 몇 군데를 조정했다. 실제 설정은 src/styles/global.css와 src/components/YouTube.astro에 있다.

요소현재 구현
보조 문장게시글 본문의 .markdown-body em에 연한 회색 테마 변수, 0.94em, 기울임 제거 적용
그림 설명.prose 안에서 이미지 바로 뒤의 em, 이미지 단독 문단 다음의 em, img-75 다음 설명 및 figcaption 앞에 ▲ 추가
이미지본문 이미지 폭 100%, 높이 자동. img-75는 최대 폭 75%와 가운데 정렬
코드 블록코드용 글꼴, 여백, 가로 스크롤. Astro 구문 강조가 코드 색상을 지정하고 전역 pre 스타일이 어두운 배경과 기본 글자색 제공
표·수식넓은 표와 표시 수식은 본문 안에서 가로 스크롤
YouTubeyoutube-embed가 16:9 비율 유지. 컴포넌트는 youtube-nocookie.com과 지연 로딩 사용

예를 들어 보조 문장은 아래 CSS로 처리한다. 공통 스타일에 들어 있으므로 글마다 붙여 넣지 않아도 된다.

.markdown-body em {
  color: var(--muted);
  font-size: 0.94em;
  font-style: normal;
}

현재 이미지 폭 조절에는 img-75만 쓰고 있으며 img-50은 없다. 코드 블록의 언어명 배지나 복사 버튼도 아직 구현하지 않았다. 편집기에서 보이는 기능이 그대로 사이트에 따라오는 것은 아니다.

삼각형 역시 모든 그림 아래 문장에 붙는 것은 아니다. 캡션으로 표시한 문장에만 적용된다.

5. 표시가 이상할 때 확인할 사항

증상확인·수정 방법
*문장처럼 별표가 보임닫는 별표를 넣어 *문장*으로 작성
* 문장 *이 그대로 보임별표 바로 안쪽 공백 제거
\*문장\*이 그대로 보임역슬래시는 문자 그대로 표시하는 용도. 강조하려면 제거
</div> 다음 설명에 별표가 보임HTML 블록 뒤에 빈 줄 추가. 여는 태그와 내부 Markdown 사이에도 빈 줄 유지
**+**를 같은 표현이 깨짐**+** 버튼을처럼 띄어 쓰거나 한글 조사까지 강조 범위에 포함
그림이 보이지 않음파일 존재 여부, 대소문자, 확장자, 현재 문서 기준 상대경로 확인
공백 있는 파일명이 깨짐경로를 < >로 감싸기
코드 안에서 Markdown이 적용되지 않음문법 자체를 보여주는 정상 동작
캡션에 삼각형이 없음이미지 바로 뒤에 *설명* 또는 _설명_을 썼는지 확인
편집기와 사이트 모양이 다름사이트 전용 CSS가 적용되는 브라우저에서 확인

괄호 뒤에 한글 조사가 붙어서 굵은 글씨가 풀리는 경우도 있다. 이때는 조사까지 함께 감싸면 해결된다.

잘못된 예: **명령줄(CLI)**을 사용한다.
수정한 예: **명령줄(CLI)을** 사용한다.

6. 게시 전 확인

글을 다 썼다면 프로젝트 루트에서 개발 서버를 열고 http://localhost:4321에 접속한다.

npm run dev
  • 이미지와 캡션이 정상적으로 표시되는가?
  • 링크가 올바른 페이지로 연결되는가?
  • 코드 블록과 Markdown 기호가 의도대로 표시되는가?
  • 모바일 폭에서 본문이나 표가 화면 밖으로 밀려나지 않는가?
  • 한글·영문 번역본의 내용과 이미지 참조가 맞는가?
  • 아래 빌드가 오류 없이 끝나는가?
npm run build

좋아요 동작도 확인하려면 로컬 DB를 준비한 뒤 npm run likes:dev로 8788 포트의 서버를 연다. 여기서는 빌드된 파일을 보여주므로 글을 고친 뒤 다시 빌드해야 한다. 확인이 끝나면 커밋·푸시하고, Pages 배포가 완료됐는지 살펴본다.

좋아요 불러오는 중…

문의 이메일

[email protected]

후원

buymeacoffee.com/drleeworks