서식 지정 가이드 & 튜토리얼

가이드 및 튜토리얼은 마크다운에 추가 프론트매터 및 숏코드 서식 지정과 함께 제시되어 있습니다.

문서 위치

amp.dev 콘텐츠는 amp.dev 및 AMPHTML의 저장소 두 곳에서 가져옵니다. 컴포넌트의 모든 참조 문서는 AMPHTML의 'builtins' 또는 'extensions'에 포함되어 있습니다.

AMPHTML에서 amp.dev로 가져온 기타 여러 문서들이 있습니다. 해당 문서는 다음 파일에서 제공됩니다. amp.dev 저장소에서 문서를 업데이트하지 마세요. 변경 사항이 후속 빌드에 덮어쓰기 될 수 있습니다!

프론트매터

프론트매터는 각 가이드 및 튜토리얼의 최상단에 위치합니다.

예제:

$title: Include Custom JavaScript in AMP Pages
$order: 7
formats:
  - websites
author: CrystalOnScript
contributors:
  - fstanis
description: For web experiences requiring a high amount of customization AMP has created amp-script, a component that allows the use of arbitrary JavaScript on your AMP page without affecting the page's overall performance.

`$title`	콘텐츠 목차에 표시되는 문서의 제목입니다. "AMP" 및 기타 고유 명사를 제외한 첫 번째 단어의 첫 번째 문자는 대문자로 처리합니다. `and`라는 단어 대신 앰퍼샌드 `&` 기호를 사용합니다.
`$order`	문서의 콘텐츠 목차가 표시되는 위치를 정의합니다. 올바른 위치에 표시되게 하려면 다른 문서의 `$order`를 편집해야 할 수도 있습니다.
`formats`	문서와 관련된 AMP 경험을 나열합니다. 문서가 AMP 웹사이트 및 AMP 스토리와 관련되었으나 AMP 광고 또는 AMP 이메일과는 관련이 없을 시 Frontmatter는 다음과 같이 작성됩니다: ```yaml formats: - websites - stories ```
`author`	작성자는 여러분입니다! GitHub 사용자 이름을 사용하세요.
`contributors`	문서 기여자 목록이 나열됩니다. 이 필드는 선택 사항입니다.
`description`	가이드 또는 튜토리얼에 대한 간략한 설명을 작성합니다. 검색 엔진 최적화에 도움이 되므로, 여러분의 작업을 필요한 사람이 발견할 수 있습니다!
`tutorial`	웹사이트에서 프론트매터 옆에 튜토리얼 아이콘을 추가하려면 `tutorial: true`를 추가합니다. 튜토리얼은 콘텐츠 목차의 섹션 하단에 있습니다.

숏코드

숏코드 목록 및 활용 사례는 GitHub의 documentation.md에서 확인하실 수 있습니다.

이미지

amp.dev는 AMP로 작성되었습니다! 그렇기에 이미지는 amp-img 기준에 부합합니다. 빌드 프로세스에서 이미지를 amp-img 형식으로 변환하는 데 다음 구문이 활용되었습니다.

섹션 필터링

일부 문서는 여러 AMP 형식과 연관되었을 수 있지만 이러한 형식에는 다른 것들과 연관성 없는 추가 설명 또는 정보가 필요할 수도 있습니다. 다음 숏코드로 섹션을 래핑하여 필터링할 수 있습니다.

&lsqb;filter formats="websites"]
This is only visible for [websites](?format=websites).
&lsqb;/filter]

&lsqb;filter formats="websites"]
This is only visible for [websites](?format=websites).
&lsqb;/filter]

&lsqb;filter formats="websites, email"]
This is visible for [websites](?format=websites) & [email](?format=email).
&lsqb;/filter]

&lsqb;filter formats="stories"]
This is visible for [stories](?format=stories).
&lsqb;/filter]

팁

다음 숏코드에 텍스트를 래핑하여 팁과 콜아웃을 추가할 수 있습니다.

&lsqb;tip type="default"]
Default tip
[/tip]

&lsqb;tip type="important"]
Important
[/tip]

&lsqb;tip type="note"]
Note
[/tip]

&lsqb;tip type="read-on"]
Read-on
[/tip]

코드 조각

백틱(`) 기호 3개 사이에 코드 조각을 배치하고 첫 번째 백틱 세트 끝부분에서 언어를 지정합니다.

```html
  // code sample

```css
// code sample

  // code sample
```</pre></div>

[`amp-mustache`](../../../../documentation/components/reference/amp-mustache.md?format=websites) 템플릿을 활용하면 자주 그렇듯 코드에 중괄호가 두 개 포함된 경우 코드 부분을 래핑해야 합니다.

<div class="ap-m-code-snippet"><pre>```html<br><br>  // code with double curly braces<br><br>```</pre></div>

### 목록의 코드 조각

Python 마크다운에는 일부 제한이 있습니다. 목록에 코드 조각을 포함할 시 다음 구문을 활용하세요.

<div class="ap-m-code-snippet"><pre>&lsqb;sourcecode:html]
      <html>
        <p>Indented content.</p>
      </html>
    &lsqb;/sourcecode]</pre></div>

## 코드 샘플 미리보기

코드 샘플에 미리보기 또는 [AMP Playground](https://playground.amp.dev/) 버전 링크를 포함할 수 있습니다.

<div class="ap-m-code-snippet">
  <pre>&lsqb;example preview="default: none|inline|top-frame"
          playground="default: true|false"
          imports="<custom-element-1>,<custom-element-2>,..."
          template="<custom-template>"]
  ```html
    // code sample

[/example]

미리보기는 Playground에서 열었을 때 선택한 최근 형식으로 자동 변환됩니다🤯!

preview 속성을 활용하여 미리보기 생성 방식을 정의합니다.

none: 미리보기가 생성되지 않습니다.
inline: 예제 미리보기가 소스 코드 상단에 표시됩니다. 인라인 미리보기는 코드에 head 요소가 포함되지 않은 경우 일반 웹사이트 예제에서만 제공됩니다. 스타일 지정이나 기타 head 요소가 필요하지 않은 작은 예제에서만 이 옵션을 선택하세요(가져오기는 imports 속성으로 지정되므로 해당되지 않습니다).
top-frame: 예제 미리보기가 iframe 내부에서 소스 코드 상단에 표시됩니다. 방향은portrait 및 landscape 모드 중 선택할 수 있으며, 추가 속성을 지정하여 방향을 사전 선택할 수도 있습니다.
orientation: default: landscape|portrait

사용자 지정 요소가 필요한 경우 쉼표로 구분되고 콜론과 버전이 뒤에 표시되는 컴포넌트 이름의 목록처럼 imports 속성으로 지정합니다. 코드에서 amp-mustache가 사용된다면 template 속성에서 대신 종속성을 지정합니다.

리소스 링크가 포함된 이메일 콘텐츠의 경우 소스에 플레이스홀더를 사용합니다.

인라인 샘플

간단한 인라인 샘플 임베드입니다. 인라인 스타일로 CSS를 정의할 수 있습니다.



  
     Hello World
  
    ```html
    Hello World
    ```
  [/example]

다음과 같이 표시되어야 합니다:

[example preview="inline" playground="true"]

<div style="background: red; width: 200px; height: 200px;">Hello World</div>

이 코드 조각을 Playground에서 열기

인라인 샘플은 페이지에 바로 임베드 되므로 컴포넌트가 해당 페이지에 이미 사용된 경우 충돌이 발생할 수 있습니다(예: amp-consent).

탑프레임 미리보기

헤더 요소를 제정하거나 <style amp-custom> 내부에서 전역 스타일을 정의해야 할 경우 탑프레임 미리보기를 사용하세요.

AMP 보일러플레이트 코드는 AMP 형식에 따라 자동으로 추가되므로 헤더에 추가하지 않습니다. 헤더에는 샘플로 필요한 요소만을 추가합니다!

  [example preview="top-frame"
         playground="true"]
    ```html
    <head>
      <script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"></script>
      <style amp-custom>
        body {
          background: red;
        }
      </style>
    </head>
    <body>
      <h1>Hello AMP</h1>
      <amp-youtube width="480"
        height="270"
        layout="responsive"
        data-videoid="lBTCB7yLs8Y">
      </amp-youtube>
    </body>
    ```
  [/example]

다음과 같이 표시되어야 합니다:

<head>
  <script
    async
    custom-element="amp-youtube"
    src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"
  ></script>
  <style amp-custom>
    body {
      background: red;
    }
  </style>
</head>
<body>
  <h1>Hello AMP</h1>
  <amp-youtube
    width="480"
    height="270"
    layout="responsive"
    data-videoid="lBTCB7yLs8Y"
  >
  </amp-youtube>
</body>

이 코드 조각을 Playground에서 열기

AMP 스토리

AMP 스토리 미리보기 시 preview="top-frame"과 orientation="portrait"을 함께 사용합니다.

  [example preview="top-frame"
         orientation="portrait"
         playground="true"]
    ```html
    <head>
      <script async custom-element="amp-story"
          src="https://cdn.ampproject.org/v0/amp-story-1.0.js"></script>
      <style amp-custom>
        body {
          font-family: 'Roboto', sans-serif;
        }
        amp-story-page {
          background: white;
        }
      </style>
    </head>
    <body>
      <amp-story standalone>
        <amp-story-page id="cover">
          <amp-story-grid-layer template="vertical">
            <h1>Hello World</h1>
            <p>This is the cover page of this story.</p>
          </amp-story-grid-layer>
        </amp-story-page>
        <amp-story-page id="page-1">
          <amp-story-grid-layer template="vertical">
            <h1>First Page</h1>
            <p>This is the first page of this story.</p>
          </amp-story-grid-layer>
        </amp-story-page>
      </amp-story>
    </body>
    ```
  [/example]

다음과 같이 표시되어야 합니다:

<head>
  <script
    async
    custom-element="amp-story"
    src="https://cdn.ampproject.org/v0/amp-story-1.0.js"
  ></script>
  <style amp-custom>
    body {
      font-family: 'Roboto', sans-serif;
    }
    amp-story-page {
      background: white;
    }
  </style>
</head>
<body>
  <amp-story standalone>
    <amp-story-page id="cover">
      <amp-story-grid-layer template="vertical">
        <h1>Hello World</h1>
        <p>This is the cover page of this story.</p>
      </amp-story-grid-layer>
    </amp-story-page>
    <amp-story-page id="page-1">
      <amp-story-grid-layer template="vertical">
        <h1>First Page</h1>
        <p>This is the first page of this story.</p>
      </amp-story-grid-layer>
    </amp-story-page>
  </amp-story>
</body>

이 코드 조각을 Playground에서 열기

AMP 이메일의 절대 URL

AMP 이메일에 엔드포인트 URL이 임베드 될 경우 를 활용하여 절대 경로로 지정하는 방법을 참조하세요.

다음과 같이 표시되어야 합니다:

[example preview="top-frame" playground="true"]

<div class="resp-img">
  <amp-img
    alt="flowers"
    src="/static/inline-examples/images/flowers.jpg"
    layout="responsive"
    width="640"
    height="427"
  ></amp-img>
</div>

이 코드 조각을 Playground에서 열기

이스케이핑 mustache 템플릿

원격 엔드포인트를 사용한 top-frame 샘플입니다. 및을 활용하여 Mustache 템플릿을 이스케이핑 처리해야 합니다.

다음과 같이 표시되어야 합니다:

[example preview="top-frame" playground="true" imports="amp-list:0.1" template="amp-mustache:0.2"]

<amp-list
  width="auto"
  height="100"
  layout="fixed-height"
  src="/static/inline-examples/data/amp-list-urls.json"
>
  <template type="amp-mustache"
    >
    <div class="url-entry">
      <a href="{{url}}">{{title}}</a>
    </div>
  </template>
</amp-list>

이 코드 조각을 Playground에서 열기

링크

표준 마크다운 링크 구문으로 다른 페이지로 연결할 수 있습니다.

[link](../../../courses/beginning-course/index.md)

amp.dev에 다른 페이지를 연결할 경우 참조는 대상 파일에 상대 파일 경로가 됩니다.

앵커

문서에서 앵커를 사용해 특정 섹션으로 연결합니다.

[link to example section](#example-section)

앵커가 없는 섹션으로 연결하기 전 <a name="#anchor-name></a>를 사용해 앵커 대상을 생성합니다. 섹션 헤드라인의 끝부분이 적합합니다.

## Example section <a name="example-section"></a>

앵커에는 문자, 숫자, 대시 및 밑줄 기호만 사용되어야 합니다. 헤드라인과 일치하거나 섹션을 설명하는 앵커 이름을 영어로 짧게 작성합니다. 또한 앵커 이름이 문서 안에 하나만 있도록 지정합니다.

페이지를 번역한 경우 앵커 이름은 변경되지 않고 영어로 남아 있어야 합니다.

다른 페이지의 링크에 사용할 앵커를 생성하면 모든 번역에 동일한 앵커를 생성해야 합니다.

AMP 형식 필터

AMP 웹사이트나 AMP 스토리와 같은 AMP 형식으로 컴포넌트 문서, 가이드 및 튜토리얼, 예제를 필터링할 수 있습니다. 이러한 페이지를 링크로 연결할 경우, 링크에 형식 매개변수를 추가하여 대상에서 지원되는 형식을 명시적으로 지정해야 합니다.

[link](../../learn/amp-actions-and-events.md?format=websites)

페이지에 사용된 모든 형식이 대상에서 지원된다고 확신할 경우에만 매개변수를 생략할 수 있습니다.

컴포넌트 참조

링크에서 버전 부분이 생략될 경우 컴포넌트 참조 문서 링크는 자동으로 최신 버전을 지정합니다. 버전을 명시적으로 지정하고 싶을 경우 전체 이름을 지정하세요.

[latest version](../../../components/reference/amp-carousel.md?format=websites)
[explicit version](../../../components/reference/amp-carousel-v0.2.md?format=websites)

문서 구조

제목, 헤딩 및 하위 헤딩

제목, 헤딩 및 하위 헤딩에서 사용된 첫 번째 단어의 첫 번째 문자는 대문자로 표기하고 그 다음은 소문자로 작성합니다. 예상 값에는 AMP 및 고유 명사가 포함됩니다. 헤딩 제목에는 Introduction을 사용하지 않으며 문서 제목 다음에는 서문을 입력합니다.

문서 이름 지정

문서 이름은 대시 이름 지정 규칙에 따라 지정합니다.

Do	Don’t
hello-world-tutorial.md	hello_world_tutorial.md
website-fundamentals.md	websiteFundamentals.md
actions-and-events.md	actionsandevents.md

Written by @CrystalOnScript