AMP
PL
English Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Tiếng việt

Przewodniki i samouczki dotyczące formatowania

Przewodniki i samouczki należy przesyłać w formacie Markdown, z dodatkowym formatowaniem sekcji frontmatter i szortkodów.

Lokalizacje dokumentacji

Treść na amp.dev jest pobierana z dwóch repozytoriów, amp.dev i AMPHTML. Cała dokumentacja referencyjna pod składnikami jest pobierana z AMPHTML, albo z obiektów wbudowanych, albo z rozszerzeń.

Jest kilka innych dokumentów, które są importowane do amp.dev z AMPHTML. Ich listę zawiera ten plik. Nie aktualizuj tych dokumentów w repozytorium amp.dev — Twoje zmiany zostaną zastąpione w kolejnych kompilacjach!

Sekcja frontmatter

U góry każdego przewodnika i samouczka znajduje się sekcja frontmatter.

Przykład:

$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 Tytuł dokumentu w takiej postaci, w jakiej będzie widnieć w spisie treści. Wpisz wielką pierwszą literę pierwszego słowa, z wyjątkiem słowa „AMP” i innych nazw własnych. Używaj znaków „handlowego i” (&), zamiast słowa „and”.
$order Określ, gdzie w spisie treści pojawi się Twój dokument. Być może, aby pojawił się on we właściwym miejscu, konieczna będzie edycja zmiennej „$order” w innych dokumentach.
formats Lista zastosowań AMP, których dotyczy dokument. Jeśli Twój dokument dotyczy witryn internetowych AMP i relacji AMP, ale nie reklam AMP ani wiadomości e-mail AMP, sekcja frontmatter będzie wyglądać następująco: ```yaml formats: - witryny internetowe - relacje ```
author Autor to Ty! Użyj swojej nazwy użytkownika GitHub.
contributors Podaj listę wszystkich osób, które przyczyniły się do powstania dokumentu. To pole jest opcjonalne.
description Napisz krótki opis swojego przewodnika lub samouczka. Pomoże to w optymalizacji dla wyszukiwarek internetowych i przekazaniu Twojego dzieła tym, którzy go potrzebują!
tutorial Dodaj wpis `tutorial: true` do sekcjii frontmatter witryny internetowej, aby dodać ikonę samouczka obok niej. Samouczki znajdują się w dolnej części swojej sekcji w spisie treści.

Szortkody

Listę szortkodów i ich zastosowań znajdziesz w pliku documentation.md na GitHub.

Obrazy

Witryna amp.dev jest utworzona z użyciem technologii AMP! Dlatego też nasze obrazy muszą spełniać kryteria amp-img . W procesie kompilacji do konwersji obrazów na prawidłowy format amp-img stosowana jest następująca składnia.

Sekcje filtrujące

Niektóre dokumenty mogą dotyczyć wielu formatów AMP, natomiast niektóre formaty mogą wymagać dalszych wyjaśnień lub informacji, które nie dotyczą innych. Możesz filtrować te sekcje, opakowując je w poniższy szortkod.

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

Porady

Możesz dodawać porady i objaśnienia, opakowując tekst w następujący szortkod:

[tip type="default"]
Default tip
[/tip]

Ważne

Uwaga

Czytaj dalej

Fragmenty kodu

Umieść fragmenty kodu wewnątrz zestawów złożonych z trzech odwróconych apostrofów, określ język na końcu pierwszego zestawu odwróconych apostrofów.

```html
  // code sample
```
  // code sample

  // code sample

Jeśli Twój kod zawiera podwójne nawiasy klamrowe, co jest częste, gdy używasz szablonów amp-mustache, musisz opakować część z kodem:

```html

  // code with double curly braces

```

Fragmenty kodu na listach

Język Python-Markdown ma pewne ograniczenia. Dodając fragmenty kodu na listach, używaj następującej składni:

1. First:
    [sourcecode:html]
      
        
Indented content.

      
    [/sourcecode]
  2. Second
  3. Third

Podgląd próbek kodu

Próbki kodu mogą mieć podgląd i/lub link do wersji placu zabaw AMP.

  [example preview="default: none|inline|top-frame"
          playground="default: true|false"
          imports="{custom-element-10},{custom-element-21},..."           template="{custom-template2}"]   ```html     // code sample   ```   [/example]   {/custom-template2}{/custom-element-21}{/custom-element-10}

Uwaga: podgląd zostanie automatycznie przekształcony na aktualnie wybrany format po otwarciu go w placu zabaw 🤯!

Aby określić sposób generowania podglądu, użyj atrybutu preview:

  • none: podgląd nie będzie generowany

  • inline: przykładowy podgląd wyświetlany jest nad kodem źródłowym. Podgląd inline jest możliwy w przypadku normalnych przykładów witryn internetowych, jeśli kod nie zawiera żadnych elementów head. Użyj tej opcji w przypadku małych przykładów, które nie wymagają żadnej stylizacji lub innych elementów head (import nie liczy się, ponieważ jest określany za pomocą atrybutu imports).

  • top-frame: Przykładowy podgląd wyświetlany jest nad kodem źródłowym w ramce iframe. Orientację można przełączać pomiędzy trybem portrait i landscape. Orientację można wstępnie wybrać poprzez określenie dodatkowego atrybutu:

  • orientation: default: landscape|portrait

Jeśli konieczne są elementy niestandardowe, określ je w atrybucie imports jako rozdzielaną przecinkami listę z nazwą składnika, po której następuje dwukropek i wersja. Jeśli w kodzie stosowany jest składnik amp-mustache, określ zamiast tego zależność w atrybucie template.

W przypadku treści wiadomości e-mail z linkami do zasobów, użyj w źródle symbolu zastępczego .

Próbka kodu inline

Oto prosta próbka osadzenia kodu inline. Możesz definiować CSS za pomocą stylów inline:

  



  

     
Hello World

  


    ```html
    
Hello World

    ```
  [/example]
  [/example]

Wygląda to tak:

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

<div style="background: red; width: 200px; height: 200px;">Hello World</div>
Otwórz ten fragment kodu w placu zabaw

Ostrzeżenie: próbki kodu inline są osadzane bezpośrednio w stronie. Może to prowadzić do konfliktów, jeśli składniki (np. amp-consent) są już używane na stronie.

Podgląd górnej ramki

Używaj podglądu górnej ramki zawsze wtedy, gdy musisz określić elementy nagłówka lub zdefiniować globalne style w składniku <style amp-custom>.

Ważne: nie dodawaj żadnego standardowego kodu AMP do nagłówka, ponieważ zostanie on dodany automatycznie na podstawie formatu AMP. Do nagłówka dodawaj tylko te elementy, które są wymagane w próbce!

  [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]

Wygląda to tak:

 
<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>
Otwórz ten fragment kodu w placu zabaw

Relacje AMP

W celu generowania podglądu relacji AMP stosuj atrybut preview="top-frame" z właściwością 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]

Wygląda to tak:

 
  <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>
Otwórz ten fragment kodu w placu zabaw

Bezwzględne adresy URL poczty elektronicznej AMP

Zwróć uwagę, jak używamy do utworzenia bezwzględnego adresu URL punktu końcowego, jeśli jest on wbudowany w wiadomość e-mail AMP.

  


  
    
  
  
    
  
  
    
  

  


    

      

      
    


    
      

    
  



    ```html
    
            

    ```
  [/example]

Wygląda to tak:

[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>
Otwórz ten fragment kodu w placu zabaw

Opatrywanie szablonów mustache znakami ucieczki

Oto przykład top-frame wykorzystujący zdalny punkt końcowy. Szablony mustache muszą być oddzielone w próbkach przy użyciu znaczników i :

[example preview="top-frame"
        playground="true"
        imports="amp-list:0.1"
        template="amp-mustache:0.2"]
    ```html
    <amp-list width="auto" height="100" layout="fixed-height"
      src="{{server_for_email}}/static/inline-examples/data/amp-list-urls.json">
      <template type="amp-mustache">{% raw %}
        <div class="url-entry">
          <a href="{{url}}">{{title}}</a>
        </div>
      {% endraw %}
      </template>
    </amp-list>
    ```
[/example]

Wygląda to tak:

 
<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>
Otwórz ten fragment kodu w placu zabaw

Linki

Możesz wstawiać linki do innych stron za pomocą standardowej składni linków języka Markdown:

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

W przypadku umieszczenia linku do innej strony na amp.dev odnośnikiem będzie ścieżka względna do pliku docelowego.

Kotwice

Linki do poszczególnych części dokumentu wstawia się za pomocą kotwic:

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

Przed wstawieniem linku prowadzącego do sekcji, w której nie ma kotwicy należy utworzyć cel kotwicy, używając selektora <a name="#anchor-name></a>. Dobrym miejscem na to jest koniec nagłówka sekcji:

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

W kotwicy należy używać jedynie liter, cyfr, znaku kreski i podkreślenia. Używaj krótkich nazw kotwic w języku angielskim, które pasują do nagłówka lub opisują daną sekcję. Upewnij się, że nazwa kotwicy jest niepowtarzalna w dokumencie.

W razie tłumaczenia strony nazw kotwic nie wolno zmieniać i muszą one pozostać w języku angielskim.

W razie tworzenia kotwicy, która zostanie użyta w linku z innej strony należy również utworzyć taką samą kotwicę we wszystkich tłumaczeniach.

Filtr formatów AMP

Dokumentacja składników, przewodniki i tutoriale oraz przykłady można filtrować przy użyciu formatu AMP, takiego jak witryny internetowe AMP lub relacje AMP. Podczas wstawiania linku do takiej strony należy jawnie określić format, który jest obsługiwany przez cel, dołączając do linku parametr formatu:

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

Parametr można pominąć tylko mając pewność, że cel obsługuje  wszystkie formaty, które obsługuje Twoja strona.

Odnośniki do składników.

Jeśli w linku pominiesz część dotyczącą wersji, link do dokumentacji referencyjnej składnika będzie automatycznie wskazywać na najnowszą wersję. Aby jawnie wskazać wersję, podaj jej pełną nazwę:

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

Struktura dokumentów

Tytuły, nagłówki i śródtytuły

Pierwsza litera pierwszego słowa w tytułach, nagłówkach i śródtytułach jest pisana wielką literą, po której następują małe litery. Wyjątkiem jest AMP i inne nazwy własne. Żaden nagłówek nie ma tytułu Introduction, wstępy następują po tytule dokumentu.

Nazewnictwo dokumentów

Dokumentom należy nadawać nazwy w konwencji z kreskami.


Dobrze Źle
hello-world-tutorial.md hello_world_tutorial.md
website-fundamentals.md websiteFundamentals.md
actions-and-events.md actionsandevents.md