Electron Documentation

June 4, 2015 · 7 min read

이번 주에 Electron 문서를 electronjs.org로 옮겼다. 최신 문서는 /docs/latest에서 확인할 수 있다. 이전 버전의 문서도 유지하므로, 사용 중인 버전에 해당하는 문서는 /docs/vX.XX.X에서 찾아볼 수 있다.

사용 가능한 문서 버전을 확인하려면 /docs를 방문하거나, 모든 최신 버전의 문서를 한 페이지에서 보려면 /docs/all로 이동하면 된다. cmd + f를 사용해 검색하기에 편리하다.

문서 내용에 기여하고 싶다면, Electron 저장소에서 작업할 수 있다. 문서는 여기에서 가져오며, 각 마이너 릴리스마다 가져와 Jekyll로 만들어진 Electron 사이트 저장소에 추가한다.

문서를 한 저장소에서 다른 저장소로 가져오는 방법에 대해 더 알고 싶다면 아래를 계속 읽어보자. 그렇지 않으면 문서를 즐기길 바란다!

기술적 세부 사항

우리는 Electron 코어 저장소 내의 문서를 그대로 보존한다. 이는 electron/electron이 항상 최신 버전의 문서를 갖고 있음을 의미한다. 새로운 Electron 버전이 출시되면, 해당 문서를 Electron 웹사이트 저장소인 electron/electronjs.org로 복제한다.

문서를 가져오기 위해 script/docs vX.XX.X 커맨드라인 인터페이스를 사용해 스크립트를 실행한다. 이때 --latest 옵션을 포함할지 여부는 가져오는 버전이 최신 버전인지에 따라 결정된다. 문서를 가져오는 스크립트는 몇 가지 흥미로운 Node 모듈을 사용한다:

nugget: 릴리스 tarball을 가져와 임시 디렉토리에 저장한다.
gunzip-maybe: tarball을 압축 해제한다.
tar-fs: tarball에서 /docs 디렉토리만 스트리밍하고, 파일을 필터링 및 처리한다. 이 과정에서 through2를 사용해 Jekyll 사이트와 잘 동작하도록 조정한다.

테스트는 모든 부분이 예상대로 동작하는지 확인하는 데 도움을 준다.

Jekyll

Electron 웹사이트는 Jekyll로 구축되어 있으며, 문서화를 위해 컬렉션(Collections) 기능을 활용한다. 이 구조는 다음과 같다:

electron.atom.io
└── _docs
    ├── latest
    ├── v0.27.0
    ├── v0.26.0
    ├── so on
    └── so forth

Front matter

Jekyll이 각 페이지를 렌더링하려면 최소한 빈 front matter가 필요하다. 우리는 모든 페이지에서 front matter를 활용할 것이므로, /docs 디렉토리를 스트리밍하는 동안 파일이 README.md인지 확인한다. README.md 파일인 경우 하나의 front matter 설정을 받고, 마크다운 확장자를 가진 다른 파일인 경우 약간 다른 front matter를 받는다.

각 페이지는 다음과 같은 front matter 변수 세트를 받는다:

---
version: v0.27.0
category: Tutorial
title: 'Quick Start'
source_url: 'https://github.com/electron/electron/blob/master/docs/tutorial/quick-start.md'
---

README.md는 추가적으로 permalink를 받아 URL이 /readme/와 같은 어색한 형태가 아닌 index.html이라는 공통 루트를 가지도록 한다.

permalink: /docs/v0.27.0/index.html

설정과 리다이렉트

사이트의 _config.yml 파일에서는 문서를 가져올 때 --latest 플래그를 사용할 때마다 latest_version 변수가 설정된다. 또한 사이트에 추가된 모든 버전 목록과 전체 문서 컬렉션에 대해 원하는 고정 링크도 함께 추가한다.

latest_version: v0.27.0
available_versions:
  - v0.27.0
collections:
  docs: { output: true, permalink: '/docs/:path/' }

사이트 루트에 있는 latest.md 파일은 이 프런트 매터만 포함하고 있으며, 이를 통해 사용자는 특정 최신 버전 번호를 사용하지 않고도 electron.atom.io/docs/latest URL을 방문해 최신 버전 문서의 인덱스(즉, README)를 볼 수 있다(물론 최신 버전 번호를 직접 사용해도 된다).

---
permalink: /docs/latest/
redirect_to: /docs/{{ site.data.releases[0].version }}
---

레이아웃

docs.html 레이아웃 템플릿에서는 조건문을 사용해 헤더와 브레드크럼브에 정보를 표시하거나 숨긴다.

{% raw %} {% if page.category != 'ignore' %}
<h6 class="docs-breadcrumb">
  {{ page.version }} / {{ page.category }} {% if page.title != 'README' %} / {{
  page.title }} {% endif %}
</h6>
{% endif %} {% endraw %}

사용 가능한 버전을 보여주는 페이지를 만들려면 사이트 루트에 있는 versions.md 파일에서 설정 파일의 리스트를 순회한다. 이 페이지에는 /docs/라는 고정 링크를 부여한다.

{% raw %} {% for version in site.available_versions %} - [{{ version
}}](/docs/{{ version }}) {% endfor %} {% endraw %}

이 기술적인 내용이 흥미로웠기를 바란다! Jekyll을 사용해 문서 사이트를 만드는 방법에 대해 더 알고 싶다면, GitHub의 문서 팀이 Jekyll로 GitHub 문서를 게시하는 방법을 확인해 보자.

기술적 세부 사항​

Jekyll​

Front matter​

설정과 리다이렉트​

레이아웃​

기술적 세부 사항

Jekyll

Front matter

설정과 리다이렉트

레이아웃