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]
Widoczna tylko w przypadku witryn internetowych.
Widoczna tylko w przypadku witryn internetowych i poczty elektronicznej.
Porady
Możesz dodawać porady i objaśnienia, opakowując tekst w następujący szortkod:
[tip type="default"]
Default tip
[/tip]
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ówhead(import nie liczy się, ponieważ jest określany za pomocą atrybutuimports). -
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
portraitilandscape. 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>
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>
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>
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>
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>
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 |
-