앱은 어디로 내보내나

“site/는 문서를 배포하기 위함이지요? 앱을 배포하기 위해서는 어떤 디렉토리가 필요한가요?” (메인테이너, 2026-10-25)

한 줄 요약

앱을 내보내려고 따로 만드는 폴더는 없습니다. 코드는 src/에 두고, 빌드 결과(dist/)는 저장소에 넣지 않습니다. GitHub Actions가 빌드해서 배포 대상마다 정해진 곳으로 보냅니다.

site/는 무엇인가

site/는 문서 사이트(Quartz)의 설정입니다. 사이트 그 자체가 아닙니다. 빌드한 HTML은 저장소에 없고, Actions가 빌드할 때마다 만들어 GitHub Pages에 올립니다(→ github-pages-site). 앱도 같은 방식입니다.

빌드 결과는 커밋하지 않는다

백엔드로 치면 Maven의 target/나 Gradle의 build/를 커밋하지 않는 것과 같습니다.

  • 빌드 결과는 소스에서 언제든 다시 만들 수 있습니다. 커밋하면 소스와 어긋나기 쉽고, 저장소가 커집니다.
  • 그래서 dist/는 .gitignore에 넣고, CI가 깨끗한 환경에서 빌드한 것만 내보냅니다.

배포 대상마다 내보내는 곳

배포 대상코드내보내는 곳
웹src/apps/web문서 사이트와 같은 GitHub Pages의 /app/ 주소. 문서 사이트를 빌드하는 워크플로가 앱도 빌드해 그 자리에 넣는다
데스크톱src/apps/desktopGitHub Releases. 판 하나에 설치 파일(Windows · macOS · Linux)을 첨부한다
Obsidian 플러그인src/apps/obsidianGitHub Releases. 판 하나에 main.js · manifest.json · styles.css 세 파일을 첨부한다

GitHub Releases는 저장소에 붙은 “판 목록”입니다. 태그(1.0.0 같은)마다 설명과 파일을 붙여 둘 수 있고, 사용자는 거기서 내려받습니다. 백엔드로 치면 Maven 저장소에 올린 jar와 비슷하지만, 저장소 페이지 안에 있습니다. 판마다 Pre-release 표시를 켤 수 있습니다. 켜면 “아직 안정판이 아님”이라는 딱지가 붙습니다. AriadneNSD의 v0.1.0(웹 MVP)은 1.0 전이라 켜 두었습니다(2026-11-02).

Obsidian이 저장소 맨 위의 manifest.json을 읽는 까닭

Obsidian의 커뮤니티 플러그인 목록은 등록된 저장소의 **맨 위에 있는 manifest.json**을 읽어 플러그인의 이름, 지금 판, 최소 Obsidian 판을 압니다. 그 판의 파일은 같은 이름의 Release에서 받아 갑니다.

우리 코드는 src/apps/obsidian/ 아래에 있어서, 원본은 거기 두고 사본을 맨 위에 둡니다(versions.json도 함께: 플러그인 판마다 필요한 최소 Obsidian 판). 판을 올리는 스크립트가 복사하고, 둘이 다르면 CI가 실패합니다 → ADR-0036

더 읽을거리