Writing for flutter.io

(Eventually, this section should be expanded to its own page.)

Adding next/previous page links

If you have a document that spans multiple pages, you can add next and previous
page links to make navigating these pages easier. It involves adding some information
to the front matter of each page, and including some HTML.

See the list of supported languages above for what to use
following the first triple backticks.

Adding more languages for syntax highlighting

The flutter.io website uses a custom build of prism, which
includes only the languages the website requires. To improve
load times and user experience, we do not support every
language that prism supports.

To add a new language for syntax highlighting, you will need
to generate a new copy of the prism.js file.

Follow these steps to generate a new copy of prism.js:

Open js/prism.js

Copy the URL in the comment of the first line of the file

Paste it into a browser window/tab

Add the new language that you wish to syntax highlight

DO NOT change the other plugins, languages, or settings

Download the generated JavaScript, and use it to replace js/prism.js

Download the generated CSS, and use it to replace _sass/_prism.scss

Advanced stylization of code blocks

Do you want to highlight (make the background yellow)
code inside a code block? Do you want to strike-through
code inside a code block? We got that!

If you want to see how this functionality was added to this site, refer to
this commit.

Including a region of a file

You can include a specific range of lines from a file:

{%include includelines filename=PATH start=INT count=INT%}

PATH must be inside of _include. If you are including source code,
place that code into _include/code to follow our convention.

Code snippet validation

The code snippets in the markdown documentation are validated as part of the
build process. Anything within a '```dart' code fence will be extracted into
its own file and checked for analysis issues. Some ways to tweak that:

If a code snippet should not be analyzed, immediately proceed it with
a <!-- skip --> comment

To include code to be analyzed, but not displayed, add that in a comment
immediately proceeding the snippet (e.g., <!-- someCodeHere(); -->)

A snippet without any import statements will have an import
('package:flutter/material.dart')
automatically added to it

We ignore special formatting tags like [[highlight]].

Updating the Sample Catalog

The sample catalog's markdown files are generated by running sample_page.dart from the Flutter github repo. Starting from the root of the Flutter repo:

The generated markdown files will contain cloud storage links for sample app screenshots. Screenshots for each sample app are automatically generated for each Flutter repo commit. Choose a recent commit hashcode and confirm that the screenshots look OK.

If new sample apps have been added, update _data/catalog/widget.json. The entry for each widget class that's featured in a sample app should contain "sample" line like:

"sample": "ListView_index",

The sample_page.dart app will print a list of all of the "sample" properties that should appear in the widget.json file.

Preventing broken links

Some form of broken links prevention is done automatically by rake checklinks
on every commit (through tool/travis.sh). But this won't see any Firebase
redirects (rake checklinks doesn't run the Firebase server) and it won't
check incoming links.