Aither (한국어)

Astro-Theme-Aither 시작하기

Sat, 14 Mar 2026 08:00:00 GMT

이 가이드는 처음 설정부터 다국어 블로그 배포까지 전체 흐름을 안내합니다. 처음부터 끝까지 읽어도 되고, 필요한 섹션만 바로 찾아가도 됩니다. ## 준비 사항 - [Node.js](https://nodejs.org/) 22 LTS 이상 - [pnpm](https://pnpm.io/) 10 이상 - GitHub 계정 - 배포용 [Cloudflare](https://cloudflare.com/) 계정 ## 설치 ```bash git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git cd YOUR_REPO corepack enable pnpm install pnpm validate pnpm dev ``` 브라우저에서 `http://localhost:4321`을 열면 됩니다. ## 프로젝트 구조 ```text src/ ├── components/ # Astro 및 React 컴포넌트 ├── config/site.ts # 사이트 이름, 내비게이션, 푸터, 소셜 링크 ├── content/posts/ # 로케일별 글 콘텐츠 ├── i18n/ # UI 번역 ├── layouts/ # 레이아웃 ├── lib/ # 유틸리티 ├── pages/ # 페이지와 라우트 └── styles/global.css # Tailwind v4 테마 토큰 ``` ## 설정 ### Site Config `src/config/site.ts`가 사이트 설정의 단일 진실 공급원입니다: ```typescript export const siteConfig = { name: '블로그 이름', title: '태그라인', description: 'SEO용 사이트 설명', author: { name: '작성자 이름', avatar: '', }, }; ``` ### 환경 변수 ```bash cp .env.example .env ``` 값을 비워두면 해당 서비스는 자동으로 비활성화됩니다. ### 사이트 URL 운영 URL은 `astro.config.mjs`에서 설정합니다: ```javascript import { defineConfig } from 'astro/config'; import aither from '@aither/astro'; export default defineConfig({ site: 'https://your-domain.pages.dev', integrations: [aither()], }); ``` ## 글 작성하기 `src/content/posts/en/` 아래에 새 `.mdx` 파일을 만드세요: ```markdown --- title: 나의 첫 글 date: "2026-03-14T16:00:00+08:00" category: General description: SEO와 소셜 미리보기를 위한 짧은 설명. tags: [Topic, Another] pinned: false --- 여기서부터 본문이 시작됩니다. ``` ### Frontmatter 참고 | 필드 | 타입 | 필수 | 설명 | |------|------|------|------| | `title` | string | 예 | 글 제목 | | `date` | date | 예 | 발행 시각 (예: `2026-03-14T16:00:00+08:00`) | | `category` | string | 아니오 | 카테고리 | | `description` | string | 아니오 | SEO 설명 | | `tags` | string[] | 아니오 | 태그 목록 | | `pinned` | boolean | 아니오 | 상단 고정 여부 | | `image` | string | 아니오 | 커버 이미지 | ### MDX 컴포넌트 콘텐츠 안에서 컴포넌트를 바로 사용할 수 있습니다: ```mdx import MyChart from '@/components/MyChart' ``` ## 국제화 이 테마는 기본적으로 11개 언어를 지원합니다. 번역 글을 추가하려면 대상 로케일 디렉터리에 같은 파일명을 만들면 됩니다: ```text src/content/posts/en/my-post.mdx src/content/posts/ko/my-post.mdx src/content/posts/zh-hans/my-post.mdx ``` UI 문자열은 `src/i18n/messages/`에 있습니다. ## 커스텀 콘텐츠 섹션 번역, 노트, 튜토리얼 같은 별도 컬렉션은 `src/content.config.ts`와 `src/config/site.ts`에서 등록할 수 있습니다. 그러면 목록 페이지와 상세 페이지가 자동 생성됩니다. ## 테마 설정 테마는 두 층으로 나뉩니다: - 색상 모드: `light`, `dark`, `system` - 스타일 모드: `default` 또는 `evolution` 같은 내장 스타일 ```typescript ui: { defaultMode: 'system', defaultStyle: 'default', showMoreThemesMenu: true, }, ``` 색상 토큰은 `src/styles/global.css`에 있고, 기본 본문은 시스템 sans-serif, 코드 영역은 monospace를 사용합니다. ## SEO 및 AI 각 페이지는 다음과 같은 출력물을 기본 제공합니다: - `/sitemap-index.xml` - `/rss.xml` - `/robots.txt` - `/llms.txt` - `/llms-full.txt` - `/posts/slug.md` - JSON-LD 및 Open Graph ## 배포 ### Cloudflare Pages 권장 방식은 먼저 Pages 프로젝트를 만드는 것입니다. 워크플로는 기본적으로 저장소 이름을 사용하고, 필요하면 `CLOUDFLARE_PAGES_PROJECT_NAME`으로 덮어쓸 수 있습니다. GitHub Secrets에 아래 값을 추가하세요: - `CLOUDFLARE_API_TOKEN` - `CLOUDFLARE_ACCOUNT_ID` 그다음 `pnpm validate`를 실행하고 `main`에 푸시하세요. ## 자주 쓰는 명령어 | 명령어 | 설명 | |-------|------| | `pnpm dev` | 개발 서버 실행 | | `pnpm validate` | push 전 전체 검증 실행 | | `pnpm build` | 프로덕션 빌드 생성 | | `pnpm preview` | 빌드 결과를 로컬에서 미리보기 | ## 버전 체계 공개 릴리스 태그는 `v2026.04.08` 같은 CalVer 스타일 이름을 사용합니다.

실제 프로젝트를 위한 AI 에이전트 모범 사례 (예시)

Sat, 10 Jan 2026 08:00:00 GMT

AI 에이전트가 가장 유용해지는 순간은 그것이 더 이상 마법처럼 보이지 않고, 실제로 운영 가능한 도구처럼 작동하기 시작할 때다. 가장 좋은 결과를 내는 팀은 에이전트에게 "전부 처리해 달라"고 하지 않는다. 대신 할 일을 명확히 정의하고, 올바른 컨텍스트를 제공하고, 결과를 쉽게 검증할 수 있게 만든다. 이것은 단순해 보이지만 결과를 완전히 바꾼다. 준비가 잘 된 에이전트는 빠르게 움직이면서도 꽤 탄탄한 결과를 낼 수 있다. 반대로 범위가 흐린 에이전트는 컨텍스트를 낭비하고, 불필요한 우회를 하고, 자신감 있어 보이지만 실제 문제를 놓친 결과를 돌려주기 쉽다. ## 좁고 명확한 작업부터 시작하라 에이전트에게 가장 잘 맞는 작업은 구체적이고 경계가 분명한 작업이다. "이 앱을 개선해줘"라고 말하는 대신 "블로그 페이지에서 모바일 내비게이션이 겹치는 문제를 고쳐줘" 또는 "RSS 피드를 위한 간단한 검증 테스트를 추가해줘"라고 말하는 편이 훨씬 낫다. 좁은 작업은 에이전트에게 안정적인 목표를 주고, 관련 없는 부분까지 손대는 위험을 줄여 준다. 이것은 리뷰도 쉽게 만든다. 작업이 작을수록 무엇이 바뀌었는지, 무엇을 테스트해야 하는지, 결과가 실제로 맞는지 더 분명해진다. ## 컨텍스트를 명시적으로 적어라 에이전트는 중요한 컨텍스트가 암묵적으로 남아 있을 때보다 문서로 적혀 있을 때 더 잘 동작한다. 좋은 작업 브리프에는 보통 다음이 포함된다: - 정확한 목표 - 관련 파일이나 디렉터리 - 바뀌면 안 되는 제약 조건 - 기대하는 결과 또는 완료 기준 - 마지막에 실행할 검증 명령 사람은 불완전한 지시에서도 많은 것을 추론할 수 있다. 에이전트는 더 문자 그대로 받아들인다. 어떤 세부사항이 중요하다면, 적어 두는 편이 낫다. ## 추측보다 도구를 우선하라 에이전트는 변경을 제안하기 전에 현재 시스템을 먼저 살펴봐야 한다. 즉, 관련 파일을 읽고, 빌드 설정을 확인하고, 기존 규칙을 이해해야 한다. 일반적인 기억에만 의존해서는 안 된다. 외부 시스템도 마찬가지다. 답이 최신 문서, 배포 설정, 혹은 실제 동작에 달려 있다면, 에이전트는 기억에 기대어 추측하지 말고 도구를 사용해 실제 상태를 확인해야 한다. 바로 이 때문에 기계가 읽을 수 있는 인터페이스가 중요하다. 명확한 파일 구조, 검증 스크립트, 타입 스키마, 명시적인 설정은 환경 자체가 설명을 제공하기 때문에 에이전트를 더 신뢰할 수 있게 만든다. ## 결과를 검증 가능하게 유지하라 좋은 에이전트 워크플로우는 "여기 답이 있습니다"로 끝나지 않는다. 증거로 끝난다. 에이전트에게 무엇을 바꿨는지, 무엇을 테스트했는지, 무엇을 검증하지 못했는지 보고하게 하라. 빠르게 확인할 수 있는 결과물을 선호하는 것이 좋다: - 작은 diff - 통과하는 검증 명령 - 재현 가능한 스크린샷이나 프리뷰 - 위험이나 가정에 대한 짧은 메모 검증은 그럴듯한 결과를 믿을 수 있는 결과로 바꾼다. ## 복구하기 쉬운 구조로 설계하라 강한 에이전트도 잘못된 방향으로 갈 수 있다. 올바른 대응은 에이전트를 피하는 것이 아니라, 복구 비용을 낮추는 것이다. 작은 작업, 안정적인 스크립트, 체크포인트를 사용하라. 가능하면 작업을 멱등적으로 유지하라. 한 번의 실수가 큰 정리 비용으로 이어지는 워크플로우는 피하는 편이 좋다. 작업을 읽기, 계획, 구현, 검증으로 나눌 수 있다면 그렇게 나누어라. 에이전트는 살펴보기 쉽고, 테스트하기 쉽고, 계속 앞으로 밀어가기 쉬운 시스템에서 가장 좋은 성능을 낸다. ## 사람의 리뷰는 여전히 중요하다 에이전트는 속도, 커버리지, 반복 작업에 매우 강하다. 하지만 판단은 여전히 사람이 책임져야 한다. 제품 트레이드오프, 보안 경계, 톤, 브랜드, 장기 유지보수성은 더 넓은 맥락을 이해하는 사람이 검토해야 한다. 목표는 사람을 루프에서 빼는 것이 아니다. 목표는 사람이 기계적인 작업에 덜 시간을 쓰고, 실제로 판단과 책임이 필요한 결정에 더 많은 시간을 쓰게 만드는 것이다. ## 실용적인 사고 모델 AI 에이전트를 유능하고, 빠르고, 지치지 않으며, 문자 그대로 움직이는 작업자로 생각하라. 명확한 과제를 주고, 올바른 도구를 주고, 작업 과정을 보여 달라고 하라. 그리고 그 결과를 중요한 변경을 검토할 때와 같은 엄격함으로 검토하라. 진짜 레버리지는 거기서 나온다.

AI 에이전트와 도구 사용 (샘플)

Fri, 09 Jan 2026 08:00:00 GMT

AI 에이전트는 단순히 텍스트를 생성하는 것이 아니라 행동을 취할 수 있는 언어 모델입니다. 웹을 검색하고, 코드를 실행하고, API를 호출하고, 파일을 읽고, 다음에 할 일을 결정할 수 있습니다. 수동적 텍스트 생성에서 능동적 문제 해결로의 이 전환은 응용 AI에서 가장 중요한 발전 중 하나입니다. ## 채팅에서 행동으로 챗봇은 질문에 답합니다. 에이전트는 문제를 해결합니다. 차이는 자율성입니다: 에이전트는 어떤 도구를 사용할지, 어떤 순서로, 에러를 어떻게 처리할지 결정합니다. 실제 차이를 생각해 보세요. 챗봇에게 "도쿄 날씨가 어때?"라고 물으면 학습 데이터 기반으로 답할 수 있지만 — 몇 달 또는 몇 년 전 데이터로 거의 확실히 부정확합니다. 에이전트에게 같은 질문을 하면 날씨 API를 호출하고 현재 데이터를 검색하여 정확하고 최신 답변을 반환합니다. 챗봇은 그럴듯한 텍스트를 생성합니다. 에이전트는 세계와 상호작용합니다. ### 자율성의 스펙트럼 모든 에이전트가 동일하게 자율적이지는 않습니다. 스펙트럼이 있습니다: 1. **도구 보조 채팅** — 모델이 도구를 호출할 수 있지만, 사용자 요청에 대한 직접 응답으로만. 턴당 하나의 도구 호출. 2. **다단계 에이전트** — 모델이 작업을 완수하기 위해 여러 도구 호출을 연쇄할 수 있으며, 순서를 스스로 결정. 3. **완전 자율 에이전트** — 모델이 장기간 독립적으로 운영하며, 결정을 내리고 에러를 처리하고 최소한의 인간 감독으로 목표를 추구. 현재 대부분의 프로덕션 시스템은 1-2 수준입니다. 완전 자율 에이전트는 아직 해결해야 할 중요한 안전 과제가 있는 활발한 연구 분야입니다. ## 도구 사용 도구 사용은 AI 모델이 외부 함수를 호출할 수 있게 합니다. 모델은 도구가 필요한 시점을 결정하고, 올바른 매개변수를 생성하고, 결과를 응답에 통합합니다. ### 도구 사용의 작동 방식 메커니즘은 간단합니다: 1. **도구 정의** — 이름, 매개변수, 역할을 포함하여 사용 가능한 도구를 모델에 설명합니다. 2. **결정** — 사용자 요청을 처리할 때 모델이 도구가 도움이 될지 결정합니다. 그렇다면 적절한 매개변수로 도구 호출을 생성합니다. 3. **실행** — 애플리케이션이 도구 호출을 실행하고(모델이 직접 실행하지 않음) 결과를 반환합니다. 4. **통합** — 모델이 도구 결과를 사용자 응답에 통합합니다. ### 도구 정의 예시 ```json { "name": "search_documentation", "description": "Search the product documentation for relevant articles", "parameters": { "type": "object", "properties": { "query": { "type": "string", "description": "The search query" }, "max_results": { "type": "integer", "description": "Maximum number of results to return", "default": 5 } }, "required": ["query"] } } ``` ### 일반적인 도구 카테고리 프로덕션 에이전트 시스템은 보통 여러 카테고리의 도구를 제공합니다: - **정보 검색** — 웹 검색, 데이터베이스 쿼리, 파일 읽기, API 호출 - **코드 실행** — 샌드박스 환경에서 Python, JavaScript, 셸 명령 실행 - **커뮤니케이션** — 이메일 전송, 메시지 게시, 티켓 생성 - **파일 조작** — 파일 생성, 편집, 정리 - **시스템 운영** — 코드 배포, 인프라 관리, CI 파이프라인 실행 제공하는 도구가 에이전트가 할 수 있는 것의 경계를 정의합니다. 잘 설계된 도구 세트는 에이전트에게 유용할 만큼의 능력을 부여하면서 위험할 만큼의 권한은 주지 않습니다. ## 에이전트 루프 가장 강력한 패턴은 에이전트 루프입니다: 모델이 단계를 계획하고, 실행하고, 결과를 관찰하고, 다음 단계를 결정합니다. 이 루프는 작업이 완료되거나 진행할 수 없다고 판단할 때까지 계속됩니다. ### 루프의 에러 처리 견고한 에이전트는 실패를 우아하게 처리해야 합니다. 좋은 에이전트 설계에는 다음이 포함됩니다: - **재시도 로직** — 일시적 실패를 백오프와 함께 재시도 - **대체 전략** — 한 접근이 실패하면 다른 것을 시도 - **우아한 성능 저하** — 작업을 완전히 완료할 수 없으면 가능한 만큼 완료하고 남은 것을 설명 - **루프 제한** — 에이전트가 막힐 때 무한 루프를 방지하기 위한 최대 반복 횟수 설정 ## 효과적인 도구 설계 ### 도구 설계 원칙 - **명확한 이름** — `query_db_1`보다 `search_users`가 좋습니다. 모델은 이름을 기반으로 도구를 호출할 시기를 결정합니다. - **설명적 매개변수** — 모든 매개변수에 설명을 포함하세요. - **집중된 범위** — 각 도구가 하나의 일을 잘 해야 합니다. - **유용한 에러** — 무엇이 잘못되었고 대신 무엇을 시도할지 이해할 수 있는 명확한 에러 메시지를 반환하세요. - **가능하면 멱등성** — 안전하게 재시도할 수 있는 도구가 에러 처리를 단순화합니다. ## 위험 행동을 취할 수 있는 에이전트는 잘못된 행동을 취할 수 있습니다. 샌드박싱, 확인 단계, 인간 참여 리뷰는 모든 프로덕션 에이전트 시스템의 필수 안전 조치입니다. ### 안전 패턴 프로덕션 에이전트 시스템은 여러 안전 패턴을 구현해야 합니다: 1. **최소 권한** — 에이전트에게 특정 작업에 필요한 도구만 제공 2. **샌드박싱** — 코드와 파일 작업을 격리된 환경에서 실행 3. **확인 게이트** — 파괴적이거나 돌이킬 수 없는 행동에 인간 승인 요구 4. **감사 로깅** — 모든 도구 호출과 결과를 기록 5. **킬 스위치** — 실행 중인 에이전트를 즉시 중단하는 메커니즘 제공 6. **예산 제한** — API 호출, 토큰 사용, 컴퓨트 시간에 하드 캡 설정 목표는 에이전트가 유용하지 못하게 하는 것이 아닌 — 잘 정의된 경계 내에서 유용하게 하는 것입니다.

✨ Astro-Theme-Aither를 선택한 이유

Sat, 03 Jan 2026 08:00:00 GMT

텍스트 자체가 아름답다고 믿는 AI 네이티브 Astro 테마. Astro-Theme-Aither는 장식이 아닌 글을 위해 찾아오는 독자를 위해 만들어졌습니다. ## 디자인 철학 대부분의 블로그 테마는 히어로 이미지, 애니메이션, 사이드바, 팝업으로 시선을 끌려 합니다. 이런 것들은 읽기에 도움이 되지 않습니다 — 보기에 도움이 될 뿐이고, 그것은 완전히 다른 활동입니다. Astro-Theme-Aither는 정반대의 접근을 취합니다: 미니멀한 디자인이지, 미니멀한 엔지니어링이 아닙니다. 문제를 가려줄 화려한 비주얼이 없으면 모든 타이포그래피 결함, 모든 로딩 지연, 모든 인터랙션 끊김이 증폭됩니다. 미니멀한 디자인은 더 낮은 것이 아닌 더 높은 엔지니어링 품질을 요구합니다. ## 타이포그래피 서체가 곧 시각적 아이덴티티입니다. 모든 페이지는 통합된 산세리프 시스템 폰트 스택을 사용합니다 — 깔끔하고, 빠르고, 플랫폼 간 일관적입니다. 타이포그래피 파라미터는 Apple Human Interface Guidelines를 따릅니다: - **폰트 크기** — 17px 기본, 편안한 화면 읽기를 위한 최적점 - **행 높이** — 1.47, 읽기 흐름을 깨지 않으면서 각 줄에 여유를 줌 - **자간** — -0.022em, 본문 텍스트를 세련되게 만드는 미묘한 조임 - **제목 스케일** — 31px → 22px → 19px → 17px, 크기 극단 없이 명확한 계층 - **읽기 너비** — 줄당 65~75자로 제한, 눈이 가장 편안하게 추적하는 범위 이것들은 수십 년간의 화면 가독성 연구와 Apple 타이포그래피 표준에서 도출된 근거 기반 실천입니다. ## Astro 기반 Astro는 오늘날 콘텐츠 중심 사이트에 가장 적합한 프레임워크입니다. 기본적으로 정적 HTML을 출력합니다 — 명시적으로 선택하지 않는 한 클라이언트 사이드 JavaScript가 없습니다. 아일랜드 아키텍처는 인터랙티브 컴포넌트가 독립적으로 하이드레이트되고 나머지 페이지는 정적으로 유지됩니다. Astro-Theme-Aither에서 인터랙티브 아일랜드는 최소화되어 있습니다: - **테마 전환기** — View Transitions API 원형 공개 애니메이션을 사용한 라이트 / 다크 / 시스템 토글 - **언어 전환기** — localStorage 지속성을 가진 매끄러운 로케일 전환 - **로케일 감지** — 브라우저 언어를 자동 감지하고 전환을 제안 - **모바일 네비게이션** — 반응형 햄버거 메뉴 나머지는 모두 순수 HTML과 CSS로, 즉시 로드됩니다. ## 기능 - **Tailwind CSS v4** — 전체 라이트/다크 팔레트 커스터마이징이 가능한 `@theme` 디자인 토큰 - **Apple HIG 타이포그래피** — 17px / 1.47 / -0.022em 본문 텍스트 파라미터 - **View Transitions API** — 테마 전환을 위한 원형 공개 애니메이션 - **i18n** — 자동 브라우저 언어 감지를 포함한 다국어 지원 - **글 고정** — 중요한 글을 목록 상단에 고정 - **Content Collections** — 빌드 타임 프런트매터 유효성 검사를 포함한 타입 안전 Markdown - **다크 모드** — localStorage 지속성을 가진 라이트 / 다크 / 시스템 - **SEO** — Open Graph, 정규 URL, 글별 메타 설명 - **RSS + 사이트맵** — 자동 생성, 설정 불필요 - **Google Analytics** — 선택 사항, Partytown Web Worker에서 실행 - **테스트** — Vitest 유닛 테스트 + Playwright E2E, CI에 통합 - **Cloudflare Pages** — PR 미리보기 URL이 포함된 배포 워크플로우 ## 누구를 위한 것인가 좋은 글이 스스로 말하고 그 믿음을 존중하는 테마를 원한다면: - **개인 블로거** — 글이 전면에 나오길 원하는 분 - **기술 작가** — 훌륭한 코드 블록 렌더링과 명확한 산문 서식이 필요한 분 - **다국어 저자** — 자동 브라우저 언어 감지가 포함된 내장 i18n이 필요한 분 - **개발자** — 자신 있게 확장할 수 있는 잘 엔지니어링된 코드베이스를 좋아하는 분 무엇이든 쓰세요 — 타이포그래피가 멋지게 만들어줄 것입니다.

📝 Markdown 스타일 가이드

Fri, 02 Jan 2026 08:00:00 GMT

이 글은 Astro-Theme-Aither가 지원하는 모든 Markdown 기능을 보여줍니다. 글을 작성할 때 참고 자료로 활용하세요. 이 페이지를 북마크하세요 — 사용 가능한 모든 서식 옵션을 다룹니다. ## 제목 섹션 제목에는 `##`을, 하위 섹션에는 `###`을, 하위의 하위 섹션에는 `####`을 사용하세요. 글 내용에서는 `#`을 피하세요 — 글 제목이 이미 최상위 제목으로 렌더링됩니다. ### 3단계 제목 3단계 제목은 섹션을 뚜렷한 주제로 나누는 데 적합합니다. 너무 눈에 띄지 않으면서 시각적 계층을 만들어줍니다. #### 4단계 제목 4단계 제목은 세부적인 하위 섹션에 적합합니다. 드물게 사용하세요 — 개요가 4단계보다 깊어진다면 콘텐츠 구조를 재검토하는 것이 좋습니다. ### 제목 모범 사례 효과적인 제목 사용을 위한 몇 가지 지침: - **단계를 건너뛰지 마세요** — `##`에서 `###`으로, 절대 `##`에서 바로 `####`로 가지 마세요. 단계를 건너뛰면 문서 개요가 깨지고 스크린 리더를 혼란스럽게 할 수 있습니다. - **제목을 설명적으로 유지하세요** — "설정 관련"보다 "환경 설정"이 좋습니다. 독자들은 섹션을 읽을지 결정하기 전에 제목을 훑어봅니다. - **문장 표기법을 사용하세요** — 첫 단어와 고유명사만 대문자로 씁니다. ## 단락과 줄 바꿈 일반 단락 텍스트는 자연스럽게 흐릅니다. 단락을 구분하려면 빈 줄을 남기세요. 이것은 두 번째 단락입니다. 최상의 읽기 경험을 위해 단락은 하나의 아이디어에 집중하세요. 웹 글쓰기에서는 짧은 단락이 긴 텍스트 블록보다 잘 작동합니다. 화면에서 편안하게 읽을 수 있는 단위는 3~5문장입니다. 6~7문장을 넘어가면 분리를 고려하세요. 단락 내에서의 단일 줄 바꿈(빈 줄 없이)은 새 줄이 아닌 공백으로 처리됩니다. 새 단락 없이 강제 줄 바꿈이 필요하면 줄 끝에 공백 두 개를 넣거나 `
` 태그를 사용하세요 — 실제로는 거의 필요하지 않습니다. ## 강조 - **굵은 텍스트** `**이중 별표**`로 표시 - *기울임 텍스트* `*단일 별표*`로 표시 - ***굵은 기울임*** `***삼중 별표***`로 표시 - ~~취소선~~ `~~이중 물결표~~`로 표시 ### 각 스타일 사용 시점 **굵게**는 핵심 용어, 중요한 경고, 정의 등 — 훑어봐도 놓치면 안 되는 것에 적합합니다. 단락에서 가장 중요한 문구에 사용하고, 전체 문장에는 사용하지 마세요. *기울임*은 문장 내 강조, 책 및 출판물 제목, 처음 사용하는 기술 용어, 외국어 표현에 적합합니다. 굵게보다 부드러운 강조를 제공합니다. ~~취소선~~은 수정 사항, 더 이상 사용되지 않는 정보, 변경 로그의 완료 항목 표시에 유용합니다. 사용 범위는 좁지만 필요할 때 가치 있습니다. ## 링크 [인라인 링크](https://astro.build) `[텍스트](url)` 구문으로 작성합니다. 링크는 상대 경로를 사용하여 사이트의 다른 글을 참조할 수도 있습니다. 설명적인 링크 텍스트를 사용하세요 — "여기를 클릭하세요"보다 "마크다운 가이드를 읽어보세요"가 좋습니다. 좋은 링크 텍스트는 독자와 검색 엔진 모두 링크 목적지를 이해하는 데 도움이 됩니다. 문장 내에서 자연스럽게 읽히는 설명적 앵커 텍스트를 작성할 수도 있습니다. 예를 들어: [Astro 공식 문서](https://docs.astro.build)에서 모든 기능을 자세히 다룹니다. ## 목록 비순서 목록: - 첫 번째 항목 - 두 번째 항목 - 중첩 항목 - 또 다른 중첩 항목 - 세 번째 항목 순서 목록: 1. 첫 번째 단계 2. 두 번째 단계 1. 하위 단계 1 2. 하위 단계 2 3. 세 번째 단계 작업 목록: - [x] 프로젝트 설정 - [x] 첫 번째 글 작성 - [ ] 프로덕션 배포 ### 목록 서식 팁 목록은 웹 글쓰기에서 가장 효과적인 도구 중 하나입니다. 밀도 높은 텍스트를 나누고, 정보를 훑어볼 수 있게 만들며, 순서나 항목 모음을 명확히 전달합니다. **비순서 목록은** 항목에 순서가 없을 때 사용하세요 — 기능, 요구사항, 옵션, 예시. **순서 목록은** 순서가 중요할 때 사용하세요 — 프로세스 단계, 순위, 순서대로 따라야 하는 지침. **작업 목록은** 진행 상황 추적, 프로젝트 체크리스트, 할 일 항목에 사용하세요. 많은 Markdown 뷰어에서 인터랙티브 체크박스로 렌더링되지만, 정적 블로그에서는 시각적 지표로 나타납니다. 목록 항목의 구조를 일관되게 유지하세요. 첫 번째 항목이 동사로 시작하면 모든 항목이 동사로 시작해야 합니다. 첫 번째 항목이 명사구이면 그 패턴을 유지하세요. ## 인용문 > 추상화의 목적은 모호해지는 것이 아니라, 절대적으로 정확할 수 있는 새로운 의미 수준을 만드는 것이다. > > — Edsger W. Dijkstra 중첩 인용문: > 첫 번째 단계 > > > 두 번째 단계 > > > > > 세 번째 단계 ### 인용문 사용법 인용문은 유명인의 말을 인용하는 것 외에도 여러 목적으로 사용됩니다: - **출처 인용** — 다른 기사, 책, 문서를 참조할 때 - **콜아웃** — 중요한 정보나 경고를 강조할 때 - **이메일 스타일 인용** — 응답하는 대화에서 상대방이 한 말을 표시할 때 - **풀 인용** — 자신의 글에서 핵심 구절에 주의를 끌 때 인용문에 저자를 표기할 때는 위의 Dijkstra 예시처럼 별도의 줄에 엠 대시를 붙여 표기하세요. ## 코드 백틱으로 인라인 `코드`를 표시합니다. `getPublishedPosts()` 같은 함수 이름, `src/content/posts/` 같은 파일 경로, `pnpm dev` 같은 명령줄 지시, 본문 중에 나타나는 리터럴 값에 인라인 코드를 사용하세요. 구문 하이라이팅이 적용된 코드 블록: ```typescript interface Post { title: string; date: Date; description?: string; tags?: string[]; draft?: boolean; } function getPublishedPosts(posts: Post[]): Post[] { return posts .filter((post) => !post.draft) .sort((a, b) => b.date.getTime() - a.date.getTime()); } ``` ```css @theme { --font-sans: 'system-ui', sans-serif; --font-serif: 'ui-serif', 'Georgia', serif; } ``` ### 코드 블록 팁 여는 삼중 백틱 뒤에 항상 언어 식별자를 지정하세요. 구문 하이라이팅이 활성화되어 가독성이 크게 향상됩니다. 일반적인 식별자로는 `typescript`, `javascript`, `css`, `html`, `bash`, `json`, `python`, `markdown`이 있습니다. 셸 명령에는 `bash` 또는 `sh`를 사용하세요: ```bash # 의존성 설치 pnpm install # 개발 서버 시작 pnpm dev # 프로덕션 빌드 pnpm build ``` JSON 설정 파일: ```json { "name": "my-blog", "version": "1.0.0", "scripts": { "dev": "astro dev", "build": "astro build" } } ``` 코드 블록은 집중적으로 유지하세요. 전체 파일을 붙여넣기보다 관련 줄만 보여주세요. 컨텍스트가 필요하면 코드가 어디에 있는지 주석을 추가하세요. ## 표 | 기능 | 상태 | 비고 | |---|---|---| | 다크 모드 | 지원 | 라이트 / 다크 / 시스템 | | RSS 피드 | 내장 | `/rss.xml` | | 사이트맵 | 자동 생성 | `@astrojs/sitemap` | | SEO | 내장 | Open Graph + 정규 URL | 오른쪽 정렬 및 가운데 정렬 열: | 왼쪽 | 가운데 | 오른쪽 | |:---|:---:|---:| | 텍스트 | 텍스트 | 텍스트 | | 긴 텍스트 | 긴 텍스트 | 긴 텍스트 | ### 표 가이드라인 표는 명확한 열과 행이 있는 구조화된 데이터에 적합합니다. 기능 비교, 설정 옵션, API 매개변수, 참조 데이터에 이상적입니다. 표를 단순하게 유지하세요. 5~6개 이상의 열이 있는 표는 모바일 기기에서 읽기 어렵습니다. 복잡한 표는 여러 개의 작은 표로 나누거나 대신 목록 형식을 사용하세요. 열 정렬은 구분자 행의 콜론으로 제어합니다: - `:---` 왼쪽 정렬 (기본) - `:---:` 가운데 정렬 - `---:` 오른쪽 정렬 숫자 데이터에는 소수점이 시각적으로 정렬되도록 오른쪽 정렬을 사용하세요. ## 수평선 `---`를 사용하여 수평선을 만듭니다: --- 수평선 이후의 콘텐츠. 수평선은 글의 주요 섹션을 구분하거나, 주제 전환을 나타내거나, 매우 긴 글을 시각적으로 나누는 데 유용합니다. 적절히 사용하세요 — 빈번한 구분이 필요하다면 제목이 더 나은 구조적 선택일 수 있습니다. ## 이미지 이미지는 표준 Markdown 구문으로 지원됩니다: ```markdown ![대체 텍스트](./image.jpg) ``` 이 테마는 타이포그래피 중심이지만, 필요할 때 이미지도 잘 동작합니다. ### 이미지 모범 사례 - **항상 대체 텍스트를 포함하세요** — 접근성에 필수적이며 이미지 로드 실패 시에도 나타납니다 - **설명적인 파일 이름을 사용하세요** — `screenshot-2.png`보다 `dashboard-error-state.png`이 좋습니다 - **파일 크기를 최적화하세요** — 저장소에 추가하기 전에 이미지를 압축하세요; 큰 이미지는 페이지 로드를 느리게 합니다 - **읽기 흐름을 고려하세요** — 이미지를 참조하는 텍스트 근처에 배치하세요, 여러 단락 떨어진 곳이 아니라 ## 마무리 이 가이드에 설명된 Markdown 기능은 블로그 글쓰기에 필요한 대부분을 다룹니다. 좋은 Markdown의 핵심은 올바른 목적에 올바른 요소를 사용하는 것입니다: 구조를 위한 제목, 중요도를 위한 강조, 모음을 위한 목록, 기술 콘텐츠를 위한 코드 블록, 나머지를 위한 단락. 명확하게 쓰고, 일관되게 서식을 지정하고, 타이포그래피가 일하게 하세요.

👋 안녕하세요, 세상

Thu, 01 Jan 2026 08:00:00 GMT

Astro-Theme-Aither에 오신 것을 환영합니다. 이것은 하나의 믿음 위에 만들어진 블로그 테마입니다: 좋은 글은 좋은 타이포그래피를 누릴 자격이 있다. 세리프 제목, 깔끔한 읽기 리듬, 그리고 방해하지 않는 레이아웃. 여기 있는 모든 것은 단 하나의 목표를 위해 존재합니다 — 당신의 글이 아름답게 보이고 느껴지도록 하는 것. ## 또 하나의 블로그 테마를 만든 이유 웹에는 블로그 테마가 넘쳐나니, 왜 또 하나를 만들었는지 묻는 것은 당연합니다. 답은 우선순위에 있습니다. 대부분의 테마는 시각적 임팩트에 최적화합니다 — 큰 히어로 이미지, 복잡한 레이아웃, 애니메이션 전환. 데모에서는 멋지게 보이지만, 누군가가 2,000단어 글을 읽으려 앉으면 오히려 방해가 됩니다. Astro-Theme-Aither는 다른 전제에서 출발합니다. 콘텐츠가 곧 제품입니다. 테마의 역할은 그 콘텐츠를 정성껏 제공하는 것입니다: 세심한 폰트 조합, 넉넉한 여백, 그리고 장문의 읽기를 편안하게 만드는 수직 리듬. 이 철학은 기술적 결정에도 확장됩니다. 이 테마는 약 0.5 KB의 클라이언트 사이드 JavaScript만 전송합니다 — 테마 토글에 필요한 최소한만. 나머지는 모두 정적 HTML과 CSS입니다. 레이아웃 시프트도, 로딩 스피너도, 백그라운드에서 하이드레이팅하는 JavaScript 프레임워크도 없습니다. 페이지가 로드되면, 읽기만 하면 됩니다. ## 시작하기 설정하고 실행하는 데 몇 분이면 충분합니다. 전체 과정은 다음과 같습니다: 1. **저장소 복제** — GitHub 템플릿 버튼을 사용하거나 `git clone`으로 직접 복제 2. **의존성 설치** — `pnpm install`을 실행하여 모든 패키지 설치 3. **사이트 설정** — `src/config/site.ts`를 편집하여 사이트 제목, 설명, 네비게이션 링크 설정 4. **샘플 콘텐츠 교체** — `src/content/posts/`의 글을 자신의 Markdown 파일로 교체 5. **개발 시작** — `pnpm dev`를 실행하여 핫 리로딩이 되는 로컬 개발 서버 실행 6. **배포** — GitHub에 푸시하면 내장된 CI 워크플로우가 Cloudflare Pages 배포를 처리 ### 프로젝트 구조 코드베이스는 즉시 이해할 수 있도록 구성되어 있습니다: ``` src/ ├── components/ # 재사용 가능한 Astro 컴포넌트 ├── config/ # 사이트 설정 ├── content/ # Markdown 글과 콘텐츠 ├── layouts/ # 페이지 레이아웃 (Layout.astro) ├── pages/ # 라우트 페이지 └── styles/ # Tailwind v4 토큰을 사용한 글로벌 CSS ``` 각 디렉토리에는 명확한 역할이 있습니다. 컴포넌트는 작고 조합 가능합니다. 레이아웃은 문서 셸을 처리합니다. 페이지는 라우트를 정의합니다. 콘텐츠는 글을 담고 있습니다. 마법 같은 것은 없습니다 — 잘 정리된 파일들뿐입니다. ### 첫 번째 글 작성 `src/content/posts/`에 다음 프런트매터를 포함하는 새 `.md` 파일을 만드세요: ```markdown --- title: 글 제목 date: "2026-01-15T16:00:00+08:00" category: General description: SEO와 소셜 미리보기를 위한 간단한 요약 tags: [Topic, Another] --- 여기에 내용을 작성하세요. ``` `title`, `date`, `category` 필드는 필수입니다. `description` 필드는 메타 설명 태그와 Open Graph 미리보기를 채우기 때문에 작성을 강력히 권장합니다. 태그는 선택 사항이지만 독자들이 관련 콘텐츠를 발견하는 데 도움이 됩니다. ## 무엇이 포함되어 있나 즉시 사용 가능한 프로덕션 준비 블로깅 플랫폼으로, 필요한 모든 기능을 갖추고 불필요한 것은 없습니다. ### 콘텐츠 기능 - **RSS 피드** — `/rss.xml`에 자동 생성, 모든 피드 리더와 호환 - **사이트맵** — 검색 엔진 인덱싱을 위해 `@astrojs/sitemap`으로 자동 생성 - **SEO 메타 태그** — 모든 페이지에 Open Graph, Twitter 카드, 정규 URL - **다크 모드** — `localStorage` 지속성을 가진 3단 토글 (라이트 / 다크 / 시스템) - **카테고리 및 태그 페이지** — 독자들이 주제별로 탐색할 수 있는 정리된 아카이브 ### 개발자 기능 - **전체 TypeScript** — strict 모드, 완전히 타입이 지정된 컴포넌트와 유틸리티 - **Content Collections** — 빌드 타임 프런트매터 유효성 검사를 포함한 Astro 내장 타입 안전 Markdown 시스템 - **Tailwind CSS v4** — 색상, 폰트, 간격의 손쉬운 커스터마이징을 위한 `@theme` 디자인 토큰 사용 - **Vitest + Playwright** — CI 파이프라인에 이미 연결된 유닛 테스트와 E2E 테스트 - **Cloudflare Pages** — 자동 PR 미리보기 URL이 포함된 배포 워크플로우 - **Google Analytics** — 선택 사항, 메인 스레드를 차단하지 않도록 Partytown Web Worker에서 격리 실행 ### 성능 이 테마는 최소한의 JavaScript로 정적 HTML을 출력하기 때문에 기본적으로 뛰어난 성능을 제공합니다. Lighthouse 점수 전 항목 100점을 기대할 수 있습니다 — Performance, Accessibility, Best Practices, SEO. 불필요한 것이 없기 때문에 최적화할 것도 없습니다. ## 커스터마이징 이 테마는 여러분의 것이 되도록 설계되었습니다. 가장 일반적인 커스터마이징은 간단합니다: - **색상** — `src/styles/global.css`의 CSS 커스텀 프로퍼티를 편집하여 전체 팔레트 변경 - **폰트** — Tailwind 테마 설정에서 font-family 값 교체 - **네비게이션** — `src/config/site.ts`의 네비게이션 링크 배열 업데이트 - **Analytics** — 사이트 설정에서 Google Analytics 측정 ID 추가 더 깊은 변경을 위해 컴포넌트 아키텍처는 의도적으로 단순합니다. 깊게 중첩된 추상화나 복잡한 상태 관리 패턴이 없습니다. 각 컴포넌트는 하나의 일을 하고, props를 읽고, HTML을 렌더링합니다. ## 디자인 철학에 대한 참고 이 테마의 시각적 단순함은 의도적이지만, 엔지니어링적 단순함과는 다릅니다. 내부적으로 이 테마는 놀라울 정도로 많은 것을 처리합니다: 반응형 타이포그래피 스케일, 라이트 및 다크 모드 모두에서의 접근 가능한 색상 대비, 올바른 시맨틱 HTML 구조, 올바른 제목 계층 구조, 그리고 휴대폰부터 울트라와이드 모니터까지 다양한 화면에서의 읽기 경험에 대한 세심한 주의. 좋은 디자인은 보이지 않습니다. 이 테마에서 글을 읽을 때 테마를 전혀 의식하지 않고 글 자체를 즐기게 된다면 — 바로 그것이 의도한 대로 디자인이 작동하는 것입니다. 즐거운 글쓰기 되세요.