문체#

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"을 씁니다.

용어와 명명#

같은 개념에는 어디서나 같은 용어를 사용하고, 그럴듯한 동의어보다는 공식 제품 용어를 우선합니다(예: "워크플로 활성화(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 도구 모두 자체 완결적이고 heading으로 구조화된 페이지에서 가장 잘 작동합니다. 검색과 문서 어시스턴트를 구동하는 AI 도구는 ##와 ### heading을 기준으로 콘텐츠를 청크로 나누어 한 번에 한 섹션씩 가져옵니다.

길이#

• 적정 범위: 약 1,500자에서 20,000자(250~3,000단어) 사이입니다. 사람에게는 훑어보기 좋은 섹션으로 읽히고, AI 도구에게는 깔끔하게 검색 가능한 청크가 됩니다.
• 약 1,500자 미만이면 병합합니다. 이보다 작은 페이지나 섹션은 유용한 청크 크기에 미치지 못합니다. AI 검색은 이를 관련 없는 이웃 콘텐츠와 병합해버리며, 하나의 주제를 여러 작은 페이지로 지나치게 쪼개면 답변 품질이 눈에 띄게 낮아집니다. 짧은 토막글은 상위 페이지나 형제 페이지로 합치세요.
• 약 25,000자를 넘으면 분할합니다. 페이지가 여러 콘텐츠 유형(개념, 방법, 참조)을 함께 다루거나, 한 섹션이 끝없이 커지는 경우(클라이언트별 예시 목록 등)도 마찬가지입니다.
• 약 50,000자를 절대 넘기지 마세요. 에이전트는 이보다 긴 페이지를 잘라내므로, 한도를 넘는 내용은 에이전트에게 보이지 않습니다.

분할 방법#

• 임의로 길이 기준이 아니라 유형이나 작업 경계(개념, 방법, 참조, 예시)를 따라 나눕니다. 이는 독자가 탐색하는 방식과 일치하며 각 청크가 하나의 주제만 다루도록 유지합니다.
• 관련된 사실들은 한 페이지에 유지합니다(한 범주의 모든 환경 변수, 한 노드의 모든 매개변수 등). AI 검색은 인접한 콘텐츠를 함께 유지하므로, 근접성이 문맥을 보존합니다.

각 섹션을 자체 완결적으로 유지하세요#

주변 섹션에 의존하는 섹션은 단독으로 검색될 때 그 문맥이 빠진 채로 전달되어, 에이전트가 빈틈을 추측으로 메우게 됩니다. 각 섹션을 혼자 접한 독자도 이해할 수 있도록 작성하세요:

• 설명적이고 문장체인 heading을 작성합니다. heading은 AI 검색이 검색해오는 단위이며, 종종 페이지의 나머지 부분 없이 단독으로 가져와집니다. 그러니 섹션의 주제를 온전히 담아 이름 붙이세요: "Configuration"이 아니라 "Configure the Schedule Trigger"처럼요.
• 각 섹션이 그 자체로 이해되도록 만듭니다. 다시 참조하는 대신, 독자에게 필요한 핵심 문맥을 다시 진술하세요. "위에서 언급했듯이", "이전 섹션에서 설명한 대로", "아래를 참고하세요" 같은 표현은 피하세요. 이 섹션을 순서와 무관하게 가져오는 에이전트나 검색을 통해 도착한 독자는 그런 참조를 따라갈 수 없습니다.
• 다시 진술하되, 중복하지 마세요. 섹션에 필요한 한두 가지 사실만 반복하고, 문단 전체를 반복하지 마세요. 두 섹션이 같은 긴 설명을 필요로 한다면, 이는 두 섹션이 하나의 heading 아래 합쳐져야 한다는 신호입니다. 페이지가 간결하게 유지되도록 재진술은 짧게 유지하세요(쉬운 언어 참고).

관련 페이지, 사전 요구사항, 다음 단계에 링크하세요#

각 페이지를 같은 주제의 다른 페이지들과 연결하세요. 명시적이고 설명적인 링크는 에이전트가 URL을 추측하는 대신 경로를 곧바로 따라갈 수 있게 하며, 페이지들을 하나의 주제 클러스터로 묶어 AI 검색이 이를 깊이의 신호로 읽게 합니다.

• 최소한 사전 요구사항과 다음 단계는 항상 링크하세요.
• 부모와 자식을 양방향으로 링크하세요. 개요나 섹션 랜딩 페이지는 모든 자식 페이지를 나열하고 링크하며, 각 자식 페이지는 ./로 부모 페이지에 다시 링크합니다.
• 같은 주제로 상호 연결된 페이지 다섯 개 이상의 클러스터를 목표로 하세요. AI 검색은 독립된 페이지보다 서로 연결된 클러스터를 훨씬 더 많이 인용합니다.
• 본문에서 처음으로 의미 있게 언급되는 지점에 링크하세요. 대상을 명확히 나타내는 설명적인 앵커 텍스트를 사용하세요: "여기를 클릭"이 아니라 Configure the Schedule Trigger처럼요. 첫 언급에만 링크하고, 모든 언급에 링크하지 마세요.
• 별개의 주제에는 링크하되, 부족한 문맥을 메우기 위해 링크하지 마세요. 링크는 이 섹션에 필요한 문맥을 대신할 수 없습니다. 링크된 페이지 없이는 섹션을 이해할 수 없다면, 링크 대신 핵심 사실을 다시 진술하세요(각 섹션을 자체 완결적으로 유지하세요 참고).

버전 관리와 출시 상태#

많은 기능, 설정, 노드는 특정 n8n 릴리즈에 연결되어 있거나 preview나 deprecated 같은 상태를 가집니다. 특정 설치본이 어떤 기능을 지원하는지 독자가 알 수 있도록 버전과 상태를 일관되게 표기하세요.

두 가지 버전 유형#

n8n에는 두 가지 별도의 버전 번호가 있습니다. 독자가 어느 쪽을 말하는지 추측하게 두지 마세요.

• 인스턴스 버전: 2.30.0처럼 세 부분으로 이루어진 semver로 표기하는 n8n 릴리즈입니다. 기능, 환경 변수, API, CLI 명령, hook에 사용합니다.
• 노드 버전: 보통 4.7처럼 두 부분으로 이루어진 노드의 버전 번호입니다. 노드 고유의 사실에만 사용합니다.

본문에서는 단독 숫자에 한정어를 붙이세요: 그냥 "version 2"가 아니라 "n8n 2.30.0" 또는 "node version 4.7"처럼 씁니다.

버전 번호 표기법#

숫자 가이드를 따르고, n8n 인스턴스 버전에는 다음 규칙을 추가로 따르세요:

• 제품명과 숫자를 사용합니다: n8n 2.30.0.
• v 접두사를 붙이지 마세요: "n8n v2.30.0"이 아니라 "n8n 2.30.0"으로 씁니다.
• "n8n" 뒤에 "version"이라는 단어를 쓰지 마세요: 숫자만으로도 명확합니다. "n8n version 2.30.0"이 아니라 "n8n 2.30.0"으로 씁니다.

마커를 어디에 배치할지#

가용성, 상태, 또는 지원 중단 마커는 그것이 설명하는 범위에 배치하세요:

• 기능에 관한 페이지 전체: 페이지 제목 바로 아래에 hint(콜아웃)를 둡니다.
• 페이지 내 한 섹션: 그 섹션의 heading 바로 아래에 hint를 둡니다.
• 자체 heading 없이 지나가듯 언급되는 기능: hint를 사용하는 대신 문장에 녹여 넣으세요. 예를 들어 "Data table 노드(n8n 2.17.0부터 제공)는 실행 간 데이터를 저장합니다" 또는 "tablePrefix 옵션은 피하세요. n8n 2.0부터 지원 중단되었습니다"처럼 씁니다.
• 표의 단일 행(환경 변수 하나, hook 하나): 설명 셀에 "(n8n 2.17.0부터 제공)"처럼 넣습니다. 여러 행이 다르다면 전용 열을 추가하세요.

hint 스타일을 상태에 맞추세요:

예:

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

**Available from n8n 2.17.0**

</div>

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

**Deprecated from n8n 2.0**

Use `publish:workflow` instead. n8n removes `update:workflow` in 3.0.

</div>

Preview 기능 표시하기#

preview 기능은 사용은 가능하지만 아직 완전하거나 안정적이지 않으며 변경될 수 있습니다. "Preview"는 기능의 성숙도 라벨입니다. 기능 상태를 설명할 때는 "beta"가 아니라 이 용어를 사용하세요. "beta"는 릴리즈 채널, 버전 트랙, 액세스 프로그램(베타 릴리즈, 베타 Cloud 인스턴스, 비공개 베타)에만 사용하세요.

적절한 범위에 독자에게 그 상태가 무엇을 의미하는지 설명하는 info hint를 추가하세요:

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

**This feature is in preview**

Preview features may change in future releases. Avoid relying on them in production workflows.

</div>

• 도움이 될 때는 버전과 연결하세요: "n8n 2.20.0부터 preview로 제공".

기능이 제공되기 시작한 시점 표시하기#

위의 배치 규칙을 따르고, 다음도 함께 따르세요:

• 이전 버전에 미치는 영향이 있다면 명시하세요: "이전 버전에서는 대신 OLD_VAR을 사용하세요".
• 가용성과 플랜 또는 플랫폼 제한을 구분하세요. 티어 제한(Cloud, Enterprise, 셀프 호스팅)은 버전 마커와 별도로 자체 info hint에 담으세요.

지원 중단과 제거 표시하기#

지원 중단된 기능은 여전히 동작하지만 사용해서는 안 됩니다. 제거된 기능은 더 이상 존재하지 않습니다. 위의 배치 규칙을 따르고, 다음도 함께 따르세요:

• 알고 있다면 대체 기능과 제거 버전을 명시하세요: "대신 publish:workflow를 사용하세요. n8n은 3.0에서 update:workflow를 제거합니다". 제거 일정이 없다면 그렇게 밝히세요: "제거 일정은 아직 없습니다".

• 무언가를 지원 중단하거나 제거하는 버전은 항상 명시하세요. "곧" 또는 "가까운 시일 내"처럼 모호한 시기 표현을 쓰지 마세요.

• 표의 지원 중단 항목에는 식별자에 (deprecated)를 태그하고 설명에 버전을 명시하세요. 예:

  Variable	Type	Default	Description
  N8N_RUNNERS_ENABLED (deprecated)	Boolean	false	태스크 러너 활성화 여부입니다. n8n 2.0부터 지원 중단되어 더 이상 설정할 필요가 없습니다. 1.x에서는 여전히 필요하며, true로 설정해야 합니다.

지원 중단, 제거, 버전별 노드#

노드 버전 관련 사실은 한 곳에 모여 있습니다: 지원 중단 및 버전별 노드. 이 페이지는 코드베이스로부터 자동으로 갱신됩니다.

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/... 주소를 사용하세요.

이미지#

이미지는 텍스트를 보완할 뿐, 그 자체로 정보를 전달하지는 않습니다. 에이전트와 스크린 리더는 이미지의 실제 그림이 아니라 대체 텍스트와 파일 경로만 받으므로, 독자가 해야 할 일이나 알아야 할 내용은 반드시 본문에 담아야 합니다:

• 모든 지침을 텍스트로 작성합니다. 스크린샷은 화면이 어떻게 생겼는지 보여줄 수 있지만, 단계("Add trigger를 선택한 다음 On schedule을 선택합니다")는 반드시 글로 적어야 합니다. 설정값, 값, 메뉴 경로, 클릭 대상이 이미지 안에만 존재하도록 두지 마세요.
• 텍스트를 스크린샷으로 찍지 마세요. 코드, 명령어, 오류 메시지, 구성 값은 코드 블록이나 표에 넣어 독자가 복사할 수 있고 에이전트가 읽을 수 있도록 합니다. 터미널이나 코드 편집기의 그림을 붙여넣지 마세요.
• 스크린샷은 지침이 아니라 확인용으로 다루세요. 작성된 단계와 함께 독자가 방향을 잡거나 올바른 위치에 있는지 확인하는 용도로 사용하고, 단계를 대신하지 않도록 합니다.

각 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

각 기능마다 실제 동작하는 예시를 보여주세요#

코드, 표현식, 구성 관련 내용이 있다면 실제로 동작하는 예시를 포함하세요. 독자와 코딩 에이전트는 산문보다 예시에 더 많이 의존합니다.

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

잘못된 예시를 보여줄 경우, 그 옆에 올바른 예시를 나란히 배치하세요. 혼자 남겨진 잘못된 코드 조각은 그대로 복사되기 쉽습니다.

힌트#

힌트(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)에 영향을 줄 수 있으므로 신중히 사용하세요.

탭은 짧은 병렬 변형에만 사용하세요. 독자는 하나의 변형만 보지만 AI 도구는 모든 변형을 읽으므로, 길거나 수가 많은 변형은 페이지를 비대하게 만듭니다. 전체 탭 블록을 합쳐서 화면 한 개 분량(약 3,000자) 이내로 유지하세요. 변형이 이를 넘어서면(각각이 전체 절차이거나, 사소하지 않은 변형이 네 개 이상인 경우) 탭을 없애고 각 변형에 페이지 내 고유한 heading을 부여해, 각각이 깔끔하고 자체 완결적인 섹션이 되도록 하세요. 합쳐진 페이지가 페이지 길이 가이드를 초과하거나 변형의 개수가 정해져 있지 않을 때만 변형별로 별도 페이지로 분할하세요. 공유되는 설정과 설명은 탭 블록 밖에 두어 변형마다 반복되지 않도록 하세요.

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

**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을 찾을 수 있습니다.