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
  • After the YAML
  • Breadcrumbs
• 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 future diffs shorter, so it's easier to tell what changed and why. For example (from the source for the doc comment guidelines article):

Format your text using the markup
specified in section 15.1.2 of the
[Dart Language Specification](/docs/spec/).
Although dartdoc currently recognizes some additional markdown
(as noted below),
it might not always.

Top matter

YAML setup code

---
layout: article
title: "Idiomatic Dart"
rel:
  author: bob-nystrom
description: 'Learn how to write code that looks and feels like Dart.'
has-permalinks: true
article:
  written_on: 2011-10-01
  updated_on: 2013-03-12
  collection: everyday-dart
---

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

After the YAML

After the YAML comes the TOC (usually), title, attribution, and introduction.

{% include toc.html %}

# {{ page.title }}

_Written by Bob Nystrom<br>
October 2011
(updated March 2013)_

A summary, usually one or two paragraphs.

## Your first header

Breadcrumbs

To add breadcrumbs to page (for tools, articles, and anything else with a real tree structure and no better way of navigating it), include breadcrumbs.html, like this:

{% include toc.html %}
{% include breadcrumbs.html %}

# {{ page.title }}

You can provide a shortened title (short-title in the YAML) for use in breadcrumbs. For example, https://www.dartlang.org/tools/pub/ has way too long a name to appear in its subpages, so it defines a short-title like this:

---
layout: default
title: "Pub Package and Asset Manager"
short-title: "Pub"
---

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 Polymer and other 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:**
...