Added an introduction option by passing in a file with markdown.

pkg/docgen/lib/docgen.dart

Index: pkg/docgen/lib/docgen.dart
diff --git a/pkg/docgen/lib/docgen.dart b/pkg/docgen/lib/docgen.dart
index b67a321e5d309796d9614b00f60b8aa1d7c957dd..cd7656bef69482db0561c1f199f3c7bcb4b65f5c 100644
--- a/pkg/docgen/lib/docgen.dart
+++ b/pkg/docgen/lib/docgen.dart
@@ -79,7 +79,7 @@ bool _includePrivate = false;
  */
 Future<bool> docgen(List<String> files, {String packageRoot,
     bool outputToYaml: true, bool includePrivate: false, bool includeSdk: false,
-    bool parseSdk: false, bool append: false}) {
+    bool parseSdk: false, bool append: false, String introduction: ''}) {
   _includePrivate = includePrivate;
   if (!append) {
     var dir = new Directory('docs');
@@ -106,7 +106,8 @@ Future<bool> docgen(List<String> files, {String packageRoot,
         throw new StateError('No library mirrors were created.');
       }
       _documentLibraries(mirrorSystem.libraries.values,includeSdk: includeSdk,
-          outputToYaml: outputToYaml, append: append, parseSdk: parseSdk);
+          outputToYaml: outputToYaml, append: append, parseSdk: parseSdk, 
+          introduction: introduction);
 
       return true;
     });
@@ -222,7 +223,8 @@ Future<MirrorSystem> _analyzeLibraries(List<String> libraries,
  * Creates documentation for filtered libraries.
  */
 void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false,
-    bool outputToYaml: true, bool append: false, bool parseSdk: false}) {
+    bool outputToYaml: true, bool append: false, bool parseSdk: false, 
+    String introduction: ''}) {
   libs.forEach((lib) {
     // Files belonging to the SDK have a uri that begins with 'dart:'.
     if (includeSdk || !lib.uri.toString().startsWith('dart:')) {
@@ -242,11 +244,17 @@ void _documentLibraries(List<LibraryMirror> libs, {bool includeSdk: false,
   filteredEntities.where((e) => e is Class || e is Library).forEach((output) {
     _writeIndexableToFile(output, outputToYaml);
   });
+  var intro = introduction == '' ? 

[Emily Fortuna, 2013/08/15 18:39:35]

any reason why you define a new variable here instead of just assigning a new
value to introduction?

[janicejl, 2013/08/15 18:45:59]

Done. Moved it down to the map instead. 

+      '' : markdown.markdownToHtml(new File(introduction).readAsStringSync(),
+          linkResolver: linkResolver, inlineSyntaxes: markdownSyntaxes);
   // Outputs a yaml file with all libraries and their preview comments after 
   // creating all libraries. This will help the viewer know what libraries are 
   // available to read in.
-  var libraryMap = {'libraries' : filteredEntities.where((e) => 
-      e is Library).map((e) => e.previewMap).toList()};
+  var libraryMap = {
+    'libraries' : filteredEntities.where((e) => 
+        e is Library).map((e) => e.previewMap).toList(),
+    'introduction' : intro
+  };
   _writeToFile(getYamlString(libraryMap), 'library_list.yaml', append: append);
   // Outputs all the qualified names documented with their type.
   // This will help generate search results.