👩‍💻Quarto Blog 기본 셋팅

blog
quarto
code
Quarto로 속편한 Github Blog 구축하기(1)
Published

January 7, 2024

이번 포스팅은 Github Blog를 만들어 갔던 경험과 그 경험들을 통해 Quarto라는 좋은 툴을 소개하기 위한 글로 준비를 했습니다. 본격적인 Quarto로 속편한 Github Blog를 구축하는 방법을 소개하기 전에 어떻게 Quarto를 알게 되었고 적극적으로 소개하게 되었는지 이야기를 드릴려고 합니다.

이전에 글또 7기를 시작하는 다짐글에서 잠깐 기술 블로그 방황기에 대해 언급을 한 적이 있었습니다. 하지만 기술 블로그를 작성해보고 싶은 계기부터 잠깐 이야기해보려고 합니다. 학부 전공은 기계공학과인지라 컴퓨터, IT 관련글들을 볼 기회가 많았던 것은 아니지만 어쩌다보니 AI, 인공지능의 매력에 빠져서 공부를 하다보니 책보다는 구글링과 유튜브로 많은 지식들을 배우게 되는 경험들이 자연스럽게 기술 블로그를 작성하는 문화에 빠져들게 되었습니다. 저와 같이 아무것도 모르는 사람들을 위해 친절한 설명들과 단계별 캡쳐 사진들을 따라가다보면 원하는 프로그램을 실행시킬 수 있었고, 때론 내가 막혀있던 점들을 푼 이전의 누군가의 간단히라도 적어둔 팁을 확인하고 도움을 얻을 수 있었기 때문에 잘 키워가는 기술 블로그 하나 열 책 안 부러울 정도로 기술 블로그에 대한 막연한 동경이 있었습니다.

그러다가 어느 정도 공부를 하다보니 "나도 한번 내 기술 블로그를 운영해볼까?"라는 호기가 생겼습니다.

시작도 하기 전에 (살짝은) 비장했던 마음도 있었고 설렜던 마음도 있었습니다. 아직 어떻게 블로그를 만들지 생각도 없었지만 나도 무언가를 아카이빙하고 그 글들이 다른 많은 사람들에게 도움이 되면 좋지 않을까라고 생각하며 유명해지면 어떨까..?라는 행복회로를 돌리며 다들 어떻게 기술 블로그를 만드는지 찾아보기 시작했습니다. 나름 AI 공부를 하며 코딩을 할 줄 아니까 Markdown까지는 문서를 작성하는 규칙이니 쉽게 적응을 했지만, 웹 개발은 정말 잘 모르는 분야에다가 웹 개발 공부에 시간을 투자하면서 까지 Github 블로그를 만들 수는 없었기에 눈 앞이 깜깜해지는 기분이었습니다.

물론..! 이전에 Hugo, Notion 개인 도메인, Velog 등등 여러 블로그 구축 방법들도 있었지만 플랫폼마다 커스텀하기가 어려운 점도 있었고 새로운 언어를 새롭게 공부해야 하는 경우들도 있었기 때문에, 저는 최대한 블로그의 내가 쓸 내용 Contents에 집중할 수 있도록 내용이 Compile/Rendering 되는 건 알아서 해주면 좋겠다는 바람이 있었습니다. (왜 Github Blog를 선택했는지는 여러 조건과 개인적 선호를 반영한 내용이 있으니 이전글을 참고해주세요!) 그러던 중에 FastAI에서 딥러닝 기술 블로그를 가장 심플하고 빠르게 작성할 수 있는 FastPages를 만들었다는 걸 알게 되었고 이 FastPages를 활용해서 잘 작성하고 있었습니다. FastPages의 최대 장점은 AI에서 많이 사용하는 Jupyter Notebook 형식의 파일을 그대로 포스팅을 할 수 있는 기능 등을 통해 원래 제가 원했던 점인 정말 Contents에 집중할 수 있는 환경을 만들어주는 Build 프로그램이었기에 정말 마음에 쏙 들었고 그대로 기술 블로그를 만들었습니다.

그렇게 이제는 더이상 블로그 이사를 안할 줄 알았지만..(블로그 이사는 정말 품이 많이 드는 것 같아요🥲) fastpages repository에 청천벽력과 같은 공지가 붙게 되었습니다.

…

아예 Fastpages 서비스를 닫아서 블로그가 아예 안열리는 것은 아니었지만, 블로그 지속성을 위해 마지막 블로그 이사를 Quarto로 하게 되었고 결과적으로는 Fastpages보다 Quarto가 훨씬 사용하기도 편하고 적당한 자유도가 있는 플랫폼이라는 생각이 들어서 오늘 이 포스팅을 통해 많은 분들께 알리고 싶어서 글을 작성하게 되었습니다. 생각보다 많은 분들이 알고 계시지 않은 것 같아 앞으로 주변에 더더욱 열심히 홍보하려고 합니다. Quarto를 중심으로 VSCode(+Copliot), Typora를 사용하면 더욱 쾌적한 블로그를 만들 수 있기 때문에 Quarto를 메인으로 다른 프로그램들은 가볍게 서포트 프로그램이라고 생각해주시면 될 것 같습니다.

그럼 프로그램들을 하나씩 살펴본 후에 Github repository를 하나 만들어서 블로그(Website)를 하나 만들어보는 실습까지 가보도록 하겠습니다!

Quarto

홈페이지를 들어가보면 정말 AI, Data 친화적인 글 작성 플랫폼이라는게 온몸으로 느껴집니다. 우선 홈페이지에서 찾을 수 있는 상단 소개 멘트로 Quarto의 철학을 살펴보면, 말 그대로 과학적이고 기술적인 글들을 위한 프로그램이라는 것을 알 수 있습니다.

An open-source scientific and technical publishing system

Quarto가 주요 콘텐츠로 타겟팅한 언어는 Python, R, Julia와 같이 AI 뿐만 아니라 과학, 수학적 실험시에 많이 사용되는 컴퓨터 언어들을 지원하는 것을 알 수 있습니다. 또한 제가 사용하게 된 가장 강력한 이유인 Jupyter notebook과 같은 .ipynb 파일 형식 그대로를 interactive하게 포스팅할 수 있는 기능이 있습니다!

Quarto에서의 기본 문서 파일 작성 Format은 .qmd

Quarto에서는 기본적으로 .qmd 파일 형식으로 포스팅 글들을 적게 됩니다. 기존의 Markdown형식의 파일들의 확장자가 .md였다면 이를 Quarto에서 조금 변형하여 만든 파일 형식이라고 보시면 되고 Markdown 작성과 다른 부분은 거의 없어서 기존의 Markdown 형식의 글들을 그대로 옮겨서 Compile하실 수 있습니다. .qmd파일 형식 이외에 앞서 말씀드린 대로 Jupyter Notebook을 통해 작성한 .ipynb 형식의 파일들도 바로 Compile 가능하다는 건 정말 편한 기능입니다!

VSCode + Copliot

사실 VSCode는 Markdown 작성할 때 뿐만 아니라 여러 코딩 언어들로 작업할 때도 많이 쓰이는 편집기 입니다. 그래서 Markdown을 작성하기 위해 특별히 좋다라고 할 수는 없지만 Jupyter Notebook 형식이 아닌 블로그 글들을 적을 때는 Quarto에서 Build하기 편하기 때문에 VSCode를 추천합니다. 물론 Quarto 공식 홈페이지에서도 처음 Instruction에서 VSCode를 사용하고 VSCode 내부 확장 프로그램 Quarto를 써야 하기 때문에 추천이라기 보다 꼭 써야 하는 프로그램일 수도 있겠네요..! VSCode 자체의 장점도 있지만 Copliot을 같이 쓰게 된다면 가끔 한글자 더 타이핑하지 많아도 내용이 자연스럽게 추천 작성이 되기 때문에 너무 편하기도 합니다.

Typora

사실 Github Blog를 만들때 한 가지 또 발목을 잡게 되는 부분이 이미지를 글에 적당히 넣는 작업인 것 같습니다. 정말 1개의 글을 잘 쓰려고 하다보면 많은 적절한 이미지들을 글 사이사이에 넣어야 하는데, 간단히 편집하고 크기를 조절하면서 이미지를 글에 삽입하는 과정에서 Drag & Drop으로 간단히 넣을 수만 있다면 글을 작성하는 피로도가 확 감소합니다. 사실 이런 부분이 Github Blog로 운영하지 않고 Notion과 같은 다른 플랫폼을 이용한다면 당연히 Drag & Drop으로 넣고 쉽게 편집할 수 있는 거 아니야? 하겠지만, Markdown으로 작성(.qmd 형식)하는 저는 이미지들을 저장하고 각 이미지들의 경로들을 설정해서 글에 코드로 넣고 해당 이미지가 맞는지 확인하는 것도 신경써야 할 큰 일이었습니다.

그러던 와중에 Typora라는 좋은 프로그램을 알게 되었습니다. 많이 쓰시는 Notion처럼 글을 작성하면서 동시에 그림이 랜더링된 모습을 확인할 수 있고, 그래서 글을 작성할 때 더 내용을 이미지들과 유기적으로 연결 되는지 확인해가며 작성할 수 있습니다.

Typora로 작성했을 때 Notion처럼 작성할 수 있는 Markdown

단, 여기서 Typora로 이미지를 Drag & Drop을 하게 되면 자동으로 이미지의 경로를 Typora에서 작성해주게 되는데, 삽입되는 이미지 경로를 저장해주는 설정을 아래와 같이 수정해서 설정을 바꿔주면 훨씬 사용하기 편합니다. Typora 창의 왼쪽 상단의 File - Preferences - Image 로 들어가서 아래와 같이 이미지 경로를 원하는 곳으로 설정하면 Blog Repository에 있는 작성하고 있는 글의 경로를 중심으로 이미지를 참조하여 넣을 수 있습니다.

Typora Image 경로 설정

위의 사진에서 처럼 설정하게 되면 작성하고 있는 .qmd파일에 ![이미지_캡션](../../images/[포스팅_이름.qmd]/[이미지_이름.png])와 같이 코드가 작성이 된 것을 확인할 수 있습니다. Markdown에서 이미지를 넣는 형식과 크게 다르지 않지만 만약 html 문법을 이용해서 이미지 정렬, 사이즈 조절과 같은 옵션 설정이 필요하다면 이 포스팅의 이후 시리즈로 작성한 Quarto Blog(2) - 이미지 넣기를 참고해주세요!

Blog(Website) 만들기

Quarto를 가지고 이제 본격적으로 Blog를 만드는 실습을 하기 전에 Quarto 설치는 공식 홈페이지의 순서를 따라 진행해주시길 바랍니다. 어렵지 않기 때문에 각자 OS 환경에 맞는 프로그램을 설치한 후 아래의 순서를 따라 진행하도록 하겠습니다. Blog는 Quarto에서 소개하고 있는 Website 만들기를 따라 진행하는 내용과 크게 다르지 않기 때문에 혹시 포스팅 내용에 오류가 있다면 공식 instruction을 크로스 체크 해보셔도 좋을 것 같습니다.

  1. 블로그를 만들 Github Repository 하나 만들기
  2. Repository를 Clone 하여 Quarto project 시작하기
  3. Default Blog localhost로 확인하기
  4. Rendering 한 후 Blog publish하기

1. Repository 하나 만들기

블로그를 만들 Repository를 Github에 하나 만들어 줍니다. Repository는 어떤 이름을 가지고 있어도 상관없지만 보통 Github에서 개인 블로그 주소를 본인의 nickname.github.io로 만들기 때문에 저는 아래와 같이 블로그를 위한 Repository를 만들었습니다.

다음으로 해당 Repository의 Settings에 들어가서 블로그의 웹페이지들이 랜더링될 폴더를 /docs로 설정하는 과정을 아래와 같이 설정해줍니다.

다음으로 해당 repository를 원하는 경로에 clone 해서 블로그를 작성할 폴더를 준비합니다.

2. Quarto Project 시작

이제 VSCode를 열어서 확장 프로그램에서 Quarto를 검색한 후 해당 확장 프로그램을 VSCode에 깔아줍니다.

VSCode에서 Ctrl+Shift+P 단축키로 명령어 팔레트를 열어서 Qaurto:Create Project를 실행합니다.

출처: Quarto 공식 홈페이지

Blog Porject를 선택합니다. 이때 프로젝트 이름은 아무거나 입력헤도 됩니다. 프로젝트를 생성한 후, 프로젝트 하위에 있는 모든 파일들을 Github repository 이름과 동일한 폴더로 옮겨줍니다.

출처: Quarto 공식 홈페이지

그러면 Github Repository의 이름이 test_blog라고 했을 때 아래와 같이 폴더와 파일들의 구성이 되는 것을 확인할 수 있습니다.

Blog project 시작

3. Default Blog localhost로 확인

이제 VSCode에서 Blog Repository(test_blog)가 열린 프로젝트 창에서 터미널을 열어서 아래의 명령어를 입력해봅니다.

quarto preview

그러면 Default로 생성된 블로그 페이지가 localhost로 열리는 것을 확인할 수 있습니다.

Default Blog

Blog Publish

이전 단계에서는 localhost로 페이지를 랜더링해서 확인한 것이기 때문에 publish가 되지 않았습니다. quarto에서 프로젝트를 rendering하기 위해서는 publish를 하는 명령어를 실행해야 합니다.

하지만 그전에!

page들을 publish할 directory를 /docs로 따로 설정을 해주었기 때문에 해당 폴더에 랜더링된 html 파일들을 만들 수 있도록 아래와 같이 ._quarto.yml 설정파일을 아래와 같이 작성해줍니다.

project:
  type: website
  output-dir: docs

위와 같이 render이 잘 완료되었다는 메세지가 확인이 되면 아래의 명령어를 실행하여 publish 합니다.

quarto render

마지막으로 Github에 Push를 하게 되면 이제 website를 확인할 수 있습니다!(build되는데 약 2-3분 걸릴 수 있습니다.)

이번에는 Quarto Engine을 이용해서 간단하게 Blog Website를 올리는 부분을 진행했습니다. 좀 더 본격적으로 조정할 수 있는 옵션들에 대해서는 다음 포스팅에서 살펴볼 예정입니다.

Reference