Skip to content

Latest commit

 

History

History
315 lines (260 loc) · 9.08 KB

documentation.md

File metadata and controls

315 lines (260 loc) · 9.08 KB
Raw

Writing documentation and guides

This document holds all the information that is relevant to maintain and contribute the content for each if its packages.

Collections

Pages inside Grow are stored in so called collections. A collection is established by creating a _blueprint.yaml in a directory. The following fields are evaluated by the amp.dev setup:

# If true on a collection, "Get started" and "Previous chapter" and "Next chapter"
# link are automatically added to the bottom of the page
chaptered: true|false

Documents

Frontmatter

The documents inside the pages package are Grow documents that use the built-in fields and some additional ones that are used to categorize them:

formats [default: websites,ads,email,stories]:
  - websites
  - ads
  - email
  - stories
status [default: production]:
  - experimental
  - canary
  - production
validAmp [default: true]
  - true
  - false
draft [default: true]
  - true
  - false
tags [default: '']
  - ads-analytics
  - dynamic-content
  - layout
  - media
  - presentation
  - social
  - personalization

Format filtering documents

By the categorization via the formats list in the frontmatter the user is able to filter the documentation by one of the formats. The filtered variants of each page get generated during build time but you are also able to create custom filtered ones by duplicating the document you want to filter it and append the format it is going to be filtered by. So for example a filtered version of [email protected] becomes index.ads.md.

If the document has a specific path that is not getting inherited from the _blueprint.yaml also make sure to set a matching path. Same example: index.md has $path: /category.html then index.ads.md needs to have $path: /category.ads.html. Otherwise the build process is not able to match the base and the filtered variant. To not have double navigation items make sure to also give $hidden: true to the filtered variant.

Format filtered paragraphs

Documents will be relevant to multiple formats on a broad scope, but may contain sections and paragraphs that are not accurate for all formats listed in the frontmatter. You can wrap paragraphs in a filter to hide or show them, depending on what format the user has selected.

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

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

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

Shortcodes

The project enables various shortcodes to extend the basic functionality of markdown.

Tip

[tip type="default|important|note|read-on"]
# Headline
Text.
[/tip]

The type=default can be omitted.

Video

[video src="https://www.youtube.com/watch?v=npum8JsITQE" caption="This is the caption text."]

The video ID (npum8JsITQE in the above example) will be extracted automatically.

Stage

<section class="ap--stage ap--container-fluid">
[stage format="websites|stories|ads|emails"]
## What is AMP?
# AMP is a web component framework for easily creating user first

[Get Started](/content/amp-dev/documentation/guides-and-tutorials/index.md)
[/stage]
</section>

The Link is optional and will create a button inside the stage.

Teaser grid

[teaser-grid]
[](/content/shared/fill-ins/success-story.md)
[](/content/shared/fill-ins/success-story-2.md)
[](/content/shared/fill-ins/success-story.md)

[All success stories](#)
[/teaser-grid]

A list of links that will expand to a row of cards that link to the document.

Importing AMP Components

Import AMP components via:

{% do doc.amp_dependencies.add('amp-anim', '0.1') %}

Code Samples

Code samples are placed inside sets of three backticks. The sourcecode language specified at the end of the first backtick set.

```html
  // code sample
```

```css
  // code sample
```

```js
  // code sample
```

If your code contains double curly braces, which often is the case if you use amp-mustache templates, you have to wrap the code part:

```html
{% raw %}
  // code with double curly braces
{% endraw %}
```

Code samples in lists

Python-Markdown has some limitations. Use the following syntax when including code samples in lists:

  
  1. First:
    [sourcecode:html]
      <html>
          <p>Indented content.</p>
      </html>
    [/sourcecode]
  2. Second
  3. Third

Code samples with preview

You can let a code sample have a preview or a link to open the code sample in the AMP Playground:

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

Use the preview attribute to define how the preview is generated:

  • none: No preview will be generated

  • inline: The example preview is displayed above the source code. An inline preview is only possible for normal website examples if the code does not contain any head elements. Use this option for small examples that do not need any styling or other head elements (imports do not count, since they are specified via the imports attribute).

  • top-frame: The example preview is displayed above the source code inside an iframe. The orientation can be toggled between portrait and landscape mode. You can preselect the orientation by specifying the additional attribute:

    • orientation: default: landscape|portrait

If custom elements are needed, specify them in the imports attribute as a comma separated list with the name of the component followed by a colon and the version.

For email content with resource links use the placeholder {{server_for_email}} in the source.

  
[example preview="top-frame" orientation="portrait"
         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]

SUCCESS STORY (EXAMPLE STRUCTURE)

Arrays can contain multiple elements. The media source can be image_src or video_src.

Leave the device.direction property empty to get a flat front view. Device.layouts and their ratios:

  • Desktop: 8:5
  • Tablet: 4:3
  • Mobile: 3:5

The order of contents' elements is equal to the order of the resulting page. Content layouts:

  • media + text
  • media only
  • text only
  • quote
  • text with media + button

The stage has the ability to display three different device layouts:

  • all (Three elements with devices.type desktop, tablet and mobile)
  • tablet-mobile (Two elements with devices.type tablet and mobile)
  • mobile (One element with devices.type mobile) Other combinations aren't allowed and can lead to broken layouts.
stage:
  headline: <string>
  subline: <string>
  layout: [all | tablet-mobile | mobile]
  devices:
    - image_src: [url] | video_src: [url]
      width: <number>
      height: <number>
      type: [mobile |  tablet | desktop] (depends on the layout)
      direction: [left | right | left-flat | right-flat] (optional)
      alt: <string>
      poster_src: [url]
      artwork_src: [url]
      video_title: <string>
      video_artist: <string>
      video_album: <string>

kpis:
  - value: <string>
    text: <string> (optional)

contents:
  #(media + text)
  - layout: text-media
    image_src: [url] | video_src: [url]
    width: <number>
    height: <number>
    type: [mobile |  tablet | desktop] (optional)
    direction: [left | right | left-flat | right-flat] (optional)
    alt: <string>
    headline: <string> (optional)
    text: <string>
    background: [gradient | gray]

  #(media only)
  - layout: media
    image_src: [url] | video_src: [url]
    width: <number>
    height: <number>
    type: [mobile |  tablet | desktop] (optional)
    direction: [left | right | left-flat | right-flat] (optional)
    alt: <string>

  #(text only)
  - layout: text
    headline: <string> (optional)
    text: <string>

  #(quote)
  - layout: quote
    quote: <string>
    image_src: [url]
    width: <number>
    height: <number>
    alt: <string>
    author: <string>
    story_url: [url]

  #(text + media + button)
  - layout: text-button
    image_src: [url] | video_src: [url]
    width: <number>
    height: <number>
    type: [mobile |  tablet | desktop] (optional)
    direction: [left | right | left-flat | right-flat] (optional)
    alt: <string>
    headline: <string> (optional)
    text: <string>
    download_url: [url]
    background: [gradient | gray]