Skip to content

Commit 7021ced

Browse files
haksungjangclaude
haksungjang
and
claude
committed
docs: migrate wiki pages to docs/ folder structure
- Add docs/README.md as table of contents with mermaid diagram - docs/dev/: setup.md, local-server.md (hugo.toml path updated) - docs/contribute/: meeting.md, subgroup.md, blog.md, index-page.md, english-page.md, file-attachment.md - docs/workflow/: git-workflow.md (added mermaid flowchart) - docs/admin/: review-test.md (added mermaid flowchart), deployment.md - meeting.md: replace cp-based workflow with archetype template method; add "새 미팅 페이지 생성 방법" section - file-attachment.md: add GitHub Releases upload rules section - english-page.md: add mermaid content structure diagram - CONTRIBUTING.md: replace all wiki links with docs/ relative paths Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
1 parent 716249a commit 7021ced

13 files changed

Lines changed: 781 additions & 6 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -10,8 +10,8 @@ OpenChain KWG는 [Hugo](https://gohugo.io/) static site generator의 Theme인 [D
1010

1111
이 웹사이트를 지속적으로 관리하고 개선하는 데 기여하실 수 있습니다. 웹사이트 개발은 [GitHub](https://github.com/OpenChain-Project/OpenChain-KWG)에서 하며, 빌드, 배포 및 Pull Request 방법은 다음 페이지를 참고하세요.
1212

13-
* [로컬에서 웹사이트 구동하기](https://github.com/OpenChain-Project/OpenChain-KWG/wiki/%EB%A1%9C%EC%BB%AC%EC%97%90%EC%84%9C-%EC%9B%B9%EC%82%AC%EC%9D%B4%ED%8A%B8-%EA%B5%AC%EB%8F%99%ED%95%98%EA%B8%B0)
14-
* [Git Workflow](https://github.com/OpenChain-Project/OpenChain-KWG/wiki/Git-Workflow)
13+
* [로컬에서 웹사이트 구동하기](docs/dev/local-server.md)
14+
* [Git Workflow](docs/workflow/git-workflow.md)
1515

1616

1717
## 웹사이트 자료 추가
@@ -21,7 +21,7 @@ OpenChain KWG의 모든 활동은 누구나 열람하고 사용할 수 있도록
2121
이 웹사이트에는 주기적으로 생성되는 다음과 같은 자료를 추가하고 있습니다.
2222

2323
* [Resource](https://openchain-project.github.io/OpenChain-KWG/resource/) : OpenChain KWG에서 번역/생성한 자료 공개
24-
* [Meeting](https://openchain-project.github.io/OpenChain-KWG/meeting/) : OpenChain KWG 정기 모임 공지, 발표자료, 참석자, 회의록 등 자료 공개 (작성 방법 : [Meeting 내용 작성하기](https://github.com/OpenChain-Project/OpenChain-KWG/wiki/Meeting-%EB%82%B4%EC%9A%A9-%EC%9E%91%EC%84%B1%ED%95%98%EA%B8%B0))
24+
* [Meeting](https://openchain-project.github.io/OpenChain-KWG/meeting/) : OpenChain KWG 정기 모임 공지, 발표자료, 참석자, 회의록 등 자료 공개 (작성 방법 : [Meeting 내용 작성하기](docs/contribute/meeting.md))
2525

2626
### 새 미팅 페이지 생성 방법
2727

@@ -72,12 +72,12 @@ git push origin master
7272
> 주의: `static/` 또는 `content/` 폴더에 PDF, PPTX 등 대용량 파일을
7373
> 직접 커밋하지 마세요. GitHub Pages 1GB 용량 한도를 초과할 수 있습니다.
7474
75-
* [Subgroup](https://openchain-project.github.io/OpenChain-KWG/subgroup/) : OpenChain KWG Subgroup의 활동 자료 공개 (작성 방법 : [Subgroup 내용 작성하기](https://github.com/OpenChain-Project/OpenChain-KWG/wiki/Subgroup-%EB%82%B4%EC%9A%A9-%EC%9E%91%EC%84%B1%ED%95%98%EA%B8%B0))
76-
* [Blog](https://openchain-project.github.io/OpenChain-KWG/blog/) : OpenChain KWG 멤버가 작성하는 뉴스, 기술블로그 공개 (작성 방법 : [Blog 작성하기](https://github.com/OpenChain-Project/OpenChain-KWG/wiki/Blog-%EC%9E%91%EC%84%B1%ED%95%98%EA%B8%B0))
75+
* [Subgroup](https://openchain-project.github.io/OpenChain-KWG/subgroup/) : OpenChain KWG Subgroup의 활동 자료 공개 (작성 방법 : [Subgroup 내용 작성하기](docs/contribute/subgroup.md))
76+
* [Blog](https://openchain-project.github.io/OpenChain-KWG/blog/) : OpenChain KWG 멤버가 작성하는 뉴스, 기술블로그 공개 (작성 방법 : [Blog 작성하기](docs/contribute/blog.md))
7777

7878
이러한 자료를 추가하는 데 기여하실 분을 모십니다. 자료를 추가하는 방법은 다음 페이지를 참고하세요!
7979

80-
* [OpenChain KWG wiki](https://github.com/OpenChain-Project/OpenChain-KWG/wiki)
80+
* [OpenChain KWG 문서 (docs/)](docs/README.md)
8181

8282
## 오픈소스 문서 번역
8383

‎docs/README.md‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
# OpenChain KWG 문서 (docs/)
2+
3+
OpenChain KWG 웹사이트 개발 및 기여에 관한 문서 모음입니다.
4+
5+
```mermaid
6+
graph TD
7+
docs --> dev[dev/ — 개발 환경]
8+
docs --> contribute[contribute/ — 콘텐츠 기여]
9+
docs --> workflow[workflow/ — Git 워크플로우]
10+
docs --> admin[admin/ — 관리자 가이드]
11+
```
12+
13+
---
14+
15+
## 개발 환경 (dev/)
16+
17+
| 문서 | 설명 |
18+
|------|------|
19+
| [개발 환경 구축하기](dev/setup.md) | Hugo, NodeJS 설치 및 환경 구성 |
20+
| [로컬에서 웹사이트 구동하기](dev/local-server.md) | PostCSS 설치, 빌드, 로컬 서버 실행 |
21+
22+
---
23+
24+
## 콘텐츠 기여 (contribute/)
25+
26+
| 문서 | 설명 |
27+
|------|------|
28+
| [Meeting 내용 작성하기](contribute/meeting.md) | 정기 미팅 페이지 생성 및 수정 방법 (Archetype 포함) |
29+
| [Subgroup 내용 작성하기](contribute/subgroup.md) | Subgroup 활동 페이지 추가/수정 방법 |
30+
| [Blog 작성하기](contribute/blog.md) | 뉴스/기술 블로그 작성 방법 |
31+
| [Index 페이지 헤더 영역 작성하기](contribute/index-page.md) | `_index.md` Front Matter 작성 가이드 |
32+
| [영문 페이지 작성](contribute/english-page.md) | `/ko` ↔ `/en` 다국어 페이지 반영 방법 |
33+
| [파일 첨부와 그림 보여주기](contribute/file-attachment.md) | 이미지 삽입, 대용량 파일 GitHub Releases 업로드 규칙 |
34+
35+
---
36+
37+
## Git 워크플로우 (workflow/)
38+
39+
| 문서 | 설명 |
40+
|------|------|
41+
| [Git Workflow](workflow/git-workflow.md) | Fork → Clone → Branch → PR 전체 흐름 |
42+
43+
---
44+
45+
## 관리자 가이드 (admin/)
46+
47+
| 문서 | 설명 |
48+
|------|------|
49+
| [Review와 Test 절차](admin/review-test.md) | PR Review, 로컬 Test 방법 |
50+
| [수정 사항 반영 및 Deployment](admin/deployment.md) | master branch 반영 및 GitHub Pages 배포 |
51+
52+
---
53+
54+
## 빠른 시작
55+
56+
처음 기여하시는 분은 아래 순서를 따르세요.
57+
58+
1. [개발 환경 구축하기](dev/setup.md) — Hugo, NodeJS 설치
59+
2. [Git Workflow](workflow/git-workflow.md) — Fork & Clone (Step 1~4)
60+
3. [로컬에서 웹사이트 구동하기](dev/local-server.md) — 빌드 및 로컬 확인
61+
4. 콘텐츠 추가/수정 (위 contribute/ 문서 참고)
62+
5. [Git Workflow](workflow/git-workflow.md) — Commit & Pull Request (Step 5~7)

‎docs/admin/deployment.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# 수정 사항 반영 및 Deployment
2+
3+
develop branch의 수정 사항에 대한 [Review와 Test](review-test.md)가 완료되었으면 이를 master branch에 반영하고 deploy합니다.
4+
5+
## Master branch로 수정사항 Merge
6+
7+
먼저 origin이 OpenChain-Project repository임을 확인합니다.
8+
9+
```bash
10+
$ git remote -v
11+
origin https://github.com/OpenChain-Project/OpenChain-KWG.git (fetch)
12+
origin https://github.com/OpenChain-Project/OpenChain-KWG.git (push)
13+
```
14+
15+
master branch로 checkout하고 origin/master를 pull합니다.
16+
17+
```bash
18+
$ git checkout master
19+
$ git pull origin master
20+
```
21+
22+
그 상태에서 origin/develop을 master branch에 merge하고, origin remote에 push합니다.
23+
24+
```bash
25+
$ git merge origin/develop
26+
$ git push origin master
27+
```
28+
29+
## Deployment
30+
31+
OpenChain KWG 웹사이트는 GitHub Actions를 통해 master branch에 push되면 자동으로 GitHub Pages에 배포됩니다.
32+
33+
수동 배포가 필요한 경우 아래 스크립트를 사용할 수 있습니다.
34+
35+
```bash
36+
$ ./publish_to_ghpages.sh
37+
```
38+
39+
이 스크립트는 gh-pages branch에 빌드 결과물을 push하여 웹사이트 deploy를 완료합니다.

‎docs/admin/review-test.md‎

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
# Review와 Test 절차 및 방법
2+
3+
관리자는 Pull Request가 들어오면 다음 절차로 Review와 Test를 수행한다.
4+
5+
```mermaid
6+
flowchart TD
7+
A([Pull Request 수신]) --> B[develop branch로 들어왔는지 확인]
8+
B --> C[Code Review]
9+
C -- 문제 없음 --> D[develop branch에 Merge]
10+
C -- 문제 발견 --> E[기여자에게 수정 요청]
11+
E --> C
12+
D --> F[로컬 develop branch로 fetch & rebase]
13+
F --> G[hugo serve로 로컬 확인]
14+
G -- 정상 동작 --> H([master branch 반영 → Deployment])
15+
G -- 문제 발견 --> E
16+
```
17+
18+
## Review
19+
20+
1. Pull Request가 develop branch로 들어왔는지 확인한다.
21+
2. Code 레벨로 검토 후 문제가 발견되지 않았다면 develop branch에 Merge한다. 특별한 문제가 있을 경우, 기여자에게 수정을 요청하여 보완하는 과정을 거친다.
22+
23+
## Test
24+
25+
Pull Request를 Merge한 최신의 develop branch를 로컬의 develop branch로 fetch & rebase한다.
26+
27+
```bash
28+
$ git checkout develop
29+
$ git fetch
30+
$ git rebase origin/develop
31+
```
32+
33+
로컬의 develop branch에서 **hugo serve**하여 Pull Request 수정 사항이 정상적으로 동작하는지 확인한다. : http://localhost:1313/OpenChain-KWG/
34+
35+
(국문과 영문을 함께 확인한다.)
36+
37+
## 다음 단계
38+
39+
Review와 Test가 완료되면 → [수정 사항 반영 및 Deployment](deployment.md)

‎docs/contribute/blog.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Blog 작성하기
2+
3+
OpenChain KWG 웹사이트 > 메뉴 > **Blog** 에는 OpenChain 뉴스 및 Tech Blog를 작성할 수 있습니다. 아래 절차를 참고하세요.
4+
5+
## 소스 코드 다운로드
6+
7+
다음 안내에 따라 로컬 PC에 OpenChain KWG 웹사이트의 소스 코드를 다운로드합니다. : [Git Workflow](../workflow/git-workflow.md)
8+
9+
## Blog 코드 위치
10+
11+
[blog](https://github.com/OpenChain-Project/OpenChain-KWG/tree/master/content/ko/blog) 내용에 대한 코드는 다음 디렉토리에 위치합니다.
12+
13+
```
14+
$ cd content/ko/blog/
15+
$ ls
16+
_index.md 2020 2021 sample
17+
```
18+
19+
여기에는 하나의 `_index.md` 파일과 연도별 디렉토리가 있습니다.
20+
21+
## Blog 작성하기
22+
23+
작성일에 해당하는 연도 디렉토리(예: `/2021`) 하위에 작성할 블로그를 위한 디렉토리를 생성합니다. 쉽게하려면 `/sample/sample-post` 디렉토리를 복사해서 사용하세요.
24+
25+
```bash
26+
$ cd blog/2021/
27+
$ cp -R ../sample/sample-post/ ./2021-01-15-title
28+
```
29+
30+
생성한 디렉토리 내에는 기본적으로 `index.md` 파일이 있어야 합니다. 그리고, 블로그 작성에 필요한 이미지 파일 등을 위치시킵니다.
31+
32+
`index.md` 파일은 Markdown 형태이며 상단의 헤더 영역과 본문 영역으로 구분됩니다.
33+
34+
헤더 영역 작성은 다음 페이지를 참고하세요. : [Index 페이지 헤더 영역 (Blog)](index-page.md#index-페이지-헤더-영역-blog)
35+
36+
그리고, 블로그 본문을 Markdown 문법에 맞추어 작성합니다. 필요에 따라 파일과 그림을 첨부합니다.
37+
38+
* [파일 첨부와 그림 보여주기](file-attachment.md)
39+
40+
## 수정 사항 확인하기
41+
42+
[로컬에서 웹사이트 구동하기](../dev/local-server.md)를 해보면 수정 사항이 정상적으로 동작하는지 확인할 수 있습니다.
43+
44+
(개발환경 구성이 수월하지 않은 경우, 수정 사항 확인하는 부분은 생략하세요.)
45+
46+
## 영문 페이지 반영하기
47+
48+
국문 페이지 내용 작성을 완료하였으면 다음 안내에 따라 이를 영문 페이지에도 반영하세요. : [영문 페이지 작성](english-page.md)
49+
50+
(영문 페이지에 반영할 필요가 없는 내용일 경우, `영문 페이지 반영하기`는 스킵합니다.)
51+
52+
## 수정 사항 반영 요청하기
53+
54+
추가 / 수정을 완료하면 Pull Request하여 반영을 요청합니다. OpenChain KWG 관리자가 Review 후 Merge / Deploy합니다.
55+
56+
Pull Request는 [Git Workflow](../workflow/git-workflow.md)를 참고하여 [Step 5](../workflow/git-workflow.md#step-5-commit) ~ [Step 7](../workflow/git-workflow.md#step-7-create-a-pull-request)을 수행하세요.

‎docs/contribute/english-page.md‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
# 웹사이트 영문 페이지 작성
2+
3+
OpenChain KWG 웹사이트는 국문을 기본으로 하고, 영문도 지원합니다.
4+
5+
웹사이트 상단 메뉴의 Korea / English 버튼을 눌러서 원하는 언어를 선택할 수 있습니다.
6+
7+
소스 코드를 [다운로드](../workflow/git-workflow.md)하여 국문 페이지에 내용을 추가/수정하였으면 아래 안내에 따라 영문 페이지에도 이를 반영하세요.
8+
9+
## 영문 페이지 작성 방법
10+
11+
소스 코드의 [`/content`](https://github.com/OpenChain-Project/OpenChain-KWG/tree/master/content) 디렉토리에는 [`/en`](https://github.com/OpenChain-Project/OpenChain-KWG/tree/master/content/en)와 [`/ko`](https://github.com/OpenChain-Project/OpenChain-KWG/tree/master/content/ko)이 존재합니다.
12+
13+
```
14+
$ ls ./content
15+
en ko
16+
```
17+
18+
`/en`과 `/ko`를 비교해보면 동일한 구조의 디렉토리를 갖고 있으며, 텍스트 파일 내 텍스트만 각각 영문/국문으로 되어 있습니다.
19+
20+
즉, 국문 작성을 위해 `/ko` 디렉토리 하위에 추가/수정한 파일을 동일하게 `/en` 디렉토리 하위에도 적용하세요. 이때, `_index.md` 파일 등 텍스트 파일 내 국문 텍스트만 영문으로 수정하면 됩니다.
21+
22+
## 디렉토리 구조 참고
23+
24+
```mermaid
25+
graph LR
26+
content --> ko
27+
content --> en
28+
ko --> ko_meeting[meeting/]
29+
ko --> ko_subgroup[subgroup/]
30+
ko --> ko_blog[blog/]
31+
en --> en_meeting[meeting/]
32+
en --> en_subgroup[subgroup/]
33+
en --> en_blog[blog/]
34+
```
35+
36+
`/ko`에서 추가한 파일과 동일한 경로를 `/en` 하위에 생성하고, 텍스트만 영문으로 작성하면 됩니다.

‎docs/contribute/file-attachment.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# 파일 첨부와 그림 보여주기
2+
3+
## 대용량 파일 업로드 규칙 (GitHub Releases)
4+
5+
> **중요:** PDF, PPTX 등 대용량 파일은 `static/` 또는 `content/` 폴더에 직접 커밋하지 마세요.
6+
> GitHub Pages 1GB 용량 한도를 초과할 수 있습니다.
7+
> 반드시 **GitHub Releases**에 업로드한 뒤 절대 경로 URL로 링크하세요.
8+
9+
- GitHub Releases 접속:
10+
https://github.com/OpenChain-Project/OpenChain-KWG/releases
11+
- 해당 연도의 Release 태그 선택 (예: `meeting-slides-2026`)
12+
태그가 없으면 새로 생성:
13+
- Tag: `meeting-slides-YYYY`
14+
- Title: `Meeting Slides YYYY`
15+
- 파일명 규칙 준수 후 업로드:
16+
- 영문, 숫자, 하이픈(`-`), 언더스코어(`_`), 점(`.`)만 사용
17+
- 공백·한글·특수문자 사용 금지
18+
- 권장 형식: `YYYYMMDD-발표자-주제키워드.pdf`
19+
- 예시: `20260320-kakao-sbom-intro.pdf`
20+
- 업로드 후 다운로드 URL 복사:
21+
`https://github.com/OpenChain-Project/OpenChain-KWG/releases/download/meeting-slides-YYYY/파일명.pdf`
22+
23+
마크다운에서 링크하는 방법:
24+
25+
```markdown
26+
<!-- 올바른 방식 -->
27+
[발표자료](https://github.com/OpenChain-Project/OpenChain-KWG/releases/download/meeting-slides-YYYY/파일명.pdf)
28+
29+
<!-- 금지 -->
30+
[발표자료](/slides/파일명.pdf)
31+
```
32+
33+
---
34+
35+
## 파일 첨부 (소용량 파일)
36+
37+
소용량 파일(이미지 등)은 첨부할 `_index.md`가 위치한 디렉토리(예: `/content/ko/meeting/6th`) 내에 위치시키세요.
38+
39+
그리고, `_index.md`에서 아래 예와 같이 첨부파일 다운로드 링크를 추가하면 됩니다.
40+
41+
```markdown
42+
* [OpenChainKWG_6th_20200616.pdf](OpenChainKWG_6th_20200616.pdf)
43+
```
44+
45+
## 이미지 보여주기
46+
47+
먼저 이미지 파일을 이미지를 보여줄 `_index.md`가 위치한 디렉토리(예: `/content/ko/meeting/6th`) 내에 위치시키세요.
48+
49+
이미지 파일은 주로 다음 세가지 방식으로 보여줄 수 있습니다.
50+
51+
### Markdown 형태로 보여주기
52+
53+
다음과 같이 Markdown 방식으로 보여줄 수 있습니다. 이 경우 화면에 가득차게 보여집니다.
54+
55+
```markdown
56+
![OpenChain_KWG_6th_2.png](OpenChain_KWG_6th_2.png)
57+
```
58+
59+
### html tag 사용하여 보여주기
60+
61+
html tag를 사용하여 사이즈를 조절하며 보여줄 수 있습니다.
62+
63+
```html
64+
<!-- 폭의 90%만 채워서 보여주기 -->
65+
<div><span class="image fit">
66+
<img src="OpenChain_6th.jpg" width="90%">
67+
</span></div>
68+
69+
<!-- 세개의 그림을 폭의 1/3씩 채워서 한 줄로 보여주기 -->
70+
<div><span class="image fit">
71+
<img src="OpenChain_6th.jpg" width="30%">
72+
<img src="OpenChain_KWG_6th_1.png" width="30%">
73+
<img src="OpenChain_KWG_6th_2.png" width="30%">
74+
</span></div>
75+
```
76+
77+
### hugo의 Image Processing 기능을 사용하여 보여주기
78+
79+
hugo의 [imgproc shortcode](https://www.docsy.dev/docs/adding-content/shortcodes/#imgproc)를 이용하여 이미지 사이즈 수정, 출처/라이선스 표시 등을 할 수 있습니다.
80+
81+
먼저 Index 페이지 파일(예: `_index.md`)의 헤더 영역에 아래와 같이 이미지 파일을 resources에 추가합니다.
82+
83+
```yaml
84+
resources:
85+
- src: "guide.png"
86+
params:
87+
byline: "Photo: OpenChain Korea Work Group / CC-BY-SA"
88+
```
89+
90+
* **src** : 이미지 파일 이름을 작성합니다. 여러개의 파일인 경우, `"**.{png,jpg}"` 와 같이 표시할 수 있습니다.
91+
* **byline** : 이미지 파일 하단에 보여질 출처 및 라이선스를 작성합니다.
92+
93+
그리고, Index 페이지 파일 본문 내 이미지 파일을 보여주어야 할 부분에 아래와 같이 작성하여 이미지를 보여주세요.
94+
95+
```
96+
{{< imgproc guide Fit "900x600" >}}
97+
기업 공개SW 거버넌스 OpenChain 2.0 해설 (여기에 이미지 설명을 작성하면 이미지 하단에 함께 보여집니다.)
98+
{{< /imgproc >}}
99+
```
100+
101+
가이드 페이지에서 보여지는 이미지를 참고하세요. : [Guide](https://openchain-project.github.io/OpenChain-KWG/guide/)

0 commit comments

Comments
 (0)