Flutter's website

Flutter's static website, built with Jekyll.

Issues, bugs, and requests

We welcome contributions and feedback on our website! Please file a request in our issue tracker and we'll take a look.

Developing

Install Jekyll and related tools by following the instructions provided by GitHub.

A tldr version follows:

Ensure you have Ruby installed; you need version 2.2.2 or later:
ruby --version
Ensure you have Bundler installed; if not install with:
sudo gem install bundler
Install all dependencies:
bundle install
Create a branch.
Make your changes.
Test your changes by serving the site locally:
bundle exec jekyll serve (or jekyll serve -w --force_polling)
Prior to submitting, run link validation:
bundle exec jekyll build
bundle exec htmlproofer _site --empty-alt-ignore --url-ignore "#" --only-4xx --url-swap "https?\:\/\/(localhost\:4000|flutter\.io):"

Staging the site for external review

If you haven't done so, create a new project on firebase.corp.google.com. It's best to use a name that identifies who you are. I use "sz-flutter".
At the root of the website repo, add a .firebaserc file with the name of your firebase project. The .firebaserc file is listed in the .gitignore file, so it won't create a file in master. Here's what my rc file looks like:

$ cat .firebaserc
{
  "projects": {
    "sz" : "sz-flutter"
  }
}

From the root of the website repo, build the site:

$ jekyll build

Deploy the site to your personal instance:

$ firebase deploy --project sz

Navigate the browser to the hosted URL. In my case, that's https://sz-flutter.firebaseapp.com.
When submitting a PR for review, include a link to the relevant pages in your firebase instance to make it easier for reviewers.

Writing for flutter.io

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

Highlighting code in a code block

Do you want to highlight code inside a code block? We got that! Don't confuse this with automatic syntax highlighting. You can accomplish that by adding "dart" (or the relevant language identifier) after the tick-tick-tick:

```dart
void main() {
  print('Hello World');
}
```

If you want to highlight a specific bit of code, use the [[highlight]]highlight this text[[/highlight]] syntax. For example:

{% prettify dart %} void main() { print([[highlight]]'Hello World'[[/highlight]]); } {% endprettify %}

The prettify plugin will also unindent your code.

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.

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.

---
layout: tutorial
title: "Constraints"
sidebar: home_sidebar
permalink: /tutorials/layout/constraints.html
prev-page: /tutorials/layout/properties.html
prev-page-title: "Container Properties"
next-page: /tutorials/layout/create.html
next-page-title: "Create a Layout"
---

{% include prev-next-nav.html %}

{:toc}

<!-- PAGE CONTENT -->

{% include prev-next-nav.html %}

Omit the "prev-page" info for the first page, and the "next-page" info for the last page.

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  comment
To include code to be analyzed, but not displayed, add that in a comment immediately proceeding the snippet (e.g., )
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]].

lukechurch/website