Writing for dartlang.org

Writing for dartlang.org

(This page isn't done yet, but it's probably more useful than having nothing at all.)

The Dart site at www.dartlang.org (and in particular, www.dartlang.org/articles/) is open to contributions. The site uses Markdown (or HTML, if necessary) with some special additions. It’s great if you can contribute using git, chromiumcodereview, and our site format, but we can be flexible.

Note: We also love contributions to the API docs (api.dartlang.org), which are generated from source code and doc comments. For details, see Guidelines for Dart Doc Comments and, if you’re contributing to DOM-related docs such as dart:html, ContributingHTMLDocumentation.

Contents

• Before you write
  • Decide what you’d like/need to write about
  • Get into the spreadsheet
• Write the article
  • Initial draft and reviews
  • Conventions
  • Choosing a path
• Write code samples
• Write an author page
• Format the article
  • Top matter
    • YAML setup code
      • Choosing a collection
    • Title, author, date
  • Notes and warnings
  • Code (prettify)
  • Advanced {% … %}
    • comment
    • include
    • raw
    • capture
    • Custom stuff
  • Tips and workarounds
    • Markdown inside of HTML inside of markdown

Yet to add: Content on creating a CL, getting it reviewed, and getting the article published and advertised.

Before you write

Decide what you’d like/need to write about

Get into the spreadsheet

Talk to Kathy or to someone else in DevRel (Seth, Shailen, JJ, John) so that you get into the Dart doc tasks spreadsheet.

Write the article

Initial draft and reviews

Some authors like to create the article in a Google Drive document, moving to Markdown once the majority of comments have been dealt with.

Follow conventions

We prefer a 1 or 2-paragraph intro, followed by a TOC, followed by content. [Point to example]

Keep code copyable. Avoid giving bad examples, whenever possible. If you need to give bad examples, make it impossible to mistake them for good ones. (See the Dart Style Guide for a nice scheme.)

Choose a path

Each article (or group of articles on a single subject) goes into its own subdirectory of src/site/articles. For SEO reasons, try to put good buzzwords in the path, and separate words with dashes (-), not underscores.

Some examples:

• doc-comment-guidelines
• idiomatic-dart
• improving-the-dom
• m1-language-changes
• reflection-with-mirrors
• snapshots
• style-guide

To get the top matter and styles right, copy a file such as src/site/snapshots/index.markdown.

Write code samples

Create a code/ directory inside your article’s directory, and put .dart files there that contain the code from your article. We’ll continuously run dart_analyzer (at least) on the articles’ code, so we’ll know as soon as the code breaks.

Write an author page

If you don’t yet have an author page, create one and add a link to it from /authors/index.html. Author pages can help Google provide pretty search results for your articles.

Here's how to create your author page:

1. Go to src/site/authors.
2. Copy seth-ladd.html to your-name.html.
3. Modify the info, removing the twitter and me: links if you don’t have (or don’t want to expose your) twitter or external G+ accounts.
4. Edit index.html to add your name (alphabetically by first name).

Format the 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

Title, author, date

# {{ page.title }}
<em>Written by Kathy Walrath<br />
<time pubdate date="2012-11-21">November 2012</time>
</em>

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 %}// First line of code...
// ...
// Last line of code.
{% 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 %}

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