arminazimi/slipway-content

Slipway 사이트에서 페이지 및 게시물 작성

Slipway 사이트는 프론트매터 블록이 포함된 마크다운 파일입니다. 레이아웃이 나머지 작업(제목, 머리말, 목차, 날짜, 언어 전환기)을 처리합니다. 여러분은 스키마에 따라 프론트매터를 작성하고 일반 마크다운으로 본문을 작성하면 됩니다. 사이트에 AGENTS.md가 있다면 먼저 읽으십시오. 이 스킬과 다른 부분이 있다면 AGENTS.md가 우선합니다.

1. 기본 기준 설정

테마의 검사를 한 번 실행하여 사이트 밖의 폴더에 저장하십시오:

git clone --depth 1 https://github.com/arminazimi/slipway "$HOME/.slipway"
cd "$HOME/.slipway" && npm ci && cd -

아무것도 변경하기 전에 섹션 6을 실행하고 출력을 보관하십시오. 편집이 완료되었을 때 새로 추가된 문제나 발견 사항이 없어야 합니다.

2. 레이아웃과 파일 선택

작성할 내용	layout	파일
일반 페이지(소개, 연락처)	page	<폴더>/<페이지>.md, /<폴더>/<페이지>.html로 제공됨
사이드바가 있는 문서 페이지	doc	모든 폴더, 주로 docs/<페이지>.md, permalink 필요
날짜가 있는 게시물	post	_posts/<날짜>-<슬러그>.md, <날짜>는 YYYY-MM-DD 형식
랜딩 페이지	home	index.md

게시물의 파일 이름은 날짜와 주소를 나타냅니다. 제목을 변경하려면 파일 이름을 변경하지 말고 title을 설정하십시오. doc 페이지는 _data/navigation.yml의 docs 목록이 해당 permalink를 링크할 때만 사이드바에 표시됩니다. 읽기 순서대로 추가하십시오. search.json, feed.xml, sitemap.xml, 404.md, tags.md, archive.md를 생성하지 마십시오. 이미 존재하며, 프론트매터가 있고 의도적으로 본문이 없습니다.

초안, 예약 게시물, 게시물 편집: 초안은 _drafts/<슬러그>.md에 저장하며, 이름에 날짜가 없습니다. GitHub Pages는 _drafts/를 빌드하지 않으며, jekyll serve --drafts는 오늘 날짜로 미리보기 합니다. 예약 게시물은 YYYY-MM-DD 파일 이름이 미래 날짜인 일반 게시물입니다. GitHub Pages는 해당 날짜에 자동으로 게시하며, jekyll serve --future는 일찍 미리보기하고 페이지에 "예약됨"으로 표시합니다. 게시된 게시물을 상당히 편집한 후에는 updated: YYYY-MM-DD(파일 이름 날짜와 동일한 형식)를 추가하십시오. 게시물에 "edited on"으로 표시되며, 피드, 사이트맵, 구조화된 데이터에서 마지막 수정 날짜로 보고됩니다.

3. 스키마에 따라 프론트매터 채우기

모든 키, 유형, 허용 값은 reference/front-matter.md에 있습니다. 검사에서 사용하는 스키마에서 생성됩니다. 레이아웃에 대해 나열된 키만 사용하십시오.

• title은 필수이며 비어 있으면 안 됩니다. 레이아웃이 페이지 머리말로 출력합니다.
• description을 추가하십시오: 검색 결과와 링크 미리보기용 한 문장.
• tags와 categories는 목록입니다: tags: [release, notes].
• 게시물의 author는 _data/authors.yml의 키이거나 여러 작성자를 위한 키 목록입니다: author: [ada, sam]. 해당 파일에 키가 없으면 먼저 작성자를 추가하십시오.
• 게시물의 series는 시리즈로 분류합니다: 모든 부분에 정확히 같은 이름을 사용하십시오, series: Writing for the web. 부분은 날짜순으로 정렬됩니다.
• permalink는 /로 시작합니다. 기본 언어 게시물은 생략하십시오. 사이트 설정이 주소를 지정합니다.
• 사이트의 기본 언어(_config.yml의 lang)가 아닌 페이지와 번역이 있는 모든 페이지에 lang을 설정하십시오.
• home 전용: cta_text와 cta_url은 함께 사용하거나 전혀 사용하지 않습니다. variant는 모양을 선택합니다: editorial(기본값), landing(각각 title이 있는 features 추가), blog, 또는 docs(_data/navigation.yml의 docs 목록에서 카드).
• : 를 포함하거나 YAML이 특별히 처리하는 문자([, {, *, &, !, #, |, >, @, 백틱)로 시작하는 값은 따옴표로 묶으십시오.

4. 본문 작성

• 순수 마크다운만 사용하십시오. Liquid는 절대 사용하지 마십시오. 코드 블록에서도 {{ }}나 {% %}를 사용하지 마십시오. 레이아웃이 이미 Liquid가 할 일을 추가합니다.
• 섹션은 ##부터 시작하십시오. h1은 제목입니다. 본문에서 # 머리말을 하나 더 사용하면 두 번째 h1이 생성됩니다.
• 머리말 수준을 순서대로 유지하십시오(##, 그 다음 ###). 그래야 목차와 "에이전트로 편집" 버튼이 모든 섹션을 찾을 수 있습니다.
• 다른 페이지로 링크할 때는 파일이 아닌 주소로 링크하십시오: [Install](/docs/install/), [About](/about.html).
• 이미지는 assets/에 있습니다. 각 이미지에 대체 텍스트를 제공하십시오: ![A chart of build times](/assets/build-times.png).
• 더 넓은 페이지를 위해 프론트매터에 width: narrow, wide, 또는 full을 설정하십시오. 대신 하나의 블록(표, 이미지, 그림)을 넓히려면 sl-wide(최대 64rem) 또는 sl-bleed(가장자리에서 가장자리) 클래스가 있는 HTML 요소로 감싸십시오: <figure class="sl-wide"><img src="/assets/map.png" alt="A map of the route"></figure>. doc 레이아웃은 섹션을 열 안에 유지합니다.
• 코드 블록에 언어를 지정하십시오(```yaml). 그래야 코드가 강조 표시되고 오른쪽에서 왼쪽 페이지에서 왼쪽에서 오른쪽으로 읽힙니다.

스키마를 통과하는 예시:

• examples/doc-page.md: doc 페이지.
• examples/post.md: 태그가 있는 게시물.
• examples/post-fa.md: 페르시아어로 된 동일한 게시물.

각 파일의 첫 번째 주석에 파일 위치가 나와 있습니다.

5. 번역 추가

1. 언어는 slipway.languages가 _config.yml에 있어야 하며, code, name, prefix(예: /fa)가 있어야 합니다. 언어가 없으면 언어를 추가하기 전에 물어보십시오. 모든 페이지의 전환기가 변경됩니다.
2. 원본에 translation_key가 없으면 추가하십시오(예: plain-markdown). lang(lang: en)도 없으면 추가하십시오. 전환기는 둘 다로 번역을 찾습니다. 번역에 동일한 translation_key를 부여하십시오. 이렇게 하면 언어 전환기와 사이트맵에서 두 페이지가 연결됩니다.
3. lang을 언어 코드로 설정하고, permalink를 접두사 아래 주소로 설정하십시오: /fa/plain-markdown/.
4. 파일 위치: 페이지는 접두사 폴더(fa/about.md)에, 게시물은 자체 슬러그로 _posts/에 유지됩니다(_posts/2026-10-20-plain-markdown-fa.md).
5. title, description, tags, 본문을 번역하십시오. layout, 날짜, 코드, 명령어, URL은 그대로 유지하십시오.
6. 사이트에 해당 언어의 헤더 메뉴(_data/navigation.yml의 main_fa)가 있으면 해당 페이지도 추가하십시오.

오른쪽에서 왼쪽으로 쓰는 언어(fa, ar, he, ur)는 lang에서 오른쪽에서 왼쪽 레이아웃을 받습니다. direction이나 dir을 설정하지 마십시오. 페르시아어 텍스트에서는 페르시아어 ی와 ک(아랍어 ي와 ك 아님)를 사용하고, می‌شود와 같은 단어에 제로 너비 비접합자를 사용하며, 페르시아어 구두점(،와 ؟)을 사용하십시오. 명령어, 파일 이름, 코드는 백틱 안에 넣으십시오. 문장 안에서 왼쪽에서 오른쪽으로 유지됩니다.

6. 편집 확인

사이트 폴더에서 설정과 모든 페이지의 프론트매터를 스키마와 대조하여 확인하십시오:

node "$HOME/.slipway/tools/theme/validate.mjs" .

각 문제는 파일:줄 키: 메시지 (허용 값: ...) 형식으로 출력됩니다. 해당 줄에서 허용 값을 사용하여 수정하고 다시 실행하십시오. 그런 다음 Gemfile이 있으면 사이트를 빌드하십시오:

bundle exec jekyll build

모든 오류와 경고를 읽고 해당 파일에서 수정하십시오. 그런 다음 소스와 빌드에 대해 doctor를 실행하십시오. doctor는 AGENTS.md, content-schemas.json(사이트에 있는 경우 프론트매터를 이름이 지정된 스키마에 대해 검증), 소스 맵, 편집 프롬프트를 확인합니다:

node "$HOME/.slipway/packages/doctor/bin/slipway.mjs" doctor . --build _site

결과를 기준과 비교하십시오. 파일을 명명한 발견 사항은 수정해야 할 것입니다. Gemfile이 없으면 --build 없이 doctor를 실행하고 푸시 후 Pages 빌드 로그를 읽으십시오.

절대 하지 말아야 할 것

• 페이지에 Liquid({{ }} 또는 {% %})를 넣지 마십시오.
• reference/front-matter.md에 나열되지 않은 프론트매터 키를 추가하지 마십시오.
• 하나의 번역에서만 translation_key를 변경하지 마십시오. 해당 키를 공유하는 모든 페이지를 변경하거나 아무것도 변경하지 마십시오.
• 게시된 페이지나 게시물의 제목을 변경하기 위해 이름을 바꾸거나 이동하지 마십시오. title을 설정하십시오. 주소는 파일 이름이나 permalink이며, 링크가 깨집니다.
• _site/를 편집하지 마십시오. 프론트매터가 있고 본문이 없는 페이지를 삭제하지 마십시오.
• 한 페이지의 모양을 변경하기 위해 테마 레이아웃이나 include를 편집하지 마십시오.