InfoGrab DocsInfoGrab Docs

n8n Docs 스타일 가이드

요약

n8n은 Microsoft Writing Style Guide를 사용합니다. 다음과 같은 흔한 패턴을 주의하고, 더 쉬운 표현을 선택합니다. 같은 개념에는 어디서나 같은 용어를 사용하고, 그럴듯한 동의어보다 공식 제품 용어를 우선합니다(예: "activate a workflow"가 아니라 "publish a workflow").

문체#

n8n은 Microsoft Writing Style Guide를 사용합니다. 이 페이지는 n8n Docs에서 가장 중요한 요소를 짚고, n8n 고유의 스타일 선택을 추가합니다.

쉬운 언어#

  • 문서화하는 과정의 각 단계를 명확하게 설명합니다.
  • 현재 시제를 사용합니다.
  • 글을 가능한 한 간결하게 유지합니다. 도움이 되는 무료 브라우저 앱 두 가지입니다.
    • Hemingway는 언어 복잡도를 측정합니다. 목표로 삼을 학년에 대한 고정된 규칙은 없지만, 읽기 학년이 낮을수록 좋습니다.
    • Lexi는 Markdown 텍스트의 문장 복잡도를 여러 측정값을 합쳐 하나의 가독성 점수로 보여 줍니다. 60점 이상을 목표로 합니다. 대부분의 페이지는 이 점수를 넘어야 합니다.

다음과 같은 흔한 패턴을 주의하고, 더 쉬운 표현을 선택합니다.

피해야 할 표현 대신 쓸 표현
utilize, leverage use
in order to to
functionality, capabilities features, what it does
It's important to note that X X
n8n provides a powerful, seamless way to... n8n lets you...

몇 가지 기본 원칙입니다.

  • 군더더기를 줄입니다. "It's important to note that"이나 "Simply" 같은 도입부를 쓰지 않습니다.
  • 마케팅 표현을 피합니다. "powerful", "robust", "seamless"를 쓰지 않고, 기능이 하는 일을 서술합니다.
  • 모호한 수식어를 줄입니다. "very", "quite", "several"을 쓰지 않거나, 구체적인 수치를 제시합니다.
  • 문장을 짧게 유지합니다. 30단어 미만, 한 문장에 하나의 아이디어만 담습니다. 세미콜론이나 두 번째 "and"로 이어진 문장은 나눕니다.
  • "There is"가 아니라 동작으로 시작합니다. "To schedule a workflow, add a Schedule Trigger"로 쓰고, "There is a node that can schedule workflows"로 쓰지 않습니다.

어조와 인칭#

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

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

포용적 언어#

모든 사람을 위해 작성합니다.

  • 알 수 없는 사람에게는 "they"를 사용합니다. "Every user can configure their settings"로 쓰고, "his settings"로 쓰지 않습니다.
  • 성중립적인 용어를 선택합니다. "chairman" 대신 "Chair", "master" 대신 "Main"을 씁니다.

용어와 명칭#

같은 개념에는 어디서나 같은 용어를 사용하고, 그럴듯한 동의어보다 공식 제품 용어를 우선합니다(예: "activate a workflow"가 아니라 "publish a workflow"). 본문에서는 문장형 대소문자(sentence case)를 사용하고, UI 레이블이나 노드 이름을 그대로 쓸 때는 제품의 정확한 대소문자로 굵게 표시합니다. 제품 이름은 문장 맨 앞에서도 소문자 "n8n"으로 씁니다.

사용할 용어와 피할 용어의 전체 목록은 용어와 명칭을 참조하세요.

텍스트 서식#

  • 제목: 문장형 대소문자(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"로 씁니다.

페이지 길이와 세분화#

콘텐츠를 하나의 개념, 작업 또는 참조 범주를 다루는 집중된 페이지로 나눕니다. 하나의 거대한 페이지와 흩어진 조각 사이의 중간 범위를 유지합니다. 자체 완결적이고 제목 구조가 갖춰진 페이지는 독자와 AI 도구 모두에게 가장 효과적입니다(이유는 Agent-friendly docs를 참조하세요).

길이#

  • 적정 범위: 약 1,500자에서 20,000자(250~3,000단어). 사람이 훑어보기에 적합하고 AI 도구가 검색하기에도 적합합니다.
  • 약 1,500자 미만이면 병합합니다. 너무 작아서 검색이 잘 되지 않습니다. 짧은 페이지는 상위 페이지나 형제 페이지에 합칩니다.
  • 약 25,000자를 넘으면 분리합니다. 페이지에 콘텐츠 유형(개념, 방법 안내, 참조)이 섞여 있거나, 한 섹션이 끝없이 커지는 경우(예: 클라이언트별 예제 목록)에도 분리합니다.
  • 약 50,000자를 절대 넘기지 않습니다. 에이전트는 이 한도를 넘는 내용을 잘라 냅니다.

분리하는 방법#

  • 길이로 임의로 나누지 말고 유형 또는 작업 경계(개념, 방법 안내, 참조, 예제)를 따라 나눕니다. 독자가 탐색하는 방식과 맞고 각 덩어리가 하나의 주제를 유지합니다.
  • 관련된 사실은 한 페이지에 둡니다(한 범주의 모든 환경 변수, 한 노드의 모든 매개변수). AI 검색은 인접한 콘텐츠를 함께 가져오므로, 가까이 두면 맥락이 보존됩니다.

각 섹션을 자체 완결적으로 작성#

주변 섹션의 맥락 없이 해당 섹션에 바로 도착한 독자도 이해할 수 있도록 각 섹션을 작성합니다(이유는 Agent-friendly docs를 참조하세요).

  • 설명적인 문장형 대소문자 제목을 씁니다. AI 검색은 페이지의 나머지 없이 제목 단위로 가져오는 경우가 많으므로, 섹션의 주제를 온전히 드러냅니다. "Configuration"이 아니라 "Configure the Schedule Trigger"처럼 씁니다.
  • 각 섹션이 단독으로 이해되게 합니다. 앞쪽을 가리키지 말고 핵심 맥락을 다시 서술합니다. "as mentioned above", "as described in the previous section", "see below"는 에이전트가 섹션을 순서 없이 가져오거나 독자가 검색으로 들어오면 의미가 깨지므로 피합니다.
  • 중복하지 말고 다시 서술합니다. 섹션에 필요한 한두 가지 사실만 반복하고, 단락 전체를 반복하지 않습니다. 두 섹션에 같은 긴 설명이 필요하다면 하나의 제목 아래 합쳐야 한다는 신호입니다. 페이지가 간결하게 유지되도록 다시 서술하는 내용은 짧게 씁니다(쉬운 언어 참조).

한 문장 답변으로 시작#

H1 바로 뒤, 기존 소개글, hint 또는 include보다 앞에 쉬운 문장 하나를 추가해 페이지가 무엇에 관한 것인지 구체적으로 답합니다(이유는 Agent-friendly docs를 참조하세요).

  • 페이지나 노드로 독자가 무엇을 할 수 있는지, 실제 제품, 노드 또는 기술의 이름을 넣어 서술합니다. "it lets you do things" 같은 표현은 쓰지 않습니다.
  • 한 문장으로 씁니다. 짧은 단서가 꼭 필요한 경우에만 두 문장으로 씁니다.
  • 기존 소개글이 이미 비슷한 문장으로 시작하면 생략합니다.

예: "The Code node lets you run your own JavaScript or Python inside a workflow, so you can transform data or add logic the built-in nodes don't cover."

관련 페이지, 선행 조건, 다음 단계 링크#

각 페이지를 같은 주제의 다른 페이지와 연결합니다(Agent-friendly docs 참조).

아래 지침은 docs/integrations/("Nodes") 페이지에는 적용되지 않습니다. 해당 페이지는 다른 구조를 사용합니다.

  • 선행 조건과 다음 단계는 항상 링크합니다.
  • 섹션 랜딩 페이지는 하위 페이지로 링크합니다. 하위 페이지가 둘 이상이면 "In this section" 제목 아래에 글머리 기호(링크 + 짧은 설명)로 나열합니다. 하나뿐이면 목록을 생략하고 처음 언급하는 곳에 인라인으로 링크합니다.
  • 하위 페이지는 "Related resources" 섹션에서 상위와 형제 페이지로 링크합니다. 이 섹션은 페이지 끝에 두며, 상위 페이지에 대한 링크 하나와 직접 형제 페이지 각각에 대한 링크를 설명 없이 둡니다. 페이지가 상위 페이지의 README.md와 같은 폴더에 있으면 상위 페이지에 ./를 사용하고, 페이지 자체가 상위 한 단계 아래의 섹션 랜딩 페이지이면 ../를 사용합니다(상위 페이지 참조). 그 밖의 진짜 관련 있는 페이지는 재량으로 추가합니다.
  • 형제가 10개를 넘으면 형제 목록을 생략합니다. 상위 페이지만 링크합니다(상위 페이지의 "In this section"에 전체 목록이 있습니다).
  • 자신이 상위 페이지인 페이지는 둘 다 합니다. 하위 페이지용 "In this section"을 두고, 자신의 상위 및 형제 페이지용 "Related resources" 푸터도 둡니다. 한 단계 위와 옆으로만 링크하고 조부모 페이지로는 링크하지 않습니다.
  • 모든 페이지가 같은 단일 사실 템플릿을 따르는 평면적 참조 모음은 형제 링크를 생략합니다(예: 표현식 데이터 유형별 페이지 하나씩). "Related resources"에서 상위 페이지로만 링크합니다.
  • 같은 주제로 서로 연결된 페이지 군집을 다섯 개 이상 만드는 것을 목표로 합니다.
  • 본문에서는 의미 있는 첫 언급에만 링크합니다. 대상을 설명하는 앵커 텍스트를 사용하며(예: "click here"가 아니라 Configure the Schedule Trigger), 링크를 위해 문장을 추가하지 말고 주제에 대한 기존 언급을 재활용합니다. 링크는 섹션에 필요한 맥락을 대신할 수 없으므로, 그런 경우 핵심 사실을 다시 서술합니다(각 섹션을 자체 완결적으로 작성 참조).

기능 제공 범위#

기능의 제공 범위는 세 가지 방식으로 제한될 수 있습니다.

  • 요금제 또는 플랫폼: 어떤 n8n Cloud 요금제 또는 셀프 호스팅 에디션에서 제공되는지.
  • 버전: 어떤 n8n 버전에서 도입, 지원 중단 또는 제거되었는지.
  • Preview 상태: 아직 안정화 중인지, 변경될 수 있는지, 모든 사용자에게 배포되지 않았는지.

요금제, 플랫폼, 버전 제한은 하나의 문서화 체계를 공유합니다. Preview 상태는 다르게 동작하며 항상 별도로 문서화합니다.

요금제, 플랫폼, 버전 제한#

세 가지 범위 중 하나로 문서화합니다.

  • 페이지 또는 섹션: 페이지 제목 아래나 해당 제목 아래에 Feature availability라는 제목의 info hint를 둡니다. Feature availability hints를 참조하세요.
  • 인라인 또는 간단한 언급: 작은 옵션, 필드, 역할, 동작 옆의 짧은 메모이거나, 자체 제목 없이 본문에서 이름만 언급된 기능 또는 노드 전체입니다. 제한을 문장에 녹여 씁니다. 인라인 및 간단한 언급을 참조하세요.
  • 표 행: 여러 행 중 하나입니다. 제한을 설명 셀에 넣고, 여러 행이 서로 다르면 전용 칼럼을 둡니다. 표 행을 참조하세요.

Feature availability hints#

예시:

요금제와 버전 모두:

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

**Feature availability**

Environments are available on:

- **n8n Cloud:** Pro, Enterprise
- **Self-hosted:** Enterprise

Available from n8n 2.30.0.

</div>

버전만: 대상은 기능일 수도, 노드일 수도 있습니다.

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

**Feature availability**

Canvas Groups are available from n8n 2.28.0.

</div>

지원 중단 또는 제거에는 info가 아니라 warning을 사용합니다. 제거인 경우 문구를 바꿉니다(예: "N8N_RUNNERS_ENABLED removed from n8n 3.0"). 아래 예에서 대상은 설정입니다.

<div class="admonition warning"><div class="admonition-title">Warning</div>

**Feature availability**

`N8N_RUNNERS_ENABLED` is deprecated from n8n 2.0.

</div>

페이지 전체가 지원 중단되었거나 제거된 기능에 관한 것이라면 기본 deprecated 태그도 추가합니다(frontmatter의 태그 참조). deprecated는 status: 필드의 검증된 값이 아니므로 status: 필드는 추가하지 않습니다.

---
tags:
  - tag: deprecated
    primary: true
---

이 태그는 스페이스의 .gitbook/tags.yaml에 레이블 "Deprecated"와 색상 빨강이 정의되어 있어야 합니다.

규칙:

  • hint 스타일: 지원 중단이나 제거(독자가 조치해야 하는 경우)에는 warning, 그 외에는 info를 사용합니다. 두 가지를 합친 hint에는 warning을 사용합니다.
  • 본문에 대상을 명시합니다. hint 제목만으로는 무엇이 제공되는지 알 수 없고, 바깥의 제목에도 의존하지 않습니다. "available from n8n X.Y.Z"는 끊지 않고 그대로 씁니다. 버전만 다루는 경우 대체 대상을 밝힐 수 있습니다. 예: "The Chat Trigger node is available from n8n 1.24.0, replacing the Manual Chat Trigger node."
  • 플랫폼 글머리 기호: " <is/are> available on:"으로 시작합니다. 항상 두 플랫폼을 모두 명시합니다. 둘 다 제공되면 글머리 기호를 하나씩 둡니다. 하나만 제공되면 해당 글머리 기호 아래에 미제공 안내 줄을 둡니다("It isn't available on n8n Cloud."/"...self-hosted."). 다른 곳에서 조건부로만 제공되는 경우(예: 요청 시 제공) 미제공 안내 줄 대신 단서 줄을 둡니다(예: "On n8n Cloud Enterprise, contact n8n to enable it.").
  • 등급: 낮은 등급부터 높은 등급 순으로 쉼표로 구분하며 "and"는 쓰지 않습니다. Cloud: Starter, Pro, Enterprise. 셀프 호스팅: Community, Registered Community, Business, Enterprise. 정확한 대문자 이름을 사용하고 "Registered Community"는 줄이지 않고 풀어 씁니다.
  • "n8n Cloud"로 쓰고, 단독 "Cloud"는 쓰지 않습니다.
  • 플랫폼 전체: 모든 등급을 나열하지 말고 All plans/All editions로 씁니다. "All plans"에는 무료 체험이 포함되며(Pro와 동일), 무료 체험 자체는 나열하지 않고 체험 페이지에서만 다룹니다.
  • 글머리 기호 아래 순서: (1) 미제공/단서 줄, (2) 버전 문장, (3) 기능별 기타 단서.
  • 요금제 제한 없음(버전만, 지원 중단, 제거): 글머리 기호 없이 제목과 문장만 둡니다.
  • Compare plans and editions나 릴리스 노트로 링크하지 않습니다. 사실을 문장에 직접 서술하고, 필요하면 독자가 검색하도록 둡니다.

인라인 및 간단한 언급#

더 큰 기능 안의 작은 컨트롤, 옵션, 필드, 역할이나 자체 제목 없이 본문에서 이름만 언급된 기능/노드 전체에는 인라인 문구를 사용합니다. 페이지 전체 또는 섹션 전체에 걸친 제한에는 사용하지 않습니다(hint를 사용합니다).

  • "this feature"나 "this option"이 아니라 구체적인 대상의 이름을 씁니다. 맥락 없이도 단독으로 이해되어야 합니다.
  • 항목당 한 문장으로 씁니다. 요금제/플랫폼과 버전이 모두 해당되면 두 문장으로 쓰고, 요금제/플랫폼을 먼저 씁니다.
  • 두 플랫폼이 모두 중요하면 둘 다 언급합니다. 생략으로 미제공을 암시하지 않습니다.
  • 버전, 지원 중단 또는 제거는 간단하게 서술합니다("available from n8n X", "deprecated from n8n X"). hint의 "Available from" 도입 문구는 생략합니다.
  • 문장이 두 개를 넘거나 두 플랫폼 글머리 기호가 모두 필요하면 범위가 지정된 hint로 승격합니다.

컨트롤, 옵션, 필드, 역할의 경우:

The **Scopes** option is available on n8n Cloud Pro, Enterprise, and self-hosted Enterprise.

The **Legacy format** field is deprecated from n8n 2.30.0.

자체 제목이 없는 기능 또는 노드 전체의 경우 제한을 문장에 녹여 씁니다.

The Data table node (available from n8n 2.17.0) stores data between executions.

The environments feature (n8n Cloud Enterprise, self-hosted Enterprise) lets you promote workflows between instances.

표 행#

여러 행 중 하나에는 인라인 텍스트와 같은 어휘와 순서를 사용합니다. 제한을 설명 셀에 넣습니다.

Variable Type Default Description
N8N_RUNNERS_ENABLED (deprecated) Boolean false Whether task runners are enabled. Deprecated from n8n 2.0; you no longer need to set it.

또는 여러 행이 서로 다르면 전용 칼럼을 추가합니다.

Variable Available on Description
N8N_LDAP_ENABLED Self-hosted Business, Enterprise Whether LDAP sign-in is enabled.
N8N_SMTP_HOST All editions SMTP server hostname for outgoing email.

버전 표기#

두 가지 버전 유형#

n8n에는 서로 다른 두 가지 버전 번호가 있습니다. 독자가 어느 쪽인지 추측하게 두지 않습니다.

  • 인스턴스 버전: n8n 릴리즈의 3단계 시맨틱 버전(예: 2.30.0). 기능, 환경 변수, API, CLI 명령, 훅에 사용합니다.
  • 노드 버전: 노드의 버전으로, 보통 2단계입니다(예: 4.7). 노드에 한정된 사실에만 사용합니다.

본문에서 숫자만 쓰지 않고 한정어를 붙입니다. "version 2"가 아니라 "n8n 2.30.0" 또는 "node version 4.7"로 씁니다.

버전 번호 쓰기#

숫자 지침을 따르고, n8n 인스턴스 버전에는 다음을 추가로 적용합니다.

  • 제품 이름 + 숫자: n8n 2.30.0.
  • v 접두사를 붙이지 않습니다: "n8n v2.30.0"이 아닙니다.
  • "n8n" 뒤에 "version"을 붙이지 않습니다: "n8n version 2.30.0"이 아닙니다.
  • 본문에서는 인라인 코드 서식을 쓰지 않습니다: n8n 2.30.0이 아니라 n8n 2.30.0으로 씁니다. 버전이 실제 스니펫, 명령, 파일 경로에 나올 때만 코드 서식을 사용합니다. 예: n8n@2.30.0, Docker 태그, package.json 값.

Preview 상태#

Preview 기능은 사용할 수 있지만 아직 완성되거나 안정적이지 않으며 변경될 수 있습니다. "Preview"는 성숙도 레이블로서 대문자로 씁니다("is in Preview", "a Preview feature", "In Preview from n8n 2.20.0"). "beta"가 아니라 "Preview"를 사용합니다. 링크 미리보기, UI 미리보기 동작처럼 관련 없는 의미의 단어는 소문자로 둡니다. frontmatter와 태그 값은 산문이 아니라 문자 그대로의 식별자이므로 소문자로 유지합니다(status: preview, tag: preview).

페이지 또는 섹션: hint 제목은 **Feature availability**가 아니라 **Preview status**로 합니다. 안정성과 제공 범위는 서로 다른 질문이므로, 제공 범위 hint와 같은 레이블을 가진 두 번째 hint로 두지 않고 각각 별도의 hint를 둡니다. hint는 주변 제목과 별개로 훑어보게 되므로 노드나 기능의 이름은 제목이 아니라 아래 문장에 씁니다.

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

**Preview status**

The Data table node is in Preview and may change in future releases. Avoid relying on it in production workflows.

</div>

페이지 전체가 Preview 기능을 다룬다면 status: preview도 설정하고 기본 preview 태그를 추가합니다(frontmatter의 태그 참조).

---
status: preview
tags:
  - tag: preview
    primary: true
---

실제 사례는 Build and manage agents를 참조하세요.

인라인 또는 간단한 언급: 작은 컨트롤이거나, 자체 제목 없이 본문에서 이름만 언급된 기능 또는 노드 전체의 경우:

The **Streaming response** option is in Preview and may change in future releases.

The Data table node is in Preview and may change in future releases.
  • 도움이 되면 버전과 연결합니다: "In Preview from n8n 2.20.0".
  • Feature availability와 분리해 둡니다. 둘 다 해당되면 하나를 다른 하나에 녹이지 말고 쌓아 둡니다(hint + hint, 또는 문장 + 문장).
  • 인라인 메모가 한 문장을 넘는 경우: 페이지 또는 섹션 수준의 hint로 승격합니다.

Vale 린팅#

n8n은 Vale을 사용해 이 가이드의 규칙에 따라 문서를 린트합니다.

구성은 다음과 같습니다.

  • 리포지터리 루트에 있는 .vale.ini 파일. 구성을 담고 있습니다.
  • 스타일 정의를 담은 styles 디렉터리. 기성 스타일 라이브러리와 n8n 고유 스타일이 포함됩니다.
  • 모든 PR에서 Vale을 실행하고 위반 사항을 PR에 직접 보고하는 GitHub Action.

로컬 머신에서 Vale을 실행하려면 다음과 같이 합니다.

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

Frontmatter#

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

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

Frontmatter 예시:

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

기존 n8n Docs 페이지에서 contentType, nodeTitle, originalFilePath, originalUrl, url 같은 다른 frontmatter 필드를 볼 수 있습니다. 이 필드는 기존 페이지의 마이그레이션 관리를 위한 것입니다. 새 페이지에는 추가하지 않습니다.

태그#

시각적 태그는 페이지에 레이블로 렌더링되며, primary: true이면 사이드 메뉴에도 표시됩니다. 스페이스의 .gitbook/tags.yaml에 (레이블과 색상이) 정의되어 있어야만 렌더링됩니다. tags 배열에 객체로 추가합니다.

---
tags:
  - release
  - tag: preview
    primary: true
---

이 예시에서 시각적 태그는 tag: preview뿐입니다. release는 일치하는 .gitbook/tags.yaml 항목이 없는 일반 문자열이므로 아무것도 렌더링하지 않습니다. tags 배열에는 이처럼 아무 동작도 하지 않는 문자열을 실제 시각적 태그와 함께 둘 수 있으며, 이는 두 번째 시각적 태그가 아니라 별개의 것입니다.

  • 시각적 태그는 적용하기 전에 스페이스의 .gitbook/tags.yaml에 이미 정의되어 있어야 합니다. 있는지 확인하고, 없으면 추가합니다.
  • 시각적 태그는 레이블일 뿐입니다. 페이지의 설명 hint를 대체하지 않습니다. 상태가 무엇을 의미하는지는 hint에서 설명하고, 태그는 UI에서 표시만 합니다.
  • 문서에서 허용되는 시각적 태그는 현재 Deprecated(지원 중단된 기능에 관한 페이지 전체), Preview(Preview 기능에 관한 페이지 전체), Archived(더 이상 업데이트되지 않는 페이지) 세 가지입니다. 이 세 가지 외의 시각적 태그는 만들거나 사용하지 않습니다.

페이지 탐색#

각 스페이스는 루트에 사이드바를 정의하는 SUMMARY.md 파일을 둡니다. 어떤 페이지가 표시되는지, 어떤 순서인지, 어떻게 중첩되는지를 정의합니다. GitBook은 이 파일로 탐색을 구성하므로, 새 페이지는 SUMMARY.md에 추가하기 전까지 사이드바에 나타나지 않습니다. .md 파일을 만드는 것만으로는 충분하지 않습니다.

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

# 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으로 작성하며, 블록(콜아웃, 탭 및 기타 구조화된 페이지 요소)이라는 GitBook 전용 구성 요소를 함께 사용합니다. 아래 섹션에서 자주 쓰는 블록을 다룹니다.

Note

사용 가능한 모든 블록 유형의 Markdown 표현은 GitBook 문서를 참조하세요.

제목#

제목은 일반 Markdown(## Heading text)으로 문장형 대소문자(sentence case)로 작성합니다. GitBook이 제목 텍스트로 클릭 가능한 앵커를 자동으로 생성하므로 앵커 마크업을 직접 추가하지 않습니다.

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

## Heading text

이 태그는 앵커를 고정하므로, 나중에 제목 텍스트가 바뀌어도 제목으로 연결되는 링크가 계속 동작합니다. 제목을 고쳐 쓸 때는 앵커 태그를 유지해 기존 링크가 깨지지 않게 합니다.

링크#

외부 링크#

표준 Markdown 링크 구문을 사용합니다.

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

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

내부 링크#

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

같은 스페이스 내에서는 표준 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
대상 위치 링크 구문
같은 하위 폴더, 같은 스페이스 [link text](another-page.md)
상위 페이지, 상위가 README.md인 경우 [link to a parent page](./)
상위 페이지, 상위가 이름이 있는 페이지인 경우(이 폴더에 README.md가 없음, 예: connect-to-n8n-mcp-server.md) [link to a parent page](connect-to-n8n-mcp-server.md), ./가 아니라 파일로 직접 링크
상위 페이지, 현재 페이지 자체가 섹션 랜딩 페이지(README.md)인 경우 [link to a parent page](../), ./는 상위가 아니라 자기 자신을 가리키기 때문
다른 하위 폴더, 같은 스페이스 [link to a page](../manage-workflows/export-import.md)
다른 스페이스 [link to a page](https://app.gitbook.com/s/<spaceId>/<page-path>)

상위 페이지#

./와 ../는 디렉터리를 가리키는 참조로, GitBook이 어떤 상대 깊이에서든 해당 폴더의 README.md로 기본적으로 해석합니다. ./는 현재 폴더의 랜딩 페이지를 가리키며, 현재 페이지가 그 폴더 안의 하위 페이지일 때만 상위 페이지가 됩니다. 현재 페이지 자체가 섹션 랜딩 페이지(README.md)이면 ./는 자기 자신을 가리키므로, 한 단계 위의 실제 상위 페이지로 가려면 ../를 사용합니다.

다른 스페이스의 페이지로 링크#

상대 파일 경로는 스페이스 안에서만 해석됩니다. GitBook은 스페이스 사이의 링크를 파일 경로가 아니라 페이지 참조로 해석하므로, 다른 스페이스로 향하는 ../../ 경로는 동작하지 않습니다. 대신 대상 페이지의 GitBook URL로 링크합니다.

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

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

  • <spaceId>: 대상 페이지가 있는 스페이스의 ID. SPACE_INDEX.md에서 확인합니다.
  • <page-path>: 스페이스 폴더 안에서의 대상 페이지 경로이며 .md 확장자를 뺀 것입니다. README.md는 해당 폴더 경로가 됩니다(예: host-n8n/configure-n8n/README.md는 host-n8n/configure-n8n).

예를 들어 administer 스페이스의 페이지에서 deploy 스페이스의 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)

이 형식은 다른 스페이스의 페이지에만 사용합니다. 이미 편집 중인 스페이스의 페이지에는 상대 .md 링크를 사용합니다. GitBook은 두 형식을 모두 렌더링하지만, 스페이스 URL은 GitBook의 이름 변경 추적에서 빠지므로 누군가 대상 페이지를 이동하면 링크가 깨집니다. 또한 GitBook 미리보기에서 리비전을 벗어나, 변경 사항이 아니라 게시된 콘텐츠를 기준으로 해석됩니다. internal-links CI 검사는 이를 same-space-absolute로 보고합니다.

docs/ 아래의 각 최상위 폴더는 별도의 스페이스입니다. 대상 스페이스의 스페이스 ID는 리포지터리 루트의 SPACE_INDEX.md에서 찾을 수 있으며, 이 파일은 각 스페이스의 GitBook Git Sync 설정으로 매일 생성됩니다.

URL을 직접 만들고 싶지 않다면 GitBook에서 대상 페이지를 열고 링크를 복사합니다. GitBook에 접근할 수 없으면 해당 페이지의 게시된 https://docs.n8n.io/... 주소를 사용합니다.

이미지#

이미지는 텍스트를 보완하는 용도이며, 이미지만으로 정보를 전달하지 않습니다(이유는 Agent-friendly docs를 참조하세요). 독자가 해야 하거나 알아야 하는 모든 내용은 본문에 씁니다.

  • 모든 지시는 텍스트로 씁니다. 스크린샷은 화면이 어떻게 생겼는지 보여 줄 수 있지만, 단계("Select Add trigger, then choose On schedule")는 글로 써야 합니다. 설정, 값, 메뉴 경로, 클릭 대상의 유일한 사본을 이미지 안에만 두지 않습니다.
  • 텍스트를 스크린샷으로 찍지 않습니다. 독자가 복사하고 에이전트가 읽을 수 있도록 코드, 명령, 오류 메시지, 구성 값은 코드 블록이나 표에 넣습니다. 터미널이나 코드 편집기의 그림을 붙여 넣지 않습니다.
  • 스크린샷은 지시가 아니라 확인용으로 취급합니다. 글로 쓴 단계를 대체하지 않고 함께 두어, 독자가 방향을 잡거나 올바른 위치에 있는지 확인하게 하는 데 사용합니다.

각 스페이스에는 모든 이미지를 담는 단일 폴더가 있으며, 해당 스페이스 루트의 .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

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

편집 중인 페이지를 기준으로 한 상대 경로로 이미지를 참조합니다. 스페이스 내 어느 페이지에서든 먼저 스페이스 루트까지 올라간 다음 .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로 씁니다.

인라인 아이콘

UI 요소가 아이콘으로만 표시될 때(예: 보이는 텍스트 레이블이 없는 메뉴) HTML <img> 태그와 data-size="line"을 사용해 인라인으로 삽입하면, 블록 이미지가 아니라 텍스트 높이로 렌더링됩니다.

select **Workflow menu** <img src="/images/docs/n8n/.gitbook/assets/three-dots-horizontal.png" alt="Workflow menu icon" data-size="line">
  • 용어를 굵게 표시하고 <img> 태그는 굵게 표시하지 않습니다.
  • 대체 텍스트는 굵게 표시한 용어와 일치하도록 " icon"으로 설정합니다.
  • 어떤 아이콘 파일이 어떤 명명된 요소에 대응하는지는 용어와 명칭을 참조하세요.

동영상#

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

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

코드 예제#

공백이 아니라 탭을 사용합니다. n8n 노드 린터가 이 규칙을 강제하므로 중요합니다. 'Creating nodes' 섹션의 코드 샘플은 사용자의 노드에 복사될 수 있고, 공백을 사용하면 린터 오류가 발생합니다.

구문 강조를 위해 언어 식별자를 붙인 펜스 코드 블록을 사용합니다.

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

// Your code here

GitBook은 선택적 코드 블록 설정을 지원합니다. 독자에게 도움이 되면 제목, 줄 바꿈 또는 줄 번호를 추가합니다.


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


// Your code here

기능마다 실제 사용 예제 제시#

코드, 표현식 또는 구성 인터페이스가 있는 모든 항목에는 실제 사용 예제를 포함합니다. 독자와 코딩 에이전트는 서술보다 예제에 더 많이 의존합니다.

  • 일반적인 경우를 먼저 다루고, 그다음 문제가 생기는 경우를 다룹니다. 간단한 경로를 보여 준 다음 예외 상황(빈 입력, 페이지네이션, 속도 제한)과 실패(독자가 보게 되는 오류와 해결 방법)를 보여 줍니다.
  • 양보다 다양성을 중시합니다. 서로 다른 점을 보여 주는 예제 세 개가 거의 같은 예제 여섯 개보다 낫습니다. 채우려고 늘리지 말고 다양하게 구성합니다.
  • 의도를 인라인 주석으로 설명합니다. 각 예제가 무엇을 하고 왜 하는지 밝혀서 다른 지시로 오해되지 않게 합니다.
  • 모든 자리 표시자에 레이블을 붙입니다. 텍스트 서식에 맞춰 하이픈으로 연결한 단어를 꺾쇠괄호 안에 씁니다. YOUR_KEY나 실제 값이 아니라 <your-api-key> 또는 로 씁니다.
  • 제약 조건은 서술하지 말고 구조화합니다. 매개변수, 기본값, 한도는 단락이 아니라 표나 스키마 블록에 넣습니다.

잘못된 예제를 보여 줄 때는 옆에 올바른 예제를 함께 둡니다. 망가진 스니펫을 홀로 두면 그대로 복사됩니다.

Hint#

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

  • info는 일반적인 메모, 눈에 띄게 하려는 정보, 기능 제한 상자(특정 플랫폼이나 요금제 등급으로 제한된 기능)에 사용합니다.
  • warning은 위험이나 예상치 못한 동작이 있는 경우에 사용합니다.
  • danger는 보안 위험이 큰 경우(예: 로컬 n8n 인스턴스로 터널을 여는 경우)나 파괴적인 경우(사용자가 잘못 수행하면 데이터를 영구적으로 잃을 수 있는 경우)에 사용합니다.
  • success는 긍정적인 확인이나 팁에 사용합니다. 드물게 사용합니다.

Hint를 남용하지 않습니다. 많이 사용하면 효과가 떨어집니다.

다음 hint 구문을 사용합니다.

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

Some hint content.

</div>
Note

Some hint content.

hint에 헤더 블록(제목)을 추가하려면 hint의 첫 줄에 헤더 블록을 추가합니다.

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

## This is the hint title/heading

Some hint content.

</div>
Note

This is the hint title/heading#

Some hint content.

접을 수 있는 블록#

hint와 비슷하지만 접혀 있습니다. 사용자가 클릭해서 펼칩니다. 그대로 두면 페이지가 어수선해질 보충 상세 내용에 사용합니다.

접을 수 있는 콘텐츠는 표준 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.

탭 콘텐츠#

콘텐츠가 외부 요인(플랫폼, 코딩 언어 등)에 따라 달라지는 경우 탭으로 구분하면 사용자가 자신에게 해당하는 콘텐츠만 볼 수 있어 유용할 수 있습니다. 탭 섹션은 찾기 쉬움에 영향을 줄 수 있으므로 아껴서 사용합니다.

탭은 짧은 병렬 변형에만 사용합니다(이유는 Agent-friendly docs를 참조하세요). 탭 블록 전체를 한 화면(결합 약 3,000자) 이내로 유지합니다. 변형이 이 범위를 넘어서면(각각 전체 절차가 필요하거나 사소하지 않은 변형이 네 개 이상이면) 탭을 쓰지 말고 각 변형에 페이지에서 자체 제목을 부여해 각각이 깔끔하고 자체 완결적인 섹션이 되게 합니다. 결합한 페이지가 페이지 길이 지침을 초과하거나 변형 집합이 열려 있는 경우에만 변형마다 페이지를 나눕니다. 공통 설정과 설명은 변형마다 반복되지 않도록 탭 블록 밖에 둡니다.

탭 콘텐츠는 다음과 같이 표시합니다.


**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 구문에 따라 렌더링됩니다. 목록을 추가하려면 다음과 같이 합니다.

  • Item one
  • Another item
  • Still more items

두 번째 탭

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

임베드된 워크플로#

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>

템플릿 API URL은 게시된 템플릿의 ID를 https://api.n8n.io/workflows/templates/ 뒤에 붙여 찾습니다.

n8n Docs 스타일 가이드

n8n v2.42
원문 보기

요약

n8n은 Microsoft Writing Style Guide를 사용합니다. 다음과 같은 흔한 패턴을 주의하고, 더 쉬운 표현을 선택합니다. 같은 개념에는 어디서나 같은 용어를 사용하고, 그럴듯한 동의어보다 공식 제품 용어를 우선합니다(예: "activate a workflow"가 아니라 "publish a workflow").

문체#

n8n은 Microsoft Writing Style Guide를 사용합니다. 이 페이지는 n8n Docs에서 가장 중요한 요소를 짚고, n8n 고유의 스타일 선택을 추가합니다.

쉬운 언어#

  • 문서화하는 과정의 각 단계를 명확하게 설명합니다.
  • 현재 시제를 사용합니다.
  • 글을 가능한 한 간결하게 유지합니다. 도움이 되는 무료 브라우저 앱 두 가지입니다.
    • Hemingway는 언어 복잡도를 측정합니다. 목표로 삼을 학년에 대한 고정된 규칙은 없지만, 읽기 학년이 낮을수록 좋습니다.
    • Lexi는 Markdown 텍스트의 문장 복잡도를 여러 측정값을 합쳐 하나의 가독성 점수로 보여 줍니다. 60점 이상을 목표로 합니다. 대부분의 페이지는 이 점수를 넘어야 합니다.

다음과 같은 흔한 패턴을 주의하고, 더 쉬운 표현을 선택합니다.

피해야 할 표현 대신 쓸 표현
utilize, leverage use
in order to to
functionality, capabilities features, what it does
It's important to note that X X
n8n provides a powerful, seamless way to... n8n lets you...

몇 가지 기본 원칙입니다.

  • 군더더기를 줄입니다. "It's important to note that"이나 "Simply" 같은 도입부를 쓰지 않습니다.
  • 마케팅 표현을 피합니다. "powerful", "robust", "seamless"를 쓰지 않고, 기능이 하는 일을 서술합니다.
  • 모호한 수식어를 줄입니다. "very", "quite", "several"을 쓰지 않거나, 구체적인 수치를 제시합니다.
  • 문장을 짧게 유지합니다. 30단어 미만, 한 문장에 하나의 아이디어만 담습니다. 세미콜론이나 두 번째 "and"로 이어진 문장은 나눕니다.
  • "There is"가 아니라 동작으로 시작합니다. "To schedule a workflow, add a Schedule Trigger"로 쓰고, "There is a node that can schedule workflows"로 쓰지 않습니다.

어조와 인칭#

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

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

포용적 언어#

모든 사람을 위해 작성합니다.

  • 알 수 없는 사람에게는 "they"를 사용합니다. "Every user can configure their settings"로 쓰고, "his settings"로 쓰지 않습니다.
  • 성중립적인 용어를 선택합니다. "chairman" 대신 "Chair", "master" 대신 "Main"을 씁니다.

용어와 명칭#

같은 개념에는 어디서나 같은 용어를 사용하고, 그럴듯한 동의어보다 공식 제품 용어를 우선합니다(예: "activate a workflow"가 아니라 "publish a workflow"). 본문에서는 문장형 대소문자(sentence case)를 사용하고, UI 레이블이나 노드 이름을 그대로 쓸 때는 제품의 정확한 대소문자로 굵게 표시합니다. 제품 이름은 문장 맨 앞에서도 소문자 "n8n"으로 씁니다.

사용할 용어와 피할 용어의 전체 목록은 용어와 명칭을 참조하세요.

텍스트 서식#

  • 제목: 문장형 대소문자(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"로 씁니다.

페이지 길이와 세분화#

콘텐츠를 하나의 개념, 작업 또는 참조 범주를 다루는 집중된 페이지로 나눕니다. 하나의 거대한 페이지와 흩어진 조각 사이의 중간 범위를 유지합니다. 자체 완결적이고 제목 구조가 갖춰진 페이지는 독자와 AI 도구 모두에게 가장 효과적입니다(이유는 Agent-friendly docs를 참조하세요).

길이#

  • 적정 범위: 약 1,500자에서 20,000자(250~3,000단어). 사람이 훑어보기에 적합하고 AI 도구가 검색하기에도 적합합니다.
  • 약 1,500자 미만이면 병합합니다. 너무 작아서 검색이 잘 되지 않습니다. 짧은 페이지는 상위 페이지나 형제 페이지에 합칩니다.
  • 약 25,000자를 넘으면 분리합니다. 페이지에 콘텐츠 유형(개념, 방법 안내, 참조)이 섞여 있거나, 한 섹션이 끝없이 커지는 경우(예: 클라이언트별 예제 목록)에도 분리합니다.
  • 약 50,000자를 절대 넘기지 않습니다. 에이전트는 이 한도를 넘는 내용을 잘라 냅니다.

분리하는 방법#

  • 길이로 임의로 나누지 말고 유형 또는 작업 경계(개념, 방법 안내, 참조, 예제)를 따라 나눕니다. 독자가 탐색하는 방식과 맞고 각 덩어리가 하나의 주제를 유지합니다.
  • 관련된 사실은 한 페이지에 둡니다(한 범주의 모든 환경 변수, 한 노드의 모든 매개변수). AI 검색은 인접한 콘텐츠를 함께 가져오므로, 가까이 두면 맥락이 보존됩니다.

각 섹션을 자체 완결적으로 작성#

주변 섹션의 맥락 없이 해당 섹션에 바로 도착한 독자도 이해할 수 있도록 각 섹션을 작성합니다(이유는 Agent-friendly docs를 참조하세요).

  • 설명적인 문장형 대소문자 제목을 씁니다. AI 검색은 페이지의 나머지 없이 제목 단위로 가져오는 경우가 많으므로, 섹션의 주제를 온전히 드러냅니다. "Configuration"이 아니라 "Configure the Schedule Trigger"처럼 씁니다.
  • 각 섹션이 단독으로 이해되게 합니다. 앞쪽을 가리키지 말고 핵심 맥락을 다시 서술합니다. "as mentioned above", "as described in the previous section", "see below"는 에이전트가 섹션을 순서 없이 가져오거나 독자가 검색으로 들어오면 의미가 깨지므로 피합니다.
  • 중복하지 말고 다시 서술합니다. 섹션에 필요한 한두 가지 사실만 반복하고, 단락 전체를 반복하지 않습니다. 두 섹션에 같은 긴 설명이 필요하다면 하나의 제목 아래 합쳐야 한다는 신호입니다. 페이지가 간결하게 유지되도록 다시 서술하는 내용은 짧게 씁니다(쉬운 언어 참조).

한 문장 답변으로 시작#

H1 바로 뒤, 기존 소개글, hint 또는 include보다 앞에 쉬운 문장 하나를 추가해 페이지가 무엇에 관한 것인지 구체적으로 답합니다(이유는 Agent-friendly docs를 참조하세요).

  • 페이지나 노드로 독자가 무엇을 할 수 있는지, 실제 제품, 노드 또는 기술의 이름을 넣어 서술합니다. "it lets you do things" 같은 표현은 쓰지 않습니다.
  • 한 문장으로 씁니다. 짧은 단서가 꼭 필요한 경우에만 두 문장으로 씁니다.
  • 기존 소개글이 이미 비슷한 문장으로 시작하면 생략합니다.

예: "The Code node lets you run your own JavaScript or Python inside a workflow, so you can transform data or add logic the built-in nodes don't cover."

관련 페이지, 선행 조건, 다음 단계 링크#

각 페이지를 같은 주제의 다른 페이지와 연결합니다(Agent-friendly docs 참조).

아래 지침은 docs/integrations/("Nodes") 페이지에는 적용되지 않습니다. 해당 페이지는 다른 구조를 사용합니다.

  • 선행 조건과 다음 단계는 항상 링크합니다.
  • 섹션 랜딩 페이지는 하위 페이지로 링크합니다. 하위 페이지가 둘 이상이면 "In this section" 제목 아래에 글머리 기호(링크 + 짧은 설명)로 나열합니다. 하나뿐이면 목록을 생략하고 처음 언급하는 곳에 인라인으로 링크합니다.
  • 하위 페이지는 "Related resources" 섹션에서 상위와 형제 페이지로 링크합니다. 이 섹션은 페이지 끝에 두며, 상위 페이지에 대한 링크 하나와 직접 형제 페이지 각각에 대한 링크를 설명 없이 둡니다. 페이지가 상위 페이지의 README.md와 같은 폴더에 있으면 상위 페이지에 ./를 사용하고, 페이지 자체가 상위 한 단계 아래의 섹션 랜딩 페이지이면 ../를 사용합니다(상위 페이지 참조). 그 밖의 진짜 관련 있는 페이지는 재량으로 추가합니다.
  • 형제가 10개를 넘으면 형제 목록을 생략합니다. 상위 페이지만 링크합니다(상위 페이지의 "In this section"에 전체 목록이 있습니다).
  • 자신이 상위 페이지인 페이지는 둘 다 합니다. 하위 페이지용 "In this section"을 두고, 자신의 상위 및 형제 페이지용 "Related resources" 푸터도 둡니다. 한 단계 위와 옆으로만 링크하고 조부모 페이지로는 링크하지 않습니다.
  • 모든 페이지가 같은 단일 사실 템플릿을 따르는 평면적 참조 모음은 형제 링크를 생략합니다(예: 표현식 데이터 유형별 페이지 하나씩). "Related resources"에서 상위 페이지로만 링크합니다.
  • 같은 주제로 서로 연결된 페이지 군집을 다섯 개 이상 만드는 것을 목표로 합니다.
  • 본문에서는 의미 있는 첫 언급에만 링크합니다. 대상을 설명하는 앵커 텍스트를 사용하며(예: "click here"가 아니라 Configure the Schedule Trigger), 링크를 위해 문장을 추가하지 말고 주제에 대한 기존 언급을 재활용합니다. 링크는 섹션에 필요한 맥락을 대신할 수 없으므로, 그런 경우 핵심 사실을 다시 서술합니다(각 섹션을 자체 완결적으로 작성 참조).

기능 제공 범위#

기능의 제공 범위는 세 가지 방식으로 제한될 수 있습니다.

  • 요금제 또는 플랫폼: 어떤 n8n Cloud 요금제 또는 셀프 호스팅 에디션에서 제공되는지.
  • 버전: 어떤 n8n 버전에서 도입, 지원 중단 또는 제거되었는지.
  • Preview 상태: 아직 안정화 중인지, 변경될 수 있는지, 모든 사용자에게 배포되지 않았는지.

요금제, 플랫폼, 버전 제한은 하나의 문서화 체계를 공유합니다. Preview 상태는 다르게 동작하며 항상 별도로 문서화합니다.

요금제, 플랫폼, 버전 제한#

세 가지 범위 중 하나로 문서화합니다.

  • 페이지 또는 섹션: 페이지 제목 아래나 해당 제목 아래에 Feature availability라는 제목의 info hint를 둡니다. Feature availability hints를 참조하세요.
  • 인라인 또는 간단한 언급: 작은 옵션, 필드, 역할, 동작 옆의 짧은 메모이거나, 자체 제목 없이 본문에서 이름만 언급된 기능 또는 노드 전체입니다. 제한을 문장에 녹여 씁니다. 인라인 및 간단한 언급을 참조하세요.
  • 표 행: 여러 행 중 하나입니다. 제한을 설명 셀에 넣고, 여러 행이 서로 다르면 전용 칼럼을 둡니다. 표 행을 참조하세요.

Feature availability hints#

예시:

요금제와 버전 모두:

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

**Feature availability**

Environments are available on:

- **n8n Cloud:** Pro, Enterprise
- **Self-hosted:** Enterprise

Available from n8n 2.30.0.

</div>

버전만: 대상은 기능일 수도, 노드일 수도 있습니다.

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

**Feature availability**

Canvas Groups are available from n8n 2.28.0.

</div>

지원 중단 또는 제거에는 info가 아니라 warning을 사용합니다. 제거인 경우 문구를 바꿉니다(예: "N8N_RUNNERS_ENABLED removed from n8n 3.0"). 아래 예에서 대상은 설정입니다.

<div class="admonition warning"><div class="admonition-title">Warning</div>

**Feature availability**

`N8N_RUNNERS_ENABLED` is deprecated from n8n 2.0.

</div>

페이지 전체가 지원 중단되었거나 제거된 기능에 관한 것이라면 기본 deprecated 태그도 추가합니다(frontmatter의 태그 참조). deprecated는 status: 필드의 검증된 값이 아니므로 status: 필드는 추가하지 않습니다.

---
tags:
  - tag: deprecated
    primary: true
---

이 태그는 스페이스의 .gitbook/tags.yaml에 레이블 "Deprecated"와 색상 빨강이 정의되어 있어야 합니다.

규칙:

  • hint 스타일: 지원 중단이나 제거(독자가 조치해야 하는 경우)에는 warning, 그 외에는 info를 사용합니다. 두 가지를 합친 hint에는 warning을 사용합니다.
  • 본문에 대상을 명시합니다. hint 제목만으로는 무엇이 제공되는지 알 수 없고, 바깥의 제목에도 의존하지 않습니다. "available from n8n X.Y.Z"는 끊지 않고 그대로 씁니다. 버전만 다루는 경우 대체 대상을 밝힐 수 있습니다. 예: "The Chat Trigger node is available from n8n 1.24.0, replacing the Manual Chat Trigger node."
  • 플랫폼 글머리 기호: " <is/are> available on:"으로 시작합니다. 항상 두 플랫폼을 모두 명시합니다. 둘 다 제공되면 글머리 기호를 하나씩 둡니다. 하나만 제공되면 해당 글머리 기호 아래에 미제공 안내 줄을 둡니다("It isn't available on n8n Cloud."/"...self-hosted."). 다른 곳에서 조건부로만 제공되는 경우(예: 요청 시 제공) 미제공 안내 줄 대신 단서 줄을 둡니다(예: "On n8n Cloud Enterprise, contact n8n to enable it.").
  • 등급: 낮은 등급부터 높은 등급 순으로 쉼표로 구분하며 "and"는 쓰지 않습니다. Cloud: Starter, Pro, Enterprise. 셀프 호스팅: Community, Registered Community, Business, Enterprise. 정확한 대문자 이름을 사용하고 "Registered Community"는 줄이지 않고 풀어 씁니다.
  • "n8n Cloud"로 쓰고, 단독 "Cloud"는 쓰지 않습니다.
  • 플랫폼 전체: 모든 등급을 나열하지 말고 All plans/All editions로 씁니다. "All plans"에는 무료 체험이 포함되며(Pro와 동일), 무료 체험 자체는 나열하지 않고 체험 페이지에서만 다룹니다.
  • 글머리 기호 아래 순서: (1) 미제공/단서 줄, (2) 버전 문장, (3) 기능별 기타 단서.
  • 요금제 제한 없음(버전만, 지원 중단, 제거): 글머리 기호 없이 제목과 문장만 둡니다.
  • Compare plans and editions나 릴리스 노트로 링크하지 않습니다. 사실을 문장에 직접 서술하고, 필요하면 독자가 검색하도록 둡니다.

인라인 및 간단한 언급#

더 큰 기능 안의 작은 컨트롤, 옵션, 필드, 역할이나 자체 제목 없이 본문에서 이름만 언급된 기능/노드 전체에는 인라인 문구를 사용합니다. 페이지 전체 또는 섹션 전체에 걸친 제한에는 사용하지 않습니다(hint를 사용합니다).

  • "this feature"나 "this option"이 아니라 구체적인 대상의 이름을 씁니다. 맥락 없이도 단독으로 이해되어야 합니다.
  • 항목당 한 문장으로 씁니다. 요금제/플랫폼과 버전이 모두 해당되면 두 문장으로 쓰고, 요금제/플랫폼을 먼저 씁니다.
  • 두 플랫폼이 모두 중요하면 둘 다 언급합니다. 생략으로 미제공을 암시하지 않습니다.
  • 버전, 지원 중단 또는 제거는 간단하게 서술합니다("available from n8n X", "deprecated from n8n X"). hint의 "Available from" 도입 문구는 생략합니다.
  • 문장이 두 개를 넘거나 두 플랫폼 글머리 기호가 모두 필요하면 범위가 지정된 hint로 승격합니다.

컨트롤, 옵션, 필드, 역할의 경우:

The **Scopes** option is available on n8n Cloud Pro, Enterprise, and self-hosted Enterprise.

The **Legacy format** field is deprecated from n8n 2.30.0.

자체 제목이 없는 기능 또는 노드 전체의 경우 제한을 문장에 녹여 씁니다.

The Data table node (available from n8n 2.17.0) stores data between executions.

The environments feature (n8n Cloud Enterprise, self-hosted Enterprise) lets you promote workflows between instances.

표 행#

여러 행 중 하나에는 인라인 텍스트와 같은 어휘와 순서를 사용합니다. 제한을 설명 셀에 넣습니다.

Variable Type Default Description
N8N_RUNNERS_ENABLED (deprecated) Boolean false Whether task runners are enabled. Deprecated from n8n 2.0; you no longer need to set it.

또는 여러 행이 서로 다르면 전용 칼럼을 추가합니다.

Variable Available on Description
N8N_LDAP_ENABLED Self-hosted Business, Enterprise Whether LDAP sign-in is enabled.
N8N_SMTP_HOST All editions SMTP server hostname for outgoing email.

버전 표기#

두 가지 버전 유형#

n8n에는 서로 다른 두 가지 버전 번호가 있습니다. 독자가 어느 쪽인지 추측하게 두지 않습니다.

  • 인스턴스 버전: n8n 릴리즈의 3단계 시맨틱 버전(예: 2.30.0). 기능, 환경 변수, API, CLI 명령, 훅에 사용합니다.
  • 노드 버전: 노드의 버전으로, 보통 2단계입니다(예: 4.7). 노드에 한정된 사실에만 사용합니다.

본문에서 숫자만 쓰지 않고 한정어를 붙입니다. "version 2"가 아니라 "n8n 2.30.0" 또는 "node version 4.7"로 씁니다.

버전 번호 쓰기#

숫자 지침을 따르고, n8n 인스턴스 버전에는 다음을 추가로 적용합니다.

  • 제품 이름 + 숫자: n8n 2.30.0.
  • v 접두사를 붙이지 않습니다: "n8n v2.30.0"이 아닙니다.
  • "n8n" 뒤에 "version"을 붙이지 않습니다: "n8n version 2.30.0"이 아닙니다.
  • 본문에서는 인라인 코드 서식을 쓰지 않습니다: n8n 2.30.0이 아니라 n8n 2.30.0으로 씁니다. 버전이 실제 스니펫, 명령, 파일 경로에 나올 때만 코드 서식을 사용합니다. 예: n8n@2.30.0, Docker 태그, package.json 값.

Preview 상태#

Preview 기능은 사용할 수 있지만 아직 완성되거나 안정적이지 않으며 변경될 수 있습니다. "Preview"는 성숙도 레이블로서 대문자로 씁니다("is in Preview", "a Preview feature", "In Preview from n8n 2.20.0"). "beta"가 아니라 "Preview"를 사용합니다. 링크 미리보기, UI 미리보기 동작처럼 관련 없는 의미의 단어는 소문자로 둡니다. frontmatter와 태그 값은 산문이 아니라 문자 그대로의 식별자이므로 소문자로 유지합니다(status: preview, tag: preview).

페이지 또는 섹션: hint 제목은 **Feature availability**가 아니라 **Preview status**로 합니다. 안정성과 제공 범위는 서로 다른 질문이므로, 제공 범위 hint와 같은 레이블을 가진 두 번째 hint로 두지 않고 각각 별도의 hint를 둡니다. hint는 주변 제목과 별개로 훑어보게 되므로 노드나 기능의 이름은 제목이 아니라 아래 문장에 씁니다.

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

**Preview status**

The Data table node is in Preview and may change in future releases. Avoid relying on it in production workflows.

</div>

페이지 전체가 Preview 기능을 다룬다면 status: preview도 설정하고 기본 preview 태그를 추가합니다(frontmatter의 태그 참조).

---
status: preview
tags:
  - tag: preview
    primary: true
---

실제 사례는 Build and manage agents를 참조하세요.

인라인 또는 간단한 언급: 작은 컨트롤이거나, 자체 제목 없이 본문에서 이름만 언급된 기능 또는 노드 전체의 경우:

The **Streaming response** option is in Preview and may change in future releases.

The Data table node is in Preview and may change in future releases.
  • 도움이 되면 버전과 연결합니다: "In Preview from n8n 2.20.0".
  • Feature availability와 분리해 둡니다. 둘 다 해당되면 하나를 다른 하나에 녹이지 말고 쌓아 둡니다(hint + hint, 또는 문장 + 문장).
  • 인라인 메모가 한 문장을 넘는 경우: 페이지 또는 섹션 수준의 hint로 승격합니다.

Vale 린팅#

n8n은 Vale을 사용해 이 가이드의 규칙에 따라 문서를 린트합니다.

구성은 다음과 같습니다.

  • 리포지터리 루트에 있는 .vale.ini 파일. 구성을 담고 있습니다.
  • 스타일 정의를 담은 styles 디렉터리. 기성 스타일 라이브러리와 n8n 고유 스타일이 포함됩니다.
  • 모든 PR에서 Vale을 실행하고 위반 사항을 PR에 직접 보고하는 GitHub Action.

로컬 머신에서 Vale을 실행하려면 다음과 같이 합니다.

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

Frontmatter#

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

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

Frontmatter 예시:

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

기존 n8n Docs 페이지에서 contentType, nodeTitle, originalFilePath, originalUrl, url 같은 다른 frontmatter 필드를 볼 수 있습니다. 이 필드는 기존 페이지의 마이그레이션 관리를 위한 것입니다. 새 페이지에는 추가하지 않습니다.

태그#

시각적 태그는 페이지에 레이블로 렌더링되며, primary: true이면 사이드 메뉴에도 표시됩니다. 스페이스의 .gitbook/tags.yaml에 (레이블과 색상이) 정의되어 있어야만 렌더링됩니다. tags 배열에 객체로 추가합니다.

---
tags:
  - release
  - tag: preview
    primary: true
---

이 예시에서 시각적 태그는 tag: preview뿐입니다. release는 일치하는 .gitbook/tags.yaml 항목이 없는 일반 문자열이므로 아무것도 렌더링하지 않습니다. tags 배열에는 이처럼 아무 동작도 하지 않는 문자열을 실제 시각적 태그와 함께 둘 수 있으며, 이는 두 번째 시각적 태그가 아니라 별개의 것입니다.

  • 시각적 태그는 적용하기 전에 스페이스의 .gitbook/tags.yaml에 이미 정의되어 있어야 합니다. 있는지 확인하고, 없으면 추가합니다.
  • 시각적 태그는 레이블일 뿐입니다. 페이지의 설명 hint를 대체하지 않습니다. 상태가 무엇을 의미하는지는 hint에서 설명하고, 태그는 UI에서 표시만 합니다.
  • 문서에서 허용되는 시각적 태그는 현재 Deprecated(지원 중단된 기능에 관한 페이지 전체), Preview(Preview 기능에 관한 페이지 전체), Archived(더 이상 업데이트되지 않는 페이지) 세 가지입니다. 이 세 가지 외의 시각적 태그는 만들거나 사용하지 않습니다.

페이지 탐색#

각 스페이스는 루트에 사이드바를 정의하는 SUMMARY.md 파일을 둡니다. 어떤 페이지가 표시되는지, 어떤 순서인지, 어떻게 중첩되는지를 정의합니다. GitBook은 이 파일로 탐색을 구성하므로, 새 페이지는 SUMMARY.md에 추가하기 전까지 사이드바에 나타나지 않습니다. .md 파일을 만드는 것만으로는 충분하지 않습니다.

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

# 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으로 작성하며, 블록(콜아웃, 탭 및 기타 구조화된 페이지 요소)이라는 GitBook 전용 구성 요소를 함께 사용합니다. 아래 섹션에서 자주 쓰는 블록을 다룹니다.

Note

사용 가능한 모든 블록 유형의 Markdown 표현은 GitBook 문서를 참조하세요.

제목#

제목은 일반 Markdown(## Heading text)으로 문장형 대소문자(sentence case)로 작성합니다. GitBook이 제목 텍스트로 클릭 가능한 앵커를 자동으로 생성하므로 앵커 마크업을 직접 추가하지 않습니다.

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

## Heading text

이 태그는 앵커를 고정하므로, 나중에 제목 텍스트가 바뀌어도 제목으로 연결되는 링크가 계속 동작합니다. 제목을 고쳐 쓸 때는 앵커 태그를 유지해 기존 링크가 깨지지 않게 합니다.

링크#

외부 링크#

표준 Markdown 링크 구문을 사용합니다.

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

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

내부 링크#

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

같은 스페이스 내에서는 표준 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
대상 위치 링크 구문
같은 하위 폴더, 같은 스페이스 [link text](another-page.md)
상위 페이지, 상위가 README.md인 경우 [link to a parent page](./)
상위 페이지, 상위가 이름이 있는 페이지인 경우(이 폴더에 README.md가 없음, 예: connect-to-n8n-mcp-server.md) [link to a parent page](connect-to-n8n-mcp-server.md), ./가 아니라 파일로 직접 링크
상위 페이지, 현재 페이지 자체가 섹션 랜딩 페이지(README.md)인 경우 [link to a parent page](../), ./는 상위가 아니라 자기 자신을 가리키기 때문
다른 하위 폴더, 같은 스페이스 [link to a page](../manage-workflows/export-import.md)
다른 스페이스 [link to a page](https://app.gitbook.com/s/<spaceId>/<page-path>)

상위 페이지#

./와 ../는 디렉터리를 가리키는 참조로, GitBook이 어떤 상대 깊이에서든 해당 폴더의 README.md로 기본적으로 해석합니다. ./는 현재 폴더의 랜딩 페이지를 가리키며, 현재 페이지가 그 폴더 안의 하위 페이지일 때만 상위 페이지가 됩니다. 현재 페이지 자체가 섹션 랜딩 페이지(README.md)이면 ./는 자기 자신을 가리키므로, 한 단계 위의 실제 상위 페이지로 가려면 ../를 사용합니다.

다른 스페이스의 페이지로 링크#

상대 파일 경로는 스페이스 안에서만 해석됩니다. GitBook은 스페이스 사이의 링크를 파일 경로가 아니라 페이지 참조로 해석하므로, 다른 스페이스로 향하는 ../../ 경로는 동작하지 않습니다. 대신 대상 페이지의 GitBook URL로 링크합니다.

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

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

  • <spaceId>: 대상 페이지가 있는 스페이스의 ID. SPACE_INDEX.md에서 확인합니다.
  • <page-path>: 스페이스 폴더 안에서의 대상 페이지 경로이며 .md 확장자를 뺀 것입니다. README.md는 해당 폴더 경로가 됩니다(예: host-n8n/configure-n8n/README.md는 host-n8n/configure-n8n).

예를 들어 administer 스페이스의 페이지에서 deploy 스페이스의 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)

이 형식은 다른 스페이스의 페이지에만 사용합니다. 이미 편집 중인 스페이스의 페이지에는 상대 .md 링크를 사용합니다. GitBook은 두 형식을 모두 렌더링하지만, 스페이스 URL은 GitBook의 이름 변경 추적에서 빠지므로 누군가 대상 페이지를 이동하면 링크가 깨집니다. 또한 GitBook 미리보기에서 리비전을 벗어나, 변경 사항이 아니라 게시된 콘텐츠를 기준으로 해석됩니다. internal-links CI 검사는 이를 same-space-absolute로 보고합니다.

docs/ 아래의 각 최상위 폴더는 별도의 스페이스입니다. 대상 스페이스의 스페이스 ID는 리포지터리 루트의 SPACE_INDEX.md에서 찾을 수 있으며, 이 파일은 각 스페이스의 GitBook Git Sync 설정으로 매일 생성됩니다.

URL을 직접 만들고 싶지 않다면 GitBook에서 대상 페이지를 열고 링크를 복사합니다. GitBook에 접근할 수 없으면 해당 페이지의 게시된 https://docs.n8n.io/... 주소를 사용합니다.

이미지#

이미지는 텍스트를 보완하는 용도이며, 이미지만으로 정보를 전달하지 않습니다(이유는 Agent-friendly docs를 참조하세요). 독자가 해야 하거나 알아야 하는 모든 내용은 본문에 씁니다.

  • 모든 지시는 텍스트로 씁니다. 스크린샷은 화면이 어떻게 생겼는지 보여 줄 수 있지만, 단계("Select Add trigger, then choose On schedule")는 글로 써야 합니다. 설정, 값, 메뉴 경로, 클릭 대상의 유일한 사본을 이미지 안에만 두지 않습니다.
  • 텍스트를 스크린샷으로 찍지 않습니다. 독자가 복사하고 에이전트가 읽을 수 있도록 코드, 명령, 오류 메시지, 구성 값은 코드 블록이나 표에 넣습니다. 터미널이나 코드 편집기의 그림을 붙여 넣지 않습니다.
  • 스크린샷은 지시가 아니라 확인용으로 취급합니다. 글로 쓴 단계를 대체하지 않고 함께 두어, 독자가 방향을 잡거나 올바른 위치에 있는지 확인하게 하는 데 사용합니다.

각 스페이스에는 모든 이미지를 담는 단일 폴더가 있으며, 해당 스페이스 루트의 .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

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

편집 중인 페이지를 기준으로 한 상대 경로로 이미지를 참조합니다. 스페이스 내 어느 페이지에서든 먼저 스페이스 루트까지 올라간 다음 .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로 씁니다.

인라인 아이콘

UI 요소가 아이콘으로만 표시될 때(예: 보이는 텍스트 레이블이 없는 메뉴) HTML <img> 태그와 data-size="line"을 사용해 인라인으로 삽입하면, 블록 이미지가 아니라 텍스트 높이로 렌더링됩니다.

select **Workflow menu** <img src="/images/docs/n8n/.gitbook/assets/three-dots-horizontal.png" alt="Workflow menu icon" data-size="line">
  • 용어를 굵게 표시하고 <img> 태그는 굵게 표시하지 않습니다.
  • 대체 텍스트는 굵게 표시한 용어와 일치하도록 " icon"으로 설정합니다.
  • 어떤 아이콘 파일이 어떤 명명된 요소에 대응하는지는 용어와 명칭을 참조하세요.

동영상#

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

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

코드 예제#

공백이 아니라 탭을 사용합니다. n8n 노드 린터가 이 규칙을 강제하므로 중요합니다. 'Creating nodes' 섹션의 코드 샘플은 사용자의 노드에 복사될 수 있고, 공백을 사용하면 린터 오류가 발생합니다.

구문 강조를 위해 언어 식별자를 붙인 펜스 코드 블록을 사용합니다.

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

// Your code here

GitBook은 선택적 코드 블록 설정을 지원합니다. 독자에게 도움이 되면 제목, 줄 바꿈 또는 줄 번호를 추가합니다.


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


// Your code here

기능마다 실제 사용 예제 제시#

코드, 표현식 또는 구성 인터페이스가 있는 모든 항목에는 실제 사용 예제를 포함합니다. 독자와 코딩 에이전트는 서술보다 예제에 더 많이 의존합니다.

  • 일반적인 경우를 먼저 다루고, 그다음 문제가 생기는 경우를 다룹니다. 간단한 경로를 보여 준 다음 예외 상황(빈 입력, 페이지네이션, 속도 제한)과 실패(독자가 보게 되는 오류와 해결 방법)를 보여 줍니다.
  • 양보다 다양성을 중시합니다. 서로 다른 점을 보여 주는 예제 세 개가 거의 같은 예제 여섯 개보다 낫습니다. 채우려고 늘리지 말고 다양하게 구성합니다.
  • 의도를 인라인 주석으로 설명합니다. 각 예제가 무엇을 하고 왜 하는지 밝혀서 다른 지시로 오해되지 않게 합니다.
  • 모든 자리 표시자에 레이블을 붙입니다. 텍스트 서식에 맞춰 하이픈으로 연결한 단어를 꺾쇠괄호 안에 씁니다. YOUR_KEY나 실제 값이 아니라 <your-api-key> 또는 로 씁니다.
  • 제약 조건은 서술하지 말고 구조화합니다. 매개변수, 기본값, 한도는 단락이 아니라 표나 스키마 블록에 넣습니다.

잘못된 예제를 보여 줄 때는 옆에 올바른 예제를 함께 둡니다. 망가진 스니펫을 홀로 두면 그대로 복사됩니다.

Hint#

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

  • info는 일반적인 메모, 눈에 띄게 하려는 정보, 기능 제한 상자(특정 플랫폼이나 요금제 등급으로 제한된 기능)에 사용합니다.
  • warning은 위험이나 예상치 못한 동작이 있는 경우에 사용합니다.
  • danger는 보안 위험이 큰 경우(예: 로컬 n8n 인스턴스로 터널을 여는 경우)나 파괴적인 경우(사용자가 잘못 수행하면 데이터를 영구적으로 잃을 수 있는 경우)에 사용합니다.
  • success는 긍정적인 확인이나 팁에 사용합니다. 드물게 사용합니다.

Hint를 남용하지 않습니다. 많이 사용하면 효과가 떨어집니다.

다음 hint 구문을 사용합니다.

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

Some hint content.

</div>
Note

Some hint content.

hint에 헤더 블록(제목)을 추가하려면 hint의 첫 줄에 헤더 블록을 추가합니다.

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

## This is the hint title/heading

Some hint content.

</div>
Note

This is the hint title/heading#

Some hint content.

접을 수 있는 블록#

hint와 비슷하지만 접혀 있습니다. 사용자가 클릭해서 펼칩니다. 그대로 두면 페이지가 어수선해질 보충 상세 내용에 사용합니다.

접을 수 있는 콘텐츠는 표준 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.

탭 콘텐츠#

콘텐츠가 외부 요인(플랫폼, 코딩 언어 등)에 따라 달라지는 경우 탭으로 구분하면 사용자가 자신에게 해당하는 콘텐츠만 볼 수 있어 유용할 수 있습니다. 탭 섹션은 찾기 쉬움에 영향을 줄 수 있으므로 아껴서 사용합니다.

탭은 짧은 병렬 변형에만 사용합니다(이유는 Agent-friendly docs를 참조하세요). 탭 블록 전체를 한 화면(결합 약 3,000자) 이내로 유지합니다. 변형이 이 범위를 넘어서면(각각 전체 절차가 필요하거나 사소하지 않은 변형이 네 개 이상이면) 탭을 쓰지 말고 각 변형에 페이지에서 자체 제목을 부여해 각각이 깔끔하고 자체 완결적인 섹션이 되게 합니다. 결합한 페이지가 페이지 길이 지침을 초과하거나 변형 집합이 열려 있는 경우에만 변형마다 페이지를 나눕니다. 공통 설정과 설명은 변형마다 반복되지 않도록 탭 블록 밖에 둡니다.

탭 콘텐츠는 다음과 같이 표시합니다.


**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 구문에 따라 렌더링됩니다. 목록을 추가하려면 다음과 같이 합니다.

  • Item one
  • Another item
  • Still more items

두 번째 탭

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

임베드된 워크플로#

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>

템플릿 API URL은 게시된 템플릿의 ID를 https://api.n8n.io/workflows/templates/ 뒤에 붙여 찾습니다.