이 문서 인프라에 대하여

Source: Dev.to

번역을 진행하려면 번역하고자 하는 전체 텍스트를 제공해 주시겠어요?
텍스트를 알려주시면 요청하신 대로 마크다운 형식과 코드 블록, URL은 그대로 유지하면서 한국어로 번역해 드리겠습니다.

개요

이 페이지는 SRDD 문서가 어떻게 구조화되고, 빌드되며, 게시되는지를 설명합니다. 모든 문서는 GitHub 저장소의 ./documentation 디렉터리 내에 Markdown 파일로 존재하며, 단일 진실 소스로 작동합니다.

Documentation Structure

documentation/
├── index.md              # Entry point / overview
├── pitches.md            # Various length summaries
├── SRDD-part1-of-4.md    # Article series
├── SRDD-part2-of-4.md
├── SRDD-part3-of-4.md
├── SRDD-part4-of-4.md
├── CONTRIBUTING.md       # Contribution guide
├── about.md              # This file
└── .sync-state.json      # Dev.to sync state (auto‑generated)

각 Markdown 파일은 메타데이터(제목, 설명 등)를 위한 YAML 프론트 매터와 표준 GitHub‑flavored Markdown을 사용합니다.

Placeholder Syntax

내부 링크는 대상 플랫폼에 따라 변환되는 자리표시자 패턴을 사용합니다:

See [Part 1](https://dev.to/bbos/srdd-part-1-of-4-the-best-ai-coding-methodology-8fe) for details.

{{devto:slug}} 패턴은 다음과 같이 변환됩니다:

이렇게 하면 플랫폼마다 다른 URL을 하드코딩하지 않고도 문서 간에 링크를 연결할 수 있습니다.

퍼블리싱 워크플로우

단일 GitHub Actions 워크플로(.github/workflows/deploy-and-sync.yml)가 모든 퍼블리싱 단계를 처리합니다.

GitHub Pages용 Dev.to 플레이스홀더 변환

- name: Transform devto placeholders for GHP
  run: |
    find ./documentation -name "*.md" -exec sed -i -E \
      's/\{\{devto:([^}]+)\}\}/.\/\1.md/g' {} \;

Jekyll로 빌드

- name: Build with Jekyll
  uses: actions/jekyll-build-pages@v1
  with:
    source: ./documentation
    destination: ./_site

파이프라인 요약

1. 자산을 documentation 디렉터리로 복사합니다.
2. {{devto:slug}} 플레이스홀더를 상대 .md 링크로 변환합니다.
3. Jekyll로 사이트를 빌드합니다.
4. GitHub Pages에 배포합니다.

GitHub Pages 배포가 완료된 후, 두 번째 작업이 게시물을 Dev.to와 동기화합니다.

sync-to-devto:
  needs: deploy  # Run after deploy so canonical URLs are live
  steps:
    - name: Sync posts to Dev.to
      env:
        DEVTO_API_KEY: ${{ secrets.DEVTO_API_KEY }}
        SITE_URL: ${{ vars.SITE_URL }}

동기화 스크립트

동기화 스크립트(scripts/sync-to-devto/sync-to-devto.js)는 두 단계의 동기화를 수행합니다:

1. 1단계 – 각 Markdown 파일에 대해:

   • 프런트 매터와 내용을 파싱합니다.
   • 정규 URL( GitHub Pages를 가리킴)을 생성합니다.
   • 내용 변환(이미지에 절대 URL 적용, 스타일 제거)을 수행합니다.
   • API를 통해 Dev.to 기사을 생성하거나 업데이트합니다.
   • 반환된 Dev.to URL을 저장합니다.

2. 2단계 – {{devto:slug}} 자리표시자를 포함하는 문서를 다시 파싱하고, 1단계에서 얻은 실제 Dev.to URL로 교체한 뒤 기사를 다시 업데이트합니다.

URL 맵 예시 (1단계)

{
  "index": "https://dev.to/bbos/srdd-is-the-best...-4k2n",
  "SRDD-part1-of-4": "https://dev.to/bbos/why-srdd-exists-2j8m"
  // …
}

이 두 단계 접근 방식은 Dev.to의 동적 URL 생성에도 불구하고 모든 교차 참조가 올바르게 해결되도록 보장합니다.

해싱 및 동기화 상태

불필요한 API 호출을 방지하기 위해 각 포스트의 내용은 해시(SHA‑256, 32자까지 잘라서)됩니다. 해시는 documentation/.sync-state.json에 저장됩니다.

동기화 상태 예시

{
  "index": {
    "hash": "a1b2c3d4e5f67890...",
    "syncedAt": "2026-01-07T10:00:00Z",
    "url": "https://dev.to/bbos/srdd-...-4k2n"
  },
  "pitches": {
    "hash": "f0e1d2c3b4a59687...",
    "syncedAt": "2026-01-07T10:00:00Z",
    "url": "https://dev.to/bbos/pitches-...-2j8m"
  }
}

url 필드는 각 글의 Dev.to URL을 캐시하여, API 속도 제한으로 URL을 가져올 수 없을 때도 플레이스홀더를 해결할 수 있게 합니다.

동기화 로직

• 매 실행 시 현재 해시를 저장된 해시와 비교합니다.
• 해시가 다른 포스트만 동기화합니다.
• 업데이트된 상태 파일을 저장소에 커밋합니다.

전체 강제 동기화

변경 여부와 관계없이 모든 게시물을 동기화하려면 FORCE_SYNC 환경 변수를 설정하십시오:

env:
  FORCE_SYNC: 'true'

또는 로컬에서 실행하십시오:

node sync-to-devto.js --force

URL 캐시 새로 고침

기사의 이름이 바뀌었거나 URL이 변경된 경우, 캐시된 URL을 새로 고칩니다:

env:
  REFRESH_URLS: 'true'

또는 로컬에서 실행합니다:

node sync-to-devto.js --refresh-urls

정규 URL 및 SEO 이점

Dev.to의 모든 글에는 GitHub Pages 버전을 가리키는 canonical_url이 포함됩니다, 예:

canonical_url: https://docs-bbos.github.io/srdd/SRDD-part1-of-4/

이점

• SEO 통합: 검색 순위가 단일 URL에 집중됩니다.
• 플랫폼 유연성: 콘텐츠가 Dev.to, Medium 또는 향후 플랫폼에 표시될 수 있습니다.
• 단일 진실 원본: 독자는 언제나 권위 있는 버전을 찾을 수 있습니다.

새 페이지 추가

1. 적절한 front matter가 포함된 documentation/new-page.md 파일을 생성합니다.
2. {{devto:new-page}}를 사용해 다른 페이지에서 링크합니다.
3. main 브랜치에 커밋하고 푸시합니다.

파이프라인이 자동으로 GitHub Pages에 배포하고 새 페이지를 Dev.to와 동기화합니다.

필수 비밀 및 변수

이 인프라스트럭처는 방법론과 함께 진화하는 살아있는 문서를 위해 “한 번 작성하고, 어디서든 배포”를 가능하게 합니다.