[TIL] Github Readme 작성하기 마크다운 HTML 비교 [ 기본편 ]

TIL

[TIL] Github Readme 작성하기 마크다운 HTML 비교 [ 기본편 ]

정상호소인 2023. 11. 14. 23:57

Topic = Github Readme를 보기 좋게 만들어보자

완성 코드

Github Readme

간단하게 Readme에 대해서 알아보고 사용법은 아래에 작성

[ Readme의 특징 ]

Readme는 깃허브 Repository에 포함된 프로젝트에 대한 설명과 문서를 작성하는 마크다운 형식의 파일이다. 리드미 파일 추가 시 .md 형식의 파일이 생성되는 것을 확인할 수 있다.
마크다운 형식 외에도 CSS, HTML 형식의 코드를 통해 Readme를 작성할 수 있지만 *사용자의 안전을 위해 JavaScript를 실행하지 않아 일부 HTML 및 CSS 기능을 제한하고 있다.

*JavaScript를 사용하게 될 경우 XSS( Cross Site Scripting ), CSRF ( Cross Site Request Forgery ) 등 의 공격이 이루어질 수 있기 때문에 이를 방지하기 위함 - 추후에 JS를 배우게 될 때 자세히 학습해볼 것 같다.

[ Readme의 역할 및 권장사항 ]

프로젝트 정보 안내
- 설치 방법, 사용법, 의존성 패키지, 실행 명령어, 설정 방법, 사용 예제 등을 제시하여 사용자가 프로젝트를 쉽게 이해할 수 있도록 한다.
라이선스 정보
- 오픈 소스 프로젝트의 경우, 사용되는 라이선스 종류와 라이선스 파일을 명시해야 한다.
시각적인 정보 제공 권장
- 뱃지, 이미지 스크린 샷 등을 통해 프로젝트의 상태, 버전, 프로젝트 외형, 주 기능 등의 시각적인 정보를 제공하여 사용자가 쉽게 이해할 수 있도록 하는 것이 권장된다.
참고 문헌 및 기여
- 프로젝트 참고 자료, 관련 링크 를 추가할 수 있고 기여자, 기여 방법 등의 부가적인 요소도 포함될 수 있다. 아래는 참고용으로 인스타의 Github를 가져와봤다.

[ Readme작성 시 주의점 ]

Github의 Readme 파일은 반드시 README.md 로 작성되어야 하며 해당 파일은 프로젝트 Repository의 최상위 디렉토리에 위치해야 한다.
Readme 파일에 이미지를 추가할 경우, 이미지 파일의 네이밍에 주의하여야 한다. 이미지 리소스 추가 시 소문자, 밑줄, 숫자, 마침표로만 구성되어야 하는데 한글이 포함될 경우 아래와 같은 문제가 발생할 수 있다.
→ ✔️ [ 11.15 수정 ] Github Issues 탭을 통하여 이미지 URL 얻어오는 방식으로 이미지 저장하기.
→ ✔️ 폴더 이름을 한글로 작성 시에도 오류가 발생할 수 있다.

Caused by: org.gradle.api.internal.plugins.PluginApplicationException: Failed to apply plugin 'com.android.internal.application'.

위와 같은 문제 발생 시 네이밍 규칙에 어긋난 파일을 올바르게 수정해주는 것이 권장되는 방식이지만 임시방편으로 프로젝트 단위의 gradle.properties에 아래의 코드를 추가함으로써 리소스 경로에 대한 추가적인 검사를 수행하지 않도록 하여 해결할 수 있다.

android.overridePathCheck=true

README.md 작성방법
HTML, Markdown 형식 각각 비교해보기

[ 행 바꾸기 ]

Markdown

첫번째 텍스트

두번째 텍스트

엔터 2번

HTML

첫번째 줄<br>두번째 줄

텍스트 속성

🟪 Markdown

[ MD 일반 텍스트 ]

Readme에 그냥 텍스트 입력해주면 된다

[ 링크 추가하기 ]

[텍스트](링크URL)

[ MD 텍스트 적용 속성 ]

텍스트 굵게 ( Bold )
- **굵은 텍스트** or __굵은 텍스트__ ( *표 또는 언더 스코어 2개 )
텍스트 기울임 ( 강세, italic )
- *기울임체* or _기울임체_ ( *표 또는 언더 스코어 1개 )
텍스트 밑줄
- MD형식은 밑줄 지원X
텍스트 가로 취소선
- ~~취소선 텍스트~~
코드 블록
- ```Hello World```
- 디자인이 이뻐서 디자인 요소로 사용해도 나쁘지 않을 것 같다
인용문
- >, >>, >>> 각 단계 별 인용문
- 디자인이 이뻐서 디자인 요소로 사용해도 나쁘지 않을 것 같다.
리스트
- 순서없는 리스트 - or * 기호
- 순서있는 리스트 숫자 + 마침표 ( 1. 2. )
수평선
- --- or ___ or ***
체크박스
- - [x] 할 일1
- - [ ] 할 일 2

[ 간단한 사용 예제 ]

> 인용문1
>> 인용문2
>>> 인용문3
>>>> 인용문4
>>>>> 인용문5

- 리스트
  - 리스트2
    - 리스트3
      - 리스트4

---

```Hello World```

- [x] 할일 1
- [ ] 할일 2

[ Readme 적용 모습 ]

🟨 HTML

[ HTML 일반 텍스트 ]

<p>일반 텍스트</p>

[ 링크 추가하기 ]

<p href

[ HTML 텍스트 적용 속성 ]

텍스트 굵게 ( Bold )
- <b>굵은 텍스트</b>
텍스트 기울임 ( 강세, italic )
- <em>기울임체</em>
- <i>기울임체</i>
- em과 i 태그는 똑같은 기능을 하지만 다르게 사용되어야 한다고 하는데 리드미에서 이를 활용할 수 구별할 상황이 있을진 모르겠다.
텍스트 밑줄
- <ins>밑줄 텍스트</ins>
텍스트 가로 취소선
- <s>가로선 텍스트</s>
- <del>가로선 텍스트<del>
코드 블록
- <code>Hello World</code>
- 디자인이 이뻐서 디자인 요소로 사용해도 나쁘지 않을 것 같다
인용문
- <blockquote>인용된 텍스트</blockquote>
- 인용문 안에 중복해서 인용문을 넣을 수 있다.
- 디자인이 이뻐서 디자인 요소로 사용해도 나쁘지 않을 것 같다.
수평선
- <hr>
체크박스
- HTML 는 깃허브 리드미에서는 type태그가 적용이 되지 않아서 HTML 형식 체크박스를 지원하지 않는 것 같다.
리스트
- 순서 없는 리스트

<ul>
  <li>항목 1</li>
  <li>항목 2</li>
  <li>항목 3</li>
</ul>

- 순서 없는 리스트

<ol>
  <li>항목 1</li>
  <li>항목 2</li>
  <li>항목 3</li>
</ol>

- 순서 없는 리스트에 세부 리스트를 추가하고 싶을 경우

<ul>
  <li>항목 1</li>
  <li>
    항목 2
    <ul>
      <li>세부 항목 1</li>
      <li>세부 항목 2</li>
      <li>세부 항목 3</li>
    </ul>
  </li>
  <li>항목 3</li>
</ul>

[ 간단한 사용 예제 ]

<blockquote>😺인용문<blockquote>😺인용문2</blockquote></blockquote>

<code>Hello World</code>

4=2<sup>2</sup>

[ Readme 적용 모습 ]

텍스트 헤더 지정

🟪 Markdown

# [#Header1](https://naver.com)
# #Header1
부제목X
***

## ##Header2

### ###Header3
부제목
===

#### ####Header4
##### #####Header5
부제목
---
###### ######Header6

# 갯수로 Header1~6 까지의 텍스트 헤더 정의 가능.
텍스트 뒤에 (URL링크) 를 붙여줌으로써 링크 추가 가능.
코드 아래에 ---, === 를 통해 구분선 추가 및 부제목 추가 가능 *** 의 경우 구분선은 추가되지만 부제목은 적용되지 않는다

[ 작동 코드 ]

🟨 HTML

<h1>헤더 1 <small>부제목X 같이 제목됨</small></h1>
<br>
<h1>h1</h1>
<h2>h2</h2>
<h3>h3</h3>
<h4>h4</h4>
<h1><a href="https://example.com">헤더 1</a></h1>

<h1></h1> 의 형식으로 헤더 지정
hred = 링크 URL 을 지정하고 <h1></h1>을 감싸서 헤더에 링크 적용

[ 작동코드 ]

이미지 추가하기

[ 이미지 URL 얻어오기 ]

Github Issues 탭에 새로운 이슈를 추가하고 이미지 파일을description 란에 드래그 앤 드롭 형태로 올릴 경우 이미지 URL을 얻을 수 있다.

🟪 Markdown

// 이미지 추가하기
![이미지 대체 텍스트](이미지URL)

// 이미지에 링크 추가하기
[![이미지 대체 텍스트](이미지URL)](링크URL)

마크다운 형식으로 이미지를 추가할 경우 코드창에서 이미지 크기를 별도로 조절할 수 없다.
간단하게 이미지 작성 가능

🟨 HTML

// 이미지 추가하기
<img src = "이미지 URL">

// 이미지 링크 추가하기
<a hred="링크URL">
   <img src = "이미지 URL" alt="대체 텍스트">
</a>

// 이미지 크기 조절하기
<img src="이미지 URL" alt="대체 텍스트" width="150" height="150">

// 이미지 주석 추가하기 ( 마우스 올릴 경우 설명 텍스트 )
<img src="이미지 URL" alt="대체 텍스트" title="링크 이동">

// 이미지 gravity 조정하기
<p align="위치">
  <img src="이미지 URL">
</p>

HTML형식의 img 태그로 이미지 추가 시 당연하게 src 는 필수 값이다.

[ HTML 이미지 선택 속성 ]

대체 텍스트
- alt="대체 텍스트" 형식으로 이미지가 존재하지 않을 경우 대체 텍스트가 나타나도록 할 수 있다.
이미지 크기 조정
- width, height 값은 px값과 % 값으로 지정해줄 수 있다.
이미지 마우스 커서 주석 추가
- title 속성 지정을 통해 마우스 올릴 경우 이미지 안내 주석을 추가할 수 있다.
이미지 정렬
- <p> ( paragraph ) 문단 태그를 사용하여 태그에 align 속성 center, left, right 값을 지정하고, 이미지를 태그 안에 넣어줌으로 정렬 방식을 지정해줄 수 있다.
이미지 좌, 우 마진주기
- 좌, 우 마진 <img src="이미지 URL" hspace="10px">
- 상, 하 마진 <img src="이미지 URL" vspace="10px">

테이블

🟪 Markdown

// case1
| title1 | title2 | title3 |
| --- | --- | --- |
| 1 | 2 | 3 |
| 4 | 5 | 6 |
| 7 | 8 | 9 |

// case2 error
| title1 | title2 | title3 |
| 1 | 2 | 3 |
| 4 | 5 | 6 |
| 7 | 8 | 9 |

| --- | 의 갯수만큼의 테이블 열을 갖는다 | --- | 가 없다면 정상적으로 테이블 생성 X

[ Markdown Table 속성 ]

테이블 정렬
- 왼쪽 정렬
  - :--- ( --- 좌측 콜론 )
- 가운데 정렬
  - :---: ( --- 양측 콜론 )
- 우측 정렬
  - ---: ( --- 우측 콜론 )

🟨 HTML

<table>
  <th>
    <th>title1</th>
    <th>title2</th>
    <th>title3</th>
  </th>
  <tr>
    <td>1</td>
    <td>2</td>
    <td>3</td>
  </tr>
  <tr>
    <td>4</td>
    <td>5</td>
    <td>6</td>
  </tr>
  <tr>
    <td>7</td>
    <td>8</td>
    <td>9</td>
  </tr>
</table>

table = 표를 나타내는 HTML 태그
tr ( table row ) = 테이블에서 행을 나타내는 태그
th ( table header ) = 헤더 칸을 나타내는 태그
- defult 설정 - 중앙 정렬, bold
td ( table data ) = 테이블내의 각각의 cell을 나타내는 태그
- default 설정 - 왼쪽 정렬

[ HTML Table 정렬 속성 ]

가로 정렬
- <th align="정렬 위치">
- 정렬 위치 = left, center, right
세로 정렬
- <th valign="정렬위치">
- 정렬 위치 = top, middle, bottom
tr, td에도 동일하게 적용 가능

[ HTML Table 병합하기 ]

가로 셀 병합
- <td colspan="병합할 셀의 수">
세로 셀 병합
- <td rowspan="병합할 셀의 수">
th, tr에도 동일하게 적용할 수 있으며 초과되는 것은 밀려난다

[ HTML Table 추가 속성 ]

테이블 외곽선
- <table border="2">
maxline 1줄로 제한
- <td nowrap>데이터</td>

[ 작성 예제 - Case 1 정렬 속성 ]

<table>
  <th>
    <th>title1</th>
    <th>title2</th>
    <th>title3</th>
  </th>
  <tr align="center">
    <td>순서</td>
    <td>1</td>
    <td>2</td>
    <td>3</td>
  </tr>
  <tr>
    <td>순서</td>
    <td>4</td>
    <td>5</td>
    <td>6</td>
  </tr>
  <tr align="right">
    <td>순서</td>
    <td>7</td>
    <td>8</td>
    <td>9</td>
  </tr>
</table>

[ 작성 예제 - Case 2 셀 병합 ]

<table>
  <th>
    <th colspan="2">title1</th>
    <th>title2</th>
    <th>title3</th>
  </th>
  <tr align="center">
    <td rowspan="3">순서</td>
    <td colspan="2" rowspan="2">1</td>
    <td>2</td>
    <td>3</td>
  </tr>
  <tr>
    <td>4</td>
    <td>5</td>
    <td>6</td>
  </tr>
  <tr align="right">
    <td>7</td>
    <td>8</td>
    <td>9</td>
  </tr>
</table>

[ 테이블 속성 예제 적용 모습 ]

[ A. 오늘 복습한 내용 / B. 다음에 학습할 내용 ]

A. 마크다운 작성 방법

B. CSS, HTML 등 웹 개발 시 필요한 지식들에 대해서도 학습 해봐야겠다.

B. 보안관련된 지식도 필요할 것 같다.

[오류,에러 등등]

1. Readme에 들어갈 이미지 리소스를 디렉토리에 넣다가 실수로 한글로 네이밍한 리소스를 집어넣게 되어서 오류가 발생했다. 본문에 해결방법 기재

2. Github 내부 에서 코드를 수정하는 방식으로 이미지 파일 삭제할때마다, 리드미를 수정할 때마다 커밋이 쌓인다. 불필요한 커밋이 쌓이게 되어버려서 개인 래파지토리에 먼저 적용하고 난 뒤에 프로젝트에 적용할 수 있도록 해야겠다.

3. Github Issues 를 통한 이미지 URL 을 가져오는 방법을 생각하지 못해서 프로젝트 래파지토리 코드내의 디렉토리를 만들고 이미지를 넣어주어서 파일 무게가 커지는 문제가 생겼다.

→ 해결방법 : Issues 탭을 통해 이미지 URL 가져오는 방법 사용하기

[느낀 점]

1. 무분별한 이모티콘 사용은 오히려 난잡한 디자인을 만드는 결과를 낳을 수 있다.

2. Facebook, Instagram 등 대형 프로젝트 Readme를 참고했는데 모두 최대한 간결하게 작성하도록 하는 편인 것 같다.

3. 리드미 작성 시 PNG, JPEG 이미지 포맷 형식의 파일을 사용하기 보단 SVG 파일을 사용하자. SVG 파일은 벡터로 되어 있어 이미지 크기가 조절되더라도 형태를 깔끔하게 유지할 수 있기 때문에 시각적으로 불편하지 않다.

[Reference]

// README.md 작성법

https://hulrud.tistory.com/3