gui-gitea-operation/guide-readme/tpl.md

tpl-* (템플릿) Repository README 작성 가이드

tpl-* 접두사가 붙은 저장소는 새로운 프로젝트를 신속하게 시작할 수 있도록 설계된 템플릿입니다. README의 핵심 목표는 사용자가 이 템플릿을 어떻게 사용하고, 자신의 요구사항에 맞게 커스터마이징하는지 명확하게 안내하는 것입니다.

---

1. 템플릿 소개 (Template Introduction)

• 핵심: 이 템플릿이 어떤 종류의 프로젝트(예: React 웹앱, FastAPI 서버)를 위한 것인지 한 문장으로 설명합니다.
• 포함된 기술 스택: TypeScript, Next.js, Docker 등 주요 기술 스택을 나열하여 사용자가 기술적 요구사항을 빠르게 파악할 수 있도록 합니다.

2. 시작하기 (Getting Started)

• 목적: 사용자가 템플릿을 기반으로 새로운 프로젝트를 생성하는 과정을 단계별로 안내합니다.
• 명령어 예시:

  # 1. GitHub에서 "Use this template" 버튼을 클릭하거나, degit을 사용해 프로젝트를 생성합니다.
  npx degit your-github/tpl-react-basic my-new-project
  
  # 2. 프로젝트 디렉토리로 이동합니다.
  cd my-new-project
  
  # 3. 의존성을 설치합니다.
  npm install
  
  # 4. 개발 서버를 실행합니다.
  npm run dev
  

3. 프로젝트 구조 (Project Structure)

• 목적: 템플릿이 제공하는 기본 폴더 구조와 각 디렉토리의 역할을 설명합니다.
• 시각화: tree 명령어 결과나 다이어그램을 활용하여 구조를 명확하게 보여줍니다.
• 예시:

  /
  ├── public/           # 정적 파일 (이미지, 폰트)
  ├── src/
  │   ├── components/   # 재사용 가능한 UI 컴포넌트
  │   ├── pages/        # 페이지별 컴포넌트
  │   └── styles/       # 전역 스타일시트
  ├── .env.example      # 환경변수 예시 파일
  └── package.json
  

4. 커스터마이징 방법 (Customization Guide)

• 핵심 섹션: 사용자가 템플릿을 자신의 프로젝트에 맞게 수정하는 방법을 안내합니다.
• 주요 항목:
  • 테마 및 스타일: src/styles/theme.ts 파일에서 색상, 폰트 등을 수정하는 방법을 설명합니다.
  • 환경 변수: .env.example 파일을 복사하여 .env 파일을 만들고, 필요한 API 키 등을 설정하는 방법을 안내합니다.
  • 기본 컴포넌트 수정: 로고, 페이지 제목 등 기본적으로 수정해야 할 부분을 명시합니다.
• 팁: 표(Table)를 사용하여 각 커스텀 옵션과 해당 파일을 명시하면 가독성이 높아집니다.

기능	파일 경로	설명
로고 변경	src/components/Header.tsx	웹사이트의 로고 이미지를 교체합니다.
테마 색상	src/styles/theme.js	프라이머리, 세컨더리 색상을 변경합니다.
폰트 적용	src/styles/global.css	Google Fonts 등 외부 폰트를 추가합니다.

5. 스크린샷 또는 데모 (Screenshot or Demo)

• 목적: 템플릿을 사용했을 때 결과물이 어떻게 보이는지 시각적으로 보여줍니다.
• 팁: 기본 템플릿의 랜딩 페이지 스크린샷이나, Storybook 배포 링크를 첨부하면 효과적입니다.