옵시디언으로 깃허브 블로그 게시글 업로드하기

2025.06.26

[!tip] 이런 분들은 한 번 읽어보시면 좋을 것 같습니다.

옵시디언으로 문서를 관리하고 있으신 분

깃허브 블로그를 운영하고 있으신 분

나는 문서 정리를 옵시디언으로 하고 있다. 문서를 이 폴더 저 폴더에 뿌려 저장하는 것보다 툴이 있는 게 좋고, 회사/집/모바일 연동이 가능하고, 무료인 툴을 찾고 찾다가 일단 옵시디언에 정착했다. (정말 별의 별 툴을 전부 사용해봤음. 적어도 7~8개는 되지 않을까?) 내가 생각하는 옵시디언의 장점은:

문서 관리 도구 중 가장 가벼움.
자유도가 높음.
문서 관리 툴로서 필수 기능은 물론, 커뮤니티 플러그인으로 다양한 기능을 추가할 수 있음.
내가 원하는 기능을 직접 개발해서 추가할 수도 있음.
디자인 깔끔함. 플러그인의 일종으로 테마 적용 및 커스텀도 가능함.

모든 파일 관리를 옵시디언으로 하던 와중에, 대충 생각나는 것들을 끼적이는 메모장으로 전락한 내 옵시디언을 잘 활용 + 글을 잘 쓰는 개발자가 되고 싶어 깃허브 블로그를 만들었다. 여러가지 측면에서 다른 블로그 서비스보다 유리한 면이 많지만, 가장 귀찮은 점은 .md 파일을 작성하고 일일히 업로드해주어야 한다는 것. 이 때문에 예전부터 깃허브 블로그를 수도 없이 만들었지만, 매번 유지에 실패했다.

나는 모든 문서 작성을 옵시디언으로 하기 때문에, 작성 -> 배포까지 옵시디언 원툴로 했으면 좋겠다고 생각하여, 플러그인을 직접 만들까 고민하다가, 찾아보니 아니나 다를까 누군가 이미 만들어놓은 플러그인이 있었다. 내가 필요한 건 내 블로그 레포지토리의 특정 폴더에 .md 파일을 업로드 하는 것이 다였으므로, 바로 설치하여 사용해보았다.

바로 이 플러그인이고, 지금 봤지만 최근 업데이트가 무려 4일 전인만큼 유지보수도 활발한 편인 것 같다.
설정도 매우 간단하다. 해당 플러그인의 설정에서 Github 권한을 설정할 수 있다. 해당 칸을 채워주면 된다.

그리고 가장 애먹었던 경로. 내 블로그 레포지토리의 구조가 최상단에 게시글을 모아두는 폴더가 있기 때문에 해당 폴더명을 기재했다. 파일명이 공백이 들어감을 방지하기 위해 공백을 대시로 변경해주는 정규식을 입력해주었다.

어떤 파일을 업로드할지 구분하기 위한 표시가 필요하다. 그래서 파일의 프론트포매터(frontformatter)에 특정한 key값을 설정한다.

---
share: true
---

이 녀석을 추가해주고, ctrl+P 단축키를 눌러주면 다음과 같이 지금 보고 있는 문서를 업로드할 수 있다.

업로드 전에, 블로그 코드에서 파일명을 인코딩해주는 작업이 되었는지 확인이 필요하다. 업로드된 파일명은 문서의 제목인데, 이게 한국어로 작성되어 있으면 인코딩/디코딩 처리를 해주어야 한다. 이것도 모르고 대체 왜 에러가 나는지, 코드와 플러그인 설정 중 어느 것을 수정해야 하는지 지피티와 열심히 씨름했는데, 1) 파일은 제대로 업로드 되었음. 2) 빌드 단계 중 fs.readFileSync()에서 에러 -> 코드상 에러 임을 추론하는데 시간이 오래 걸렸다 ... 🥲

블로그의 게시글을 읽는 과정에서, 업로드 된 파일명이 한글인 경우를 위해 인코딩 처리 과정이 필요하다. 파일명을 기준으로 라우팅 처리를 하기 때문에, 그대로 가져와버리면 인코딩 -> 디코딩했을 때 파일 경로가 일치하지 않는 에러가 발생한다.

기존 코드는 다음과 같다.

const postsDirectory = join(process.cwd(), "_posts");

export function getPostSlugs() {
  return fs.readdirSync(postsDirectory);
}

그리고 다음과 같이 수정해주었다.

// 인코딩한 URL 문자열 반환
export function encodePostSlug() {
  return fs
    .readdirSync(postsDirectory)
    .filter(file => file.endsWith(".md")) 
    .map(file => {
      const rawSlug = file.replace(/\.md$/, "");
      return encodeURIComponent(rawSlug);
    });
}

// 디코딩하여 사용함
export function getPostBySlug(slug: string) {
  const decodedSlug = decodeURIComponent(slug);
  const realFilePath = join(postsDirectory, `${decodedSlug}.md`);
  ...
}

수정해주고 나니 바로 빌드, 배포에 성공했다. 템플릿에 share: true 포매터를 기재하여 자동 추가해주는 작업까지 더해주고 나면, 단축키 하나로 파일을 깃허브에 올릴 수 있게 된다! 아주 편리한 환경을 만들었다.