문체#

n8n은 Microsoft Writing Style Guide를 사용합니다. 이 페이지에서는 n8n 문서에서 가장 중요한 요소를 강조하고, 여기에 자체 스타일 선택 사항을 추가로 설명합니다.

쉬운 언어#

• 문서화하는 프로세스의 각 단계를 명확하게 설명합니다.
• 현재 시제를 사용합니다.
• 글은 최대한 간결하게 유지합니다. 이를 돕는 무료 브라우저 앱 두 가지가 있습니다:
  • Hemingway는 언어의 복잡도를 측정합니다. 목표로 삼을 학년 수준에 대한 고정된 규칙은 없지만, 읽기 학년 수준이 낮을수록 좋습니다.
  • Lexi는 Markdown 텍스트의 작성 복잡도를 측정하며, 여러 지표를 결합해 하나의 가독성 점수를 산출합니다. 이상적인 통합 가독성 점수인 60점을 최소 기준으로 여겨야 하며, 대부분의 페이지는 이보다 높은 점수를 받아야 합니다.

다음과 같은 흔한 패턴에 주의하고, 더 쉬운 표현을 사용합니다:

몇 가지 기본 원칙:

• 불필요한 말을 덜어냅니다. "It's important to note that"나 "Simply" 같은 도입부 표현을 없앱니다.
• 마케팅성 언어를 피합니다. "powerful", "robust", "seamless" 같은 표현을 쓰지 않습니다. 기능이 실제로 무엇을 하는지를 서술합니다.
• 모호한 수식어를 없앱니다. "very", "quite", "several" 같은 표현 대신 구체적인 수치를 제시합니다.
• 문장을 짧게 유지합니다. 30단어 미만으로, 한 문장에 한 가지 개념만 담습니다. 세미콜론이나 두 번째 "and"로 이어진 문장은 나눕니다.
• "There is" 대신 행동을 먼저 제시합니다. "There is a node that can schedule workflows"가 아니라 "To schedule a workflow, add a Schedule Trigger"처럼 씁니다.

어조와 인칭#

독자에게 직접 말하듯이 씁니다.

• 능동태를 사용합니다. "the request is sent by n8n"이 아니라 "n8n sends the request"라고 씁니다.
• 독자를 "you"로 지칭합니다. "Users can add a node"가 아니라 "You can add a node"라고 씁니다.
• 1인칭을 피합니다. "I", "we", "our" 대신 n8n을 주어로 씁니다. "we recommend"가 아니라 "n8n recommends"라고 씁니다.
• 축약형을 사용합니다. "do not", "you will" 대신 "Don't", "you'll"을 씁니다.

포용적 언어#

모두를 위해 씁니다.

• 성별을 알 수 없는 사람에게는 "they"를 사용합니다. "his settings"가 아니라 "Every user can configure their settings"라고 씁니다.
• 성 중립적인 용어를 선택합니다. "chairman"이 아니라 "Chair", "master"가 아니라 "Main"을 씁니다.

텍스트 서식#

• 제목: 문장체(sentence case)로 작성합니다 (자세히 보기).
• UI 요소: 볼드체로 표기합니다 (자세히 보기).
• 사용자 입력값: 코드 서식을 사용합니다. 자리표시자는 꺾쇠괄호 안에 하이픈으로 연결한 단어로 표기합니다. 예: <your-root-directory>.
• 파일 이름, 디렉터리 이름, 경로: 코드 서식을 사용합니다.
• 브랜드명은 정확히 표기해야 합니다. 예: "Github"가 아니라 "GitHub".

숫자, 날짜, 시간#

0부터 9까지는 글자로 쓰고, 10 이상은 숫자로 씁니다.

명백한 예외:

• 소수: 10 미만이더라도 항상 숫자로 씁니다 (예: three point five가 아니라 3.5).
• 백분율: 숫자로 씁니다 (예: five percent가 아니라 5%).
• 버전 및 기타 기술 문자열: 숫자로 씁니다 (예: n8n 2.1, step 3).
• 측정 단위: 숫자로 씁니다 (예: 5px, 3MB).

날짜와 시간

• 월을 풀어서 쓰고 서수를 사용하지 않습니다: "31/07/2016"이나 "July 31st"가 아니라 "July 31, 2016"으로 씁니다.
• "AM"/"PM" 앞에 공백을 둡니다: "9am"이 아니라 "9 AM"으로 씁니다.

범위

• 문장에서는 "from X to Y" 또는 "X through Y"를 사용합니다: "from 5 to 10 nodes".
• 표나 라벨에서 숫자 범위를 표기할 때는 하이픈이 아니라 엔대시(–)를 사용합니다: "5–10".
• 시간 범위에는 "to"를 사용합니다: "9 AM–5 PM"이 아니라 "9 AM to 5 PM"으로 씁니다.

자세히 보기

구두점과 띄어쓰기#

• 문장 사이에는 공백을 하나만 둡니다. 두 개를 두지 않습니다.
• 구두점은 따옴표 안쪽에 둡니다. "Select Save"가 아니라 "Select Save,"로 씁니다.
• 옥스퍼드 콤마를 사용합니다. "triggers, nodes, and credentials".
• 엠대시(—)를 피합니다. 쉼표나 새 문장을 사용합니다. "Add a node — then save"가 아니라 "Add a node, then save"로 씁니다.
• 말줄임표(…)를 피합니다. "Configure the settings..."가 아니라 "Configure the settings, then continue"로 씁니다.

Vale 린팅#

n8n은 문서를 린팅하기 위해 Vale를 사용합니다. 린팅은 이 가이드에서 정의한 규칙을 강제하고 작성 품질을 뒷받침합니다.

설정은 다음으로 구성됩니다:

• 리포지터리 루트에 있는 .vale.ini 파일로, 설정을 담고 있습니다.
• 스타일 정의를 담은 styles 디렉터리. 여기에는 기성 스타일 라이브러리와 n8n 전용 스타일이 포함됩니다.
• GitHub Action. PR이 열리거나 수정될 때 Vale를 실행하고, 위반 사항을 PR에 직접 보고합니다.

다음과 같이 로컬 머신에서 Vale를 실행할 수 있습니다:

1. Vale 문서를 따라 Vale CLI를 설치합니다.
2. 명령줄에서 린팅하거나 텍스트 편집기 플러그인을 설치하는 방법 중 선택합니다:
   1. vale docs/를 실행하면 docs 디렉터리의 모든 Markdown 파일을 린팅합니다.
   2. 또는 플러그인을 설치해 텍스트 편집기에서 자동으로 문제를 확인할 수 있습니다. VS Code를 사용한다면 ChrisChinchilla가 만든 vale-vscode를 설치하세요.

프론트매터#

Frontmatter는 페이지 상단에 위치하며 유효한 YAML이어야 합니다. n8n 문서는 다음 frontmatter 필드를 사용합니다:

• description: 페이지 콘텐츠를 간략히 요약한 내용입니다. n8n은 검색 결과와 링크 미리보기에 이 값을 표시할 수 있습니다.
• hidden: true로 설정하면 사이트의 사이드 메뉴에서 페이지가 제거됩니다. 페이지가 메뉴에 표시되어야 한다면(대부분의 페이지가 해당) 이 필드를 생략합니다.
• layout.description.visible: false로 설정하면 렌더링된 페이지에서 frontmatter description이 숨겨집니다. 항상 이 필드를 포함하고 false로 설정합니다.
• generated: true로 설정하면 해당 페이지가 자동화로 전적으로 관리됨을 표시합니다. 이러한 페이지는 수동으로 수정하지 않습니다.

Frontmatter 예시:

---
description: Learn how to merge data streams in your n8n workflows.
layout:
  description:
    visible: false
---

페이지 내비게이션#

각 space에는 루트에 SUMMARY.md 파일이 있으며, 이 파일이 사이드바를 정의합니다: 어떤 페이지가 표시되는지, 어떤 순서로 표시되는지, 어떻게 중첩되는지를 결정합니다. GitBook은 이 파일을 기반으로 내비게이션을 빌드하므로, SUMMARY.md에 추가하기 전까지 새 페이지는 사이드바에 나타나지 않습니다. .md 파일을 만드는 것만으로는 충분하지 않습니다.

SUMMARY.md는 중첩된 Markdown 목록입니다. 각 항목은 space 루트(즉 SUMMARY.md가 있는 폴더)를 기준으로 한 상대 경로로 페이지를 링크하며, .md 확장자를 포함합니다. README.md는 space나 섹션의 랜딩 페이지이며, 들여쓰기를 통해 그 아래에 페이지를 중첩시킵니다:

# Summary

* [Administer](README.md)
* [Manage credentials](manage-credentials/README.md)
  * [Share credentials securely](manage-credentials/share-credentials-securely.md)
  * [Credential overwrites](manage-credentials/credential-overwrites.md)

페이지를 추가할 때:

• 원하는 위치에 해당 SUMMARY.md에 한 줄을 추가합니다.
• 링크 텍스트로 페이지 제목을 사용합니다. 페이지의 heading과 정확히 일치할 필요는 없지만, 최대한 비슷하게 유지합니다.
• 상위 섹션 아래에 들여써서 중첩시킵니다. 항목의 순서가 사이드바의 순서를 결정합니다.

페이지를 이동하거나, 이름을 바꾸거나, 삭제할 때는 해당 SUMMARY.md 항목도 그에 맞게 갱신합니다.

Markdown과 GitBook 블록#

이 사이트는 GitBook으로 생성됩니다. 페이지는 Markdown에, 콜아웃(callout), 탭, 구조화된 페이지 요소 같은 GitBook 전용 컴포넌트를 더해 작성됩니다. GitBook은 이러한 컴포넌트를 **블록(block)**이라 부르며, 아래 섹션에서는 가장 자주 사용하는 블록을 다룹니다.

제목#

제목은 일반 Markdown(## 제목 텍스트)으로 문장체(sentence case)로 작성합니다. GitBook은 제목 텍스트로부터 자동으로 클릭 가능한 앵커를 생성하므로, 직접 앵커 마크업을 추가할 필요는 없습니다.

기존 페이지에서는 다음과 같은 명시적 앵커 태그를 볼 수 있습니다:

## Heading text

이는 안정적인 앵커를 고정하기 위한 것으로, 이후 제목 텍스트가 바뀌더라도 해당 제목으로의 링크가 계속 동작하도록 합니다. 새 제목에 반드시 추가할 필요는 없지만, 기존 앵커는 그대로 두어야 합니다. 이미 앵커가 있는 제목의 문구를 바꾸는 경우에는, 기존 링크가 끊어지지 않도록 앵커 태그를 그대로 유지합니다.

링크#

외부 링크#

표준 Markdown 링크 문법을 사용합니다:

[commits](https://github.com/n8n-io/n8n/compare/n8n@0.176.0...n8n@0.177.0)

외부 링크는 자동으로 새 탭에서 열립니다.

내부 링크#

링크 방식은 대상 페이지가 같은 space에 있는지 다른 space에 있는지에 따라 다릅니다. docs/ 아래의 각 최상위 폴더(예: build/, deploy/, administer/)는 각각 별도의 GitBook space입니다.

같은 space 내에서는 표준 Markdown 링크 문법을 사용하고, 대상 파일의 상대 경로에 .md 확장자를 포함해 링크합니다. 원본 경로를 직접 입력하는 대신 대상 파일을 링크로 지정해야, 페이지가 이동하거나 이름이 바뀌어도 참조가 자동으로 최신 상태로 유지됩니다.

상대 경로는 편집 중인 페이지와 대상의 상대적 위치에 따라 달라집니다. 아래 예시는 모두 다음 파일 트리에서 current-page.md를 편집하고 있다고 가정합니다:

docs/                                     # docs root
├── build/                                # current space
│   ├── README.md                         # space landing page
│   ├── understand-workflows/             # subfolder (section) in the space
│   │   ├── README.md                     # section landing page (parent of current-page.md)
│   │   ├── current-page.md               # <- you're editing this page
│   │   └── another-page.md               # sibling page, same level
│   └── manage-workflows/                 # another subfolder in the same space
│       ├── README.md                     # section landing page
│       └── export-import.md              # page in a different subfolder
├── deploy/                               # another space
│   ├── README.md                         # space landing page
│   └── hosting/                          # subfolder in another space
│       ├── environment-variables.md      # page in a different space
│       └── configure.md                  # another page in that subfolder
└── administer/                           # another space

같은 space, 같은 하위 폴더의 페이지에 링크하기

파일 이름만 단독으로 사용합니다:

[link text](another-page.md)

현재 페이지의 상위 페이지에 링크하기

./를 사용하면 현재 폴더(understand-workflows)의 README.md 랜딩 페이지, 즉 상위 페이지를 가리킵니다:

[link to a parent page](./)

같은 space의 다른 하위 폴더에 있는 페이지에 링크하기

현재 폴더에서 ../로 한 단계씩 올라간 다음, 대상 폴더로 내려갑니다:

[link to a page](../manage-workflows/export-import.md)

다른 space에 있는 페이지에 링크하기

상대 파일 경로는 하나의 space 내에서만 유효합니다. GitBook은 space 간 링크를 파일 경로가 아니라 페이지 참조로 해석하므로, 다른 space로 향하는 ../../ 경로는 동작하지 않습니다. 대신 대상 페이지의 GitBook URL로 링크합니다:

https://app.gitbook.com/s/<spaceId>/<page-path>

URL은 다음 두 부분으로 구성합니다:

• <spaceId>: 대상 페이지가 속한 space의 ID입니다. 아래 표에서 확인할 수 있습니다.
• <page-path>: space 폴더 내에서 대상 페이지의 경로로, .md 확장자는 제외합니다. README.md는 해당 폴더 경로가 됩니다(예: host-n8n/configure-n8n/README.md는 host-n8n/configure-n8n이 됩니다).

예를 들어, administer space의 한 페이지에서 deploy space에 있는 docs/deploy/host-n8n/configure-n8n/user-management.md로 링크하려면:

[link to a page](https://app.gitbook.com/s/jm0ZYRpZIPWge2ZSiDYO/host-n8n/configure-n8n/user-management)

docs/ 아래 각 최상위 폴더는 각각 별도의 space입니다:

직접 URL을 만들고 싶지 않다면, GitBook에서 대상 페이지를 열어 링크를 복사하세요. GitBook 접근 권한이 없다면 대신 페이지의 게시된 https://docs.n8n.io/... 주소를 사용하세요.

이미지#

각 space는 해당 space 루트의 .gitbook/assets/에 모든 이미지를 위한 단일 폴더를 가집니다:

docs/                                     # docs root
├── build/                                # space root
│   ├── .gitbook/
│   │   └── assets/                       # all images for this space live here
│   │       └── workflow-overview.png
│   ├── understand-workflows/
│   │   └── current-page.md
│   └── manage-workflows/
│       └── export-import.md
└── deploy/                               # another space
    ├── .gitbook/
    │   └── assets/                       # all images for this space live here
    │       └── hosting-diagram.png

이미지는 사용되는 space의 .gitbook/assets/ 폴더에 저장해야 합니다. 다른 space의 assets 폴더에 있는 이미지는 참조할 수 없습니다.

이미지는 편집 중인 페이지를 기준으로 한 상대 경로로 참조합니다. space 내 어떤 페이지에서든, 먼저 space 루트까지 올라간 다음 .gitbook/assets/로 들어갑니다.

한 단계 깊이의 페이지에서 (예: build-workflows/manage-workflows/export-import.md):

​ ![Alt text](../.gitbook/assets/workflow-overview.png) ​

두 단계 깊이의 페이지에서 (예: build-workflows/understand-workflows/current-page.md):

​ ![Alt text](../../.gitbook/assets/workflow-overview.png) ​

대체 텍스트

항상 설명적인 대체 텍스트(alt text)를 작성합니다. 이는 접근성을 지원하며, 이미지 로드에 실패했을 때 표시됩니다.

• 이미지가 무엇인지가 아니라 무엇을 보여주는지를 설명합니다. "screenshot"이 아니라 "Workflow canvas with a Schedule Trigger connected to an HTTP Request node"처럼 씁니다.
• 125자 미만으로 유지합니다.
• "Image of"나 "Screenshot of"로 시작하지 않습니다.

이미지 파일

• 스크린샷과 다이어그램에는 PNG를 사용합니다.
• 아이콘과 단순한 일러스트에는 가능하면 SVG를 사용합니다.
• 파일 크기를 적절히 유지합니다 — 커밋 전에 PNG를 압축하세요. Squoosh는 무료 브라우저 도구입니다.
• 소문자와 하이픈으로 연결된 파일 이름을 사용합니다: WorkflowOverview.PNG가 아니라 workflow-overview.png.

동영상#

동영상 파일을 n8n-docs 리포지터리에 저장하지 마세요. 동영상은 YouTube, Loom 또는 다른 지원되는 도메인 같은 외부에 호스팅하고, 페이지에 임베드합니다.

동영상을 임베드하려면 다음과 같이 embed 태그 안에 URL을 붙여넣습니다:

코드 예시#

공백이 아니라 탭을 사용합니다. n8n 노드 린터가 이 규칙을 강제하므로 중요합니다. 'Creating nodes' 섹션에 있는 코드 샘플은 사용자의 노드에 복사될 수 있으며, 공백을 사용하면 린터 실패를 일으킬 수 있습니다.

구문 강조를 위해 언어 식별자를 포함한 fenced code block을 사용합니다:

```typescript
// Your code here
```

// Your code here

GitBook은 선택적 코드 블록 설정을 지원합니다. 독자에게 도움이 될 경우 제목, 줄바꿈, 줄 번호를 추가하세요:

```typescript
// Your code here
```

// Your code here

힌트#

힌트(admonition 또는 콜아웃이라고도 함)는 독자의 주의를 특정한 중요 정보로 이끕니다. 힌트에는 info, warning, danger, success 네 가지 스타일이 있습니다. 다음과 같이 사용하세요:

• info는 일반적인 참고사항, 강조하고 싶은 정보, 기능 제한 안내(특정 플랫폼이나 요금제에만 제공되는 기능)에 사용합니다.
• warning은 위험이나 예상치 못한 동작이 있는 경우에 사용합니다.
• danger는 심각한 보안 위험이 있거나(로컬 n8n 인스턴스로의 터널을 여는 경우 등), 파괴적인 작업(잘못하면 사용자가 데이터를 영구적으로 잃을 수 있는 경우)에 사용합니다.
• success는 긍정적인 확인이나 팁에 사용합니다. 자주 사용하지 마세요.

힌트를 과도하게 사용하지 마세요. 자주 사용하면 효과가 떨어집니다.

다음과 같은 힌트 문법을 사용하세요:

<div class="admonition note"><div class="admonition-title">Note</div>

Some hint content.

</div>

힌트에 헤더 블록(제목)을 추가하고 싶다면, 힌트의 첫 줄에 헤더 블록을 추가하세요:

<div class="admonition note"><div class="admonition-title">Note</div>

## This is the hint title/heading

Some hint content

</div>

접이식 블록#

힌트와 비슷하지만 접힌 상태로 표시됩니다. 사용자가 클릭하면 펼쳐집니다. 없으면 페이지를 어수선하게 만들 보충 세부 정보에 사용하세요.

접이식 콘텐츠는 표준 HTML <details> 블록으로 렌더링됩니다:

<details>

<summary>Summary text the user clicks</summary>

Some collapsible content. Standard Markdown works inside the block.

</details>

Summary text the user clicks

Some collapsible content. Standard Markdown works inside the block.

탭 콘텐츠#

외부 요인(플랫폼, 코딩 언어 등)으로 인해 콘텐츠 블록이 다른 경우, 탭으로 나누어 사용자에게 관련된 콘텐츠만 보여주는 것이 유용할 수 있습니다. 탭 섹션은 검색 가능성(discoverability)에 영향을 줄 수 있으므로 신중히 사용하세요.

탭 콘텐츠는 다음과 같이 표기합니다:

**First tab**

The content is rendered following the normal Markdown syntax. To add a list:

* Item one
* Another item
* Still more items

**Second tab**

1. Content for the second tab.
2. No indentation is required.

첫 번째 탭

콘텐츠는 일반적인 Markdown 문법에 따라 렌더링됩니다. 목록을 추가하려면:

• 항목 하나
• 또 다른 항목
• 그 밖의 항목들

두 번째 탭

1. 두 번째 탭의 콘텐츠입니다.
2. 들여쓰기는 필요하지 않습니다.

임베드된 워크플로#

독자가 문서 안에서 직접 워크플로를 보고 상호작용할 수 있도록, 페이지에 n8n 워크플로를 임베드할 수 있습니다. 게시된 템플릿을 템플릿 API URL로 참조합니다:

<div class="admonition note"><div class="admonition-title">워크플로 예제</div><p>대화형 워크플로 데모입니다. <a href="https://api.n8n.io/workflows/templates/1747" target="_blank" rel="noopener noreferrer">워크플로 JSON 보기</a> 또는 <a href="https://docs.n8n.io" target="_blank" rel="noopener noreferrer">n8n 공식 문서</a>에서 확인하세요.</p></div>

게시된 템플릿의 ID를 https://api.n8n.io/workflows/templates/에 추가하면 템플릿 API URL을 찾을 수 있습니다.