Obsidian 문서는 이 페이지의 스타일 가이드를 따라요. 이 가이드는 업계 모범 사례, 특히 [Google 개발자 문서 스타일 가이드](https://developers.google.com/style)와 [Microsoft 스타일 가이드](https://learn.microsoft.com/en-us/style-guide/)를 바탕으로 정리했어요. 여기에서 다루지 않는 예외적인 경우에는 해당 외부 가이드를 보조 참고 자료로 활용하세요. > [!tip]- 기여하기 > 대부분의 문서는 이 스타일 가이드가 만들어지기 전에 작성되었어요. > > 이 스타일 가이드를 위반하는 내용을 발견하면 [이슈를 생성](https://github.com/obsidianmd/obsidian-docs/issues/new)하고 [obsidianmd/obsidian-docs](https://github.com/obsidianmd/obsidian-docs)에 풀 리퀘스트를 제출해 주세요. ## 용어 및 문법 ### 언어 스타일 영어 원문은 전 세계 사용자가 더 쉽게 이해할 수 있고 [[#번역]]에도 도움이 되도록 [Global English](https://docs.openedx.org/en/latest/documentors/references/doc_english_writing.html)를 사용하는 것을 권장해요. 핵심 원칙은 다음과 같아요: - 관용구 및 문화별 표현을 피해요 - 능동태와 직접적인 문장 구조를 사용해요 - 복잡한 용어보다 간단하고 일반적인 단어를 선호해요 - 암시하기보다 명시적으로 표현해요 - 철자 규칙은 미국 영어를 사용해요 (예: 'organise'가 아닌 'organize'). ### 한국어 문체 한국어 도움말 문서의 기본 문체는 차분한 `해요체`예요. - 설명은 실용적이고 직접적으로 작성해요. - 수사적인 질문, 과장된 표현, 설득하는 말투는 피하세요. - 제목에는 가능하면 문장 끝맺음을 넣지 마세요. - 문서 전반에서 용어를 일관되게 사용하세요. 예를 들어 `사용자 지정`, `타사`를 선호해요. - `해요체`를 사용하더라도 대화체나 마케팅 문구처럼 쓰지 마세요. ### 용어 - "hotkey"보다 "keyboard shortcut(키보드 단축키)"를 선호해요. 특정 기능을 지칭할 때는 Hotkey를 사용해요. - 모바일에서는 "Obsidian 앱", 데스크톱에서는 "Obsidian 애플리케이션"을 선호해요. - "synchronise" 또는 "synchronising"보다 "sync(동기화)" 또는 "syncing(동기화)"을 선호해요. - "search query"보다 "search term(검색어)"을 선호해요. - 섹션을 소개하는 텍스트를 지칭할 때 "header"보다 "heading(제목)"을 선호해요. - "max"보다 "maximum(최대)", "min"보다 "minimum(최소)"을 선호해요. ### 제품 이름 Obsidian 제품 이름은 "Obsidian"으로 시작해요. 예를 들어 "Obsidian Publish"와 "Obsidian Sync"예요. 문단이 지나치게 반복적이 되면 이후 언급에서 짧은 형태를 사용할 수 있어요. 예를 들어: _기기별 설정을 허용하기 위해 Obsidian Sync는 자체 설정을 동기화하지 않아요. 각 기기에서 Sync를 별도로 설정해야 해요._ ### UI 및 상호작용 - 버튼 텍스트를 나타낼 때 **굵게**를 사용해요. - "tap(탭)" 또는 "click(클릭)"보다 "select(선택)"를 선호해요. - 모바일 전용 지침의 경우, "클릭"을 사용할 수 없는 터치 상호작용을 설명할 때 "탭"을 사용할 수 있어요. - "side bar"보다 "sidebar(사이드바)"를 선호해요. - 명령이나 작업을 지칭할 때 "invoke(호출)"와 "execute(실행)"보다 "perform(수행)"을 선호해요. 연속된 여러 UI 상호작용을 지칭할 때는 → (U+2192) 기호를 사용해요. 예를 들어, "**[[설정]] → 커뮤니티 플러그인**". ### 노트, 파일 및 폴더 - 보관함의 Markdown 파일을 지칭할 때 "노트"를 사용해요. - Markdown 이외의 파일 확장자를 지칭할 때 "파일"을 사용해요. - "note title(노트 제목)"보다 "note name(노트 이름)"을 선호해요. - "current note(현재 노트)"보다 "active note(활성 노트)"를 선호해요. - "directory(디렉토리)"보다 "folder(폴더)"를 선호해요. - 파일 콘텐츠의 데이터 형식을 구체적으로 지칭하는 경우가 아니라면 "file format(파일 형식)"보다 "file type(파일 유형)"을 선호해요. 노트 간 이동 시, 대상이 숨겨져 있으면 "열기"를, 원본과 대상 노트가 모두 별도의 분할 화면에 열려 있으면 "전환"을 사용해요. ### 설정 참조 문서 가능한 경우, 모든 설정은 Obsidian 내에서 설명 텍스트를 통해 문서화해야 해요. 다음의 경우가 아니라면 Obsidian 도움말에서 특정 설정을 문서화하는 것을 피하세요: - 사용 방법과 시기에 대한 더 심층적인 지식이 필요한 경우. - 일반적으로 잘못 사용되거나 자주 질문이 올라오는 경우. - 사용자 경험을 *크게* 변경하는 경우. 특정 설정에 대한 주의를 환기하고 싶다면 팁 콜아웃 사용을 고려하세요. ### 방향 용어 영어 문서에서 방향 용어를 형용사로 사용할 때는 하이픈으로 연결해요. 방향이 명사로 쓰일 때는 하이픈을 사용하지 않아요. **권장:** - 왼쪽 하단 모서리에서 **[[설정]]**을 선택해요. - 왼쪽 하단에서 **[[설정]]**을 선택해요. **비권장:** - 왼쪽 하단 모서리에서 **[[설정]]**을 선택해요. (형용사처럼 쓰면서 하이픈이 없음) - 왼쪽 하단에서 **[[설정]]**을 선택해요. (명사처럼 쓰면서 하이픈이 있음) "top-left"와 "top-right"보다 "upper-left(왼쪽 상단)"와 "upper-right(오른쪽 상단)"를 선호해요. 설정을 지칭할 때 방향을 나타내지 마세요. 설정 컨트롤의 위치는 기기에 따라 달라요. **권장:** - **원격 보관함 선택** 옆에서 **선택**을 선택해요. **비권장:** - **원격 보관함 선택** 오른쪽에서 **선택**을 선택해요. UI 요소에서 수직 방향을 설명할 때 공간적 관계를 나타내기 위해 "위"와 "아래"를 사용해요. 다른 맥락에서 모호할 수 있는 "위로"와 "아래로"는 피해요. **권장:** - 검색 상자는 파일 목록 위에 나타나요. - 추가 옵션은 아래에서 사용할 수 있어요. **비권장:** - 검색 상자는 파일 목록에서 위쪽에 있어요. - 더 많은 옵션은 아래쪽에 있어요. ### 지침 가이드 이름, 섹션 제목, 단계별 지침에는 명령문을 사용해요. 명령문은 간결하고 행동 지향적이므로 지침을 따르는 사용자에게 더 직관적이에요. - "Setting up"보다 "Set up(설정하기)"을 선호해요 - "Moving a file"보다 "Move a file(파일 옮기기)"을 선호해요 - "Importing your notes"보다 "Import your notes(노트 들여오기)"를 선호해요 ### 문장형 대소문자 영어 제목, 버튼, 타이틀에는 *title case*보다 *sentence case*를 선호해요. UI 요소를 참조할 때는 항상 실제 UI에 표시된 대소문자를 그대로 사용하세요. **권장:** - Obsidian의 데이터 저장 방식 **비권장:** - How Obsidian Stores Data ### 예시 무의미한 용어보다 현실적인 예시를 선호해요. **권장:** - `task:(call OR schedule)` **비권장:** - `task:(foo OR bar)` ### 키 이름 및 키보드 단축키 키보드 키와 단축키를 지칭할 때 일관된 표기법을 사용해요. **개별 키 이름:** 키보드의 문자를 이름으로 지칭할 때는 이름 바로 뒤에 괄호 안에 문자를 추가해요. **권장:** - 대시를 추가하려면 하이픈(-) 키를 눌러요. - 검색하려면 물음표(?)를 사용해요. **비권장:** - 대시를 추가하려면 하이픈 키를 눌러요. - 검색하려면 ?를 사용해요. - 단어 앞에 `-`를 추가해요. **키보드 단축키:** 키보드 단축키는 더하기 기호 주위에 공백 없이 서식을 지정해요. 단축키가 운영 체제 간에 다른 경우 둘 다 명시해요. **권장:** - 실행 취소하려면 `Ctrl+Z` (Windows) 또는 `Command+Z` (macOS)를 눌러요. - 이 창을 닫으려면 `Escape`를 눌러요. - 필드 간 이동하려면 `Tab`을 사용해요. **비권장:** - 실행 취소하려면 `Cmd+Z`를 눌러요. - 실행 취소하려면 `Ctrl + Z` (공백 포함)를 눌러요. - 실행 취소하려면 `Ctrl/Cmd+Z`를 눌러요. 모든 플랫폼에서 동일한 단축키의 경우 OS를 명시할 필요가 없어요. 단축키가 플랫폼별로 다른지 확실하지 않은 경우 안전을 위해 OS를 명시해요. Windows와 Linux는 일반적으로 동일한 단축키를 사용해요. ### Markdown Markdown 블록 사이에 빈 줄을 사용해요: **권장:** ```md # 제목 1 이것은 섹션이에요. 1. 첫 번째 항목 2. 두 번째 항목 3. 세 번째 항목 ``` **비권장:** ```md # 제목 1 이것은 섹션이에요. 1. 첫 번째 항목 2. 두 번째 항목 3. 세 번째 항목 ``` **목록에서의 em 대시:** 글머리 기호 목록에서 굵은 용어와 설명을 구분할 때 em 대시(—)를 사용해요. 링크가 있는 단순한 중첩 글머리 기호 목록에서는 em 대시를 사용하지 않아요. **권장:** - **보기 메뉴** — 보기를 생성, 편집 및 전환해요. - **값 계산** — 가격을 추가하고, 합계를 계산하거나, 수학 연산을 수행해요. **비권장:** - [[베이스 생성]] — 베이스를 만들고 임베드하는 방법을 알아봐요. ### 이미지 이미지 또는 화면 크기를 설명할 때 "**너비** x **높이** 픽셀"을 사용해요. **예시:** 권장 이미지 크기: 1920 x 1080 픽셀. ## 정보 구조 ### 콜아웃 유형 특정 유형의 정보를 강조하기 위해 콜아웃을 전략적으로 사용해요: **팁** (`[!tip]-`) - 사용자의 워크플로를 향상시키는 실용적인 조언이나 모범 사례예요. 단축키, 해결 방법 또는 필수적이지 않지만 도움이 되는 정보에 사용해요. 이 콜아웃은 접힌 상태로 시작해요. **정보** (`[!info]+`) - 추가적인 맥락, 배경 정보 또는 설명이에요. 이해를 돕지만 작업을 완료하는 데 필수적이지 않은 정보에 사용해요. 이 콜아웃은 펼쳐진 상태로 시작해요. **경고** (`[!warning]+`) - 데이터 손실, 오류 또는 의도하지 않은 결과를 방지하는 중요한 주의사항이에요. 진정으로 위험한 상황에서만 드물게 사용해요. 이 콜아웃은 절대 접혀서는 안 돼요. **예시** (`[!example]-`) - 일반적인 부연 설명이나 보충 세부 사항이에요. 일부 사용자에게 관련이 있을 수 있는 부수적인 정보에 사용해요. 이 콜아웃은 접힌 상태로 시작해요. **예시:** ```md > [!tip]- 키보드 단축키 사용하기 > 자주 사용하는 단축키를 외우면 워크플로를 빠르게 할 수 있어요. > [!info]+ 유료 애드온이에요 > 이 기능을 사용하려면 유료 구독이 필요해요. > [!warning]+ 이 작업은 실행 취소할 수 없어요 > 보관함 삭제는 영구적이에요. 먼저 노트를 내보내는 것을 고려하세요. > [!example]- 고급 사용법 > 그래프 메뉴를 통해서도 이 설정을 구성할 수 있어요. ``` ### 목록 vs. 산문 강한 순서적 또는 인과적 관계가 없는 개별 항목을 제시할 때 목록을 사용해요. 항목이 서로 기반을 두거나, 설명이 필요하거나, 서술적 흐름이 유익한 경우 산문과 문단을 사용해요. **목록을 사용하는 경우:** - 관련 없는 기능 집합 - 설치 요구 사항 - 설정 옵션 - 문제 해결 단계 **산문을 사용하는 경우:** - 작동 방식에 대한 설명 - 종속성이 있는 워크플로 - 개념적 개요 - 맥락이 필요한 안내 ### 표 기능, 버전 또는 관련 데이터 포인트를 비교하여 정렬이 이해에 도움이 되는 경우 표를 사용해요. 단순한 목록이나 단일 열 데이터에는 표를 사용하지 않아요. **좋은 사용 사례:** | 기능 | 모바일 | 데스크톱 | |---------|--------|---------| | 동기화 | 예 | 예 | | 플러그인 | 아니오 | 예 | | 테마 | 제한적 | 전체 | ### 상호 참조 사용자가 관련 주제를 탐색할 수 있도록 내부 위키 링크(`[[노트 이름]]`)를 적극적으로 사용해요. 다만 과도한 링크는 피해요: - 같은 페이지에서 동일한 용어를 여러 번 링크하지 않아요 - 참조된 페이지가 의미 있는 추가 맥락을 제공할 때만 링크해요 - 도움이 될 때 설명적인 링크 텍스트를 사용해요: `[[노트 이름#섹션|설명적 텍스트]]` **예시:** 첫 번째 언급: "기기 간에 보관함을 최신 상태로 유지하려면 [[Obsidian Sync 소개|Obsidian Sync]]에 대해 알아보세요." 이후 언급: "각 기기에 대해 Sync를 별도로 설정할 수 있어요." ### 플랫폼별 콘텐츠 플랫폼 간에 다른 기능을 문서화할 때 섹션 제목을 사용하여 콘텐츠를 구성해요. 플랫폼별 지침이나 기능을 구분하기 위해 `데스크톱`과 `모바일`을 하위 섹션 제목으로 사용해요. **권장:** ```md ## 리본 사용자 지정 ### 데스크톱 데스크톱 버전에서는 다음과 같이 리본을 사용자 지정할 수 있어요: - 아이콘을 드래그 앤 드롭하여 리본 작업의 순서를 재배열해요. - 특정 작업을 숨기려면 빈 공간을 마우스 오른쪽 버튼으로 클릭하고 숨기려는 작업의 체크를 해제해요. ### 모바일 모바일 버전에서는 설정을 통해 리본을 사용자 지정할 수 있어요: 1. **[[설정]]**을 열어요. 2. **외형**으로 이동해요. 3. **리본 설정** 아래에서 **관리**를 선택해요. ``` > [!info]+ 섹션을 언제 만들어야 하나요? > 콘텐츠가 크게 다른 경우에만 별도의 섹션을 만들어요. 지침이 대부분 동일하고 사소한 차이만 있는 경우 인라인 메모를 대신 사용해요. ## 아이콘 및 이미지 말로 설명하기 어려운 것을 설명하기 쉽게 만들거나 Obsidian 애플리케이션의 중요한 부분을 보여줘야 할 때 아이콘과 이미지를 포함해요. 이미지는 `Attachments` 폴더에 저장할 수 있어요. - 이미지는 함께 있는 텍스트를 더 쉽게 이해할 수 있게 해야 해요. **예시**: 활성화하면 [[단어 개수]] 플러그인이 하단 상태 표시줄에 새 항목을 생성해요. ![[Style-guide-zoomed-example.png#interface|300]] - 이미지는 `.png` 또는 `.svg` 형식이어야 해요. - 이미지가 노트에서 너무 크게 보이면 Obsidian 외부에서 크기를 줄이거나 [[파일 임베드#노트에 이미지 임베드하기|노트에 이미지 임베드하기]]에 설명된 대로 크기를 조정해요. - 드문 경우에 특히 크거나 복잡한 이미지를 [[콜아웃#접을 수 있는 콜아웃|접힌 콜아웃]]에 배치할 수 있어요. - 팝업 창이나 모달의 경우 이미지에 전체 Obsidian 애플리케이션 창이 표시되어야 해요. ![[Style-guide-modal-example.png#interface]] ### 아이콘 [Lucide](https://lucide.dev/icons/)와 사용자 정의 Obsidian 아이콘을 세부 요소와 함께 사용하여 기능의 시각적 표현을 제공할 수 있어요. **예시:** 왼쪽 리본에서 **새 캔버스 만들기** ![[lucide-layout-dashboard.svg#icon]]를 선택하면 활성 파일과 같은 폴더에 캔버스를 생성해요. **아이콘 가이드라인** - 아이콘은 `Attachments/icons` 폴더에 저장해요. - Lucide 아이콘 이름 앞에 `lucide-` 접두사를 추가해요. - Obsidian 아이콘 이름 앞에 `obsidian-icon-` 접두사를 추가해요. **예시:** 새 캔버스를 만드는 아이콘은 `lucide-layout-dashboard`로 이름을 지정해야 해요. - 사용 가능한 아이콘의 SVG 버전을 사용해요. - 아이콘은 너비 `18` 픽셀, 높이 `18` 픽셀이어야 하며 획 너비는 `1.5`여야 해요. SVG 데이터에서 이러한 설정을 조정할 수 있어요. > [!info]- SVG에서 크기 및 획 조정 > ```html > <svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="HEIGHT" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="STROKE-WIDTH" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg> >``` - 임베드된 이미지에서 `icon` 앵커를 활용하여 아이콘 주변의 간격을 조정해 주변 텍스트와 깔끔하게 정렬되도록 해요. - 아이콘은 괄호로 둘러싸야 해요. ![[lucide-cog.svg#icon]] **예시**: `![[lucide-cog.svg#icon]]` ### 이미지 앵커 태그 이미지 앵커 태그를 사용하여 임베드된 이미지에 장식적 변경을 추가할 수 있어요. > [!warning] 실시간 미리보기 경고 > 아이콘 앵커 태그는 **실시간 미리보기**에서 올바르게 표시되지 않아요. **읽기 보기**를 사용하여 앵커 태그가 적용되었는지 확인하세요. **아이콘** `![[lucide-menu.svg#icon]]` 아이콘 앵커 태그는 인터페이스 요소를 나타내는 데 사용되는 아이콘의 올바른 수직 정렬을 보장해요. 첫 번째 메뉴 아이콘은 앵커 태그를 사용하고 ![[lucide-menu.svg#icon]], 두 번째 메뉴 아이콘은 사용하지 않아요 ( ![[lucide-menu.svg]] ). **인터페이스** `![[Vault picker.png#interface]]` 인터페이스 앵커 태그는 이미지 주위에 장식적인 박스 그림자를 추가해요. 첫 번째 이미지에는 인터페이스 앵커 태그가 적용되어 있어요. ![[Vault picker.png#interface]] 반면 두 번째 이미지에는 인터페이스 앵커가 적용되지 않았어요. ![[Vault picker.png]] **외곽선** `![[Backlinks.png#outline]]` 외곽선 앵커 태그는 이미지 주위에 미세한 테두리를 추가해요. 첫 번째 이미지에는 외곽선 앵커 태그가 적용되어 있어요. > [!tip] 차이를 확인하려면 이미지의 왼쪽 하단을 관찰하세요. ![[Backlinks.png#outline]] 두 번째 이미지에는 외곽선 앵커 태그가 없어요. ![[Backlinks.png]] ### 최적화 이미지는 페이지 로딩 시간을 늦추고 소중한 [[Obsidian Publish 소개|Publish]] 저장 공간을 차지해요. 이미지를 최적화하면 파일 크기를 줄이면서도 이미지의 시각적 완성도를 유지할 수 있어요. 이미지와 아이콘 모두 최적화해야 해요. > [!info] 이미지 최적화 도구 > 이미지 크기를 줄이기 위한 추천 프로그램이에요. > - **Windows:** [FileOptimizer](https://sourceforge.net/projects/nikkhokkho/) > - **macOS:** [ImageOptim](https://imageoptim.com/) > - **Linux/Unix** [Trimage](https://trimage.org) > > 65-75%의 최적화 비율을 권장해요. ## 레이아웃 ### 깨진 링크 풀 리퀘스트를 제출하기 전에, 작업 중인 번역 문서에서 깨진 링크를 확인하고 수정해 주세요. 깨진 링크는 시간이 지나면서 자연스럽게 발생할 수 있으므로 정확성을 확인하면 문서의 품질을 유지하는 데 도움이 돼요. [[커뮤니티 플러그인]] 또는 IDE에서 사용 가능한 도구를 사용하여 깨진 링크를 확인할 수 있어요. ### 설명 이 문서는 GitHub에서 편집되고 [[Obsidian Publish 소개|Obsidian Publish]]를 통해 온라인에 호스팅되며, 소셜 카드를 위한 [[소셜 미디어 링크 미리보기#설명|설명]]과 기타 [[SEO]] 요소를 포함해요. 작업 중인 페이지에 `description` [[속성|속성]]이 없다면 추가해 주세요. 설명은 150자 이하여야 하며 페이지 콘텐츠에 대한 객관적인 요약을 제공해야 해요. **좋은 예**: Web Clipper로 웹 페이지 메타데이터를 자동으로 캡처하고 정리하는 템플릿을 만드는 방법을 알아보세요. **개선이 필요한 예**: Web Clipper를 사용하여 웹 페이지에서 자동으로 메타데이터를 캡처하고 정리하는 템플릿을 만드는 방법을 알아보세요. ### 방향 앱 내에서 작업을 수행하는 방법에 대한 [[#지침]]을 작성하거나 다시 작성할 때 모바일과 데스크톱 버전 모두에 대한 단계를 포함해야 해요. 모바일 또는 데스크톱 기기에 접근할 수 없는 경우 풀 리퀘스트를 제출할 때 이를 언급해 주세요. ## 번역 번역을 완료할 때 콘텐츠 전체를 번역해요. 이에 포함되지만 이에 한정되지 않는 항목은 다음과 같아요: - 노트 이름 - 폴더 이름 - 별칭 - 첨부 파일 이름 - 대체 링크 텍스트