Skip to content
This repository has been archived by the owner on Feb 22, 2018. It is now read-only.

Formatting Tips

Jump to bottom
Kathy Walrath edited this page Aug 18, 2014 · 16 revisions

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
    • Tweaking titles
  • 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 a 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 }}

Tweaking titles

By default, the YAML title is used for the page title, the tab/history title, and breadcrumbs, if any. You can customize this behavior using the subsite and short-title tags.

The subsite tag adds text to the tab/history title. For example, pages in the Polymer.dart subsite, such as the release note page have subsite set to "Polymer.dart". This lets the page title be short ("Release Notes") while giving the tab/history title some context; instead of saying "Release Notes | Dart: Structured web apps" the tab/history says "Release Notes | Polymer.dart | Dart: Structured web apps".

---
layout: default
title: "Release Notes"
subsite: "Polymer.dart"
...
---

{% include breadcrumbs.html %}

The short-title tag lets you shorten the page's title in the breadcrumbs. An example is the Pub homepage:

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

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

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:**
...
Clone this wiki locally