Formatting Tips

Details on writing code for pages on www.dartlang.org. These tips do not apply to API docs; for those, see Guidelines for Dart Doc Comments.

• Top matter
  • YAML setup code
    • Choosing a collection
  • Title, author, date
• Notes and warnings
• Code (prettify)
• Advanced {% … %}
  • comment
  • highlight (for code samples)
  • include
  • raw
  • capture
  • Custom stuff
• Tips and workarounds
  • Markdown inside of HTML inside of markdown

Top matter

YAML setup code

---
layout: default
title: "Creating Streams in Dart"
rel:
  author: lasse-nielsen
description: "A Stream is a sequence of results; learn how to create your own."
has-permalinks: true
article:
  written_on: 2013-03-12
  collection: libraries-and-apis
---

The value of "collection" determines where in the Articles page your article goes. Choose one of these:

• everyday-dart
• language-details
• libraries-and-apis
• design-decisions
• performance

Boilerplate for the top of the file

---
layout: default
title: "Creating Streams in Dart"
rel:
  author: lasse-nielsen
description: "A Stream is a sequence of results; learn how to create your own."
has-permalinks: true
article:
  written_on: 2013-03-12
  collection: libraries-and-apis
---

# {{ page.title }}
{: .no_toc}

<em>Written by Bob Smith<br />
<time pubdate date="2012-11-21">November 2012</time>
</em>

A summary, no more than two paragraphs.

{% include toc.html %}

## Your first header

Notes and warnings

A note:

<aside class="alert alert-info" markdown="1">
**Note:**
…
</aside>

A warning:

<aside class="alert alert-warning" markdown="1">
**Warning:**
…
</aside>

You can use different bold text (or none at all) if needed.

Code (prettify)

{% prettify dart %}
// Code goes here...
{% endprettify %}

Instead of dart, you can use sh, html, js, yaml, or anything else that prettify supports.

Advanced {% … %}

comment

Create a comment that won’t show up in the HTML:

{% comment %}...{% endcomment %}

highlight (for code samples)

https://chromiumcodereview.appspot.com/19291003/ gives us the ability to highlight pieces of code. Try it:

[[highlight]]var x = 1;[[/highlight]]

It will turn into the appropriate <span> with a "highlight" class.

include

Include a file:

{% include downloads/_dart-editor.html %}

raw

Used by dart-web-components to avoid problems with {{...}}.

{% raw %}
{% endraw %}

Also see: dart-web-components/index.markdown:{% codesampleSetup %}

capture

You can go even further and build docs based on a template, as the tutorials do. For example, from /docs/tutorials/custom-elements/index.markdown:

{% capture whats_the_point %}
{% endcapture %}
{% capture content %}
...
{% endcapture %}
{% include tutorial.html %}

Custom stuff

You can define custom tags in /src/site/_plugins. For example, when Siggi wrote the Web UI articles, he created _plugins/code_sample.rb, which defines codesample and codesampleSetup, along with tags they can contain (srcprefix, iframeprefix, iframe, and source).

From /articles/dart-web-components/index.markdown:

{% codesampleSetup %}
{% srcprefix https://github.com/dart-lang/web-ui/blob/master/example/explainer/ %}
{% iframeprefix example/ %}
{% endcodesampleSetup %}
...
{% codesample 90 %}
{% prettify html %}
{% raw %}
{% endraw %}
{% endprettify %}
{% source helloworld.html %}
{% iframe 300px 200px helloworld.html %}
{% endcodesample %}

Tips and workarounds

Markdown inside of HTML inside of markdown

To use markdown inside an HTML element, specify markdown=”1”. E.g.:

<aside class="alert alert-info" markdown="1">
**Note:**
...