Astro를 쓰기로 결정은 했는데 이걸 어디서부터 시작할지 막막했다. 단순히 글 좀 써보자고 덤벼들긴 했는데 아직 배가 산으로 가는 기분이 드는 건 어쩔 수 없었다.

불과 몇 년 전이였으면 개발의 개 자도 모르는 내가 직접 뭔가 만들어 보겠다는 생각은 전혀 안 했을 것이다. 이렇게 겁 없이 덤빌 수 있었던 건 오로지 AI 덕분이었다. 나는 Codex를 이용해 사이트를 만들기로 했다 (claude는 툭하면 용량제한으로 아무것도 못한 경험이 있어서 codex로 갈아탔는데 아직 성능 차이는 못 느끼고 충분한 용량에 수시로 공짜 reset을 줘서 만족한다)

아무 생각없이 codex가 주는 대로 딸깍만 하자니 찝찝했다. 난 무슨 일을 하든지 적어도 어떻게 돌아가는지는 알아야 마음이 편해진다. 지금 도대체 내가 무엇을 설치하는지, 파일은 어디에 생기는지, 사이트를 보려면 무엇을 켜야 하는지. 이 정도는 알아야 나중에 문제가 생기면 대략 감이라도 잡을 수 있지 않겠나.

1. 글 쓰기 전에 작업 도구부터 준비하기

우선 필요한 건 파일을 열고 수정할 프로그램이다. 워드 문서를 워드에서 열듯, 사이트 파일도 편집할 곳이 있어야 한다. VS Code라는 코드 편집기를 사용했다.

그리고 Node.js가 필요하단다 (벌써부터 포기하고 싶어졌다). Astro가 내 컴퓨터에서 일할 수 있게 해주는 실행 도구라고 이해하면 된다. 함께 설치되는 npm은 프로젝트에 필요한 프로그램들을 가져오는 일을 맡는다.

여기서 또 하나 등장하는 것이 터미널이다. 이건 사용자가 사용하기 편하게 만든 버튼 대신 글자를 직접 입력해서 컴퓨터에 명령을 하는 창이다. VS Code의 ‘터미널을 사용했다.

2. 내 사이트가 들어갈 폴더 만들기

이제 Astro 프로젝트를 만든다. ‘프로젝트’라고 하니 거창하지만, 여기서는 사이트에 필요한 파일을 한데 모아 놓은 폴더라고 생각하면 된다. 글, 화면 구성, 설정이 그 안에 들어간다. VS Code 안에서 새 터미널을 열고 다음 명령을 입력한다.

npm create astro@latest

새 Astro 프로젝트를 만드는 안내가 시작된다. 프로그램을 내려받겠냐고 물으면 내용을 확인하고 진행한다.

완료되면 방금 만든 폴더로 이동한다.

cd my-first-site

cd는 작업할 폴더로 들어가라는 뜻이다. 폴더 이름을 다르게 정했다면 그 이름을 넣는다. 이제 컴퓨터에 사이트의 기본 파일이 생겼다. 인터넷에 공개된 것은 아직 아니다.

3. 드디어 브라우저에서 열어보기

방금 들어간 프로젝트 폴더에서 다음 명령을 실행한다.

npm run dev

이건 사이트를 만들면서 확인할 수 있도록 미리보기용 서버를 켜는 명령이다. 서버라고 해서 어디선가 거대한 컴퓨터를 빌려오는 건 아니다. 지금은 내 컴퓨터에서 실행된다.

터미널에 http://localhost:4321/ 같은 주소가 나온다. 표시된 주소를 브라우저에서 열면 기본 화면을 볼 수 있다. 숫자가 다르게 나온다면 실제로 표시된 주소를 사용하면 된다.

여기서 localhost는 ‘지금 쓰는 이 컴퓨터’를 가리킨다. 그래서 이 주소를 친구에게 보내도 내 사이트를 볼 수는 없다. 친구의 컴퓨터에서 localhost는 친구 자신의 컴퓨터를 뜻한다. 아직은 내 작업 공간 안에서만 확인하는 중이다.

4. 화면 구성과 글 보관은 조금 다른 일이다

사이트의 모양을 만드는 일과 글을 보관하는 일을 나눠 생각하면 조금 편해진다.

내 사이트는 글을 Markdown이나 MDX 파일로 보관한다. Markdown은 제목이나 목록 같은 표시를 붙여 글을 쓰는 방식이다. 예를 들어 줄 앞에 #을 붙이면 제목으로 표현할 수 있다. MDX는 여기에 화면 구성 요소도 함께 넣을 수 있는 형식인데, 처음부터 둘 다 공부할 필요는 없다.

Astro는 이렇게 보관한 글을 사이트의 화면 구성에 맞춰 보여준다. 매번 글 한 편의 디자인까지 새로 만드는 것은 아니다. 지금은 Pages CMS라는 편집 화면도 사용한다. 그곳에서 글을 수정하면 내용이 GitHub에 저장된다. 하지만 이건 기본 사이트를 만든 뒤에 붙인 글쓰기 환경으로 이해하면 된다.

5. 내가 보는 화면과, 이용자가 보는 화면은 다르다.

내 컴퓨터에서 화면이 보이는 것과, 다른 사람이 인터넷에서 들어오는 것은 별개의 단계다.

수정한 사이트를 공개할 파일로 만드는 작업을 ’빌드’라고 한다. 내 사이트처럼 정적인 페이지를 만드는 Astro 프로젝트에서는, 글과 화면 구성 파일을 바탕으로 브라우저가 보여줄 결과물을 만든다.

npm run build

기본 설정에서는 결과물이 dist라는 폴더에 만들어진다. 성공한 뒤 npm run preview를 실행하면 그 결과물을 내 컴퓨터에서 확인할 수 있다. 이것도 아직 인터넷에 공개되는 건 아니다. 마지막 빌드 결과를 보는 것이므로, 이후 파일을 수정했다면 다시 빌드해야 반영된다. 그 결과물을 사람들이 접속할 수 있는 곳에 올리는 일이 ’배포’다.

내 사이트는 파일과 변경 기록을 GitHub에 두고, Cloudflare가 그것을 가져와 빌드하고 공개하도록 연결되어 있다. 독자는 ifitallends.com이라는 주소로 들어온다.

글이나 써 볼까 했던 놈이 어느 새 터미널이라는 검은 바탕 위에 이것저것 입력하고 있다. 순간 개발자라도 된 것 마냥 내 자신이 잠시 자랑스러워진다. 예전 영어로 외국인과 첫 대화를 하고 난 후 그 뿌듯했던 감정이 떠올랐다. 아직 뭐가 뭔지도 모르지만, 적어도 어떤 순서로 개발이 진행되는지 조금이나마 머릿속에 형태가 그려진다.

다음 편에서는 내 컴퓨터에 있는 사이트를 GitHub에 보관하고, Cloudflare를 통해 다른 사람도 볼 수 있게 공개하는 과정을 다룬다.