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. For more information about contributing to www.dartlang.org, see Writing for dartlang.org.

• Line length
• 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

Line length

We'll love you more if you break lines on phrases and keep your lines short (80 characters or less). These techniques make diffs shorter, so it's easier to tell what changed and why. For an example, see the source for the doc comment guidelines article.

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:**
...