Markdown: recognize special note, promo, and aside blocks Extend the supported markdown syntax with a special aside format useful for documentation writing. *** note Pay special attention here! You may have to watch out for crazy developers. *** A note block starts with *** on its own line and ends with *** on its own line. Everything inside of the block is read as Markdown and reprocessed through a recursive call whose AST is inlined. Three kinds of notes are recognized, which are given different CSS: *** note Some sort of a warning you should watch out for. *** *** promo Look here this may interest you. *** *** aside The author felt you should read this here, but really it's just a distraction and maybe should be omitted or moved to another page buried under a link. *** Change-Id: Icbfd27d3afd7d0137e37b7d5e821938c70207cf1

diff --git a/gitiles-servlet/src/main/java/com/google/gitiles/doc/DivNode.java b/gitiles-servlet/src/main/java/com/google/gitiles/doc/DivNode.java
new file mode 100644
index 0000000..a84a041
--- /dev/null
+++ b/gitiles-servlet/src/main/java/com/google/gitiles/doc/DivNode.java

@@ -0,0 +1,42 @@
+// Copyright 2015 Google Inc. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.gitiles.doc;
+
+import org.pegdown.ast.Node;
+import org.pegdown.ast.ParaNode;
+import org.pegdown.ast.SuperNode;
+
+import java.util.List;
+
+/** Block note to render as {@code &lt;div class="{clazz}"&gt;}. */
+public class DivNode extends SuperNode {
+  private final String style;
+
+  DivNode(String style, List<Node> list) {
+    super(list.size() == 1 && list.get(0) instanceof ParaNode
+        ? ((ParaNode) list.get(0)).getChildren()
+        : list);
+    this.style = style;
+  }
+
+  public String getStyleName() {
+    return style;
+  }
+
+  @Override
+  public void accept(org.pegdown.ast.Visitor visitor) {
+    ((Visitor) visitor).visit(this);
+  }
+}

diff --git a/gitiles-servlet/src/main/java/com/google/gitiles/doc/GitilesMarkdown.java b/gitiles-servlet/src/main/java/com/google/gitiles/doc/GitilesMarkdown.java
index b79bf4d..43c589f 100644
--- a/gitiles-servlet/src/main/java/com/google/gitiles/doc/GitilesMarkdown.java
+++ b/gitiles-servlet/src/main/java/com/google/gitiles/doc/GitilesMarkdown.java

@@ -17,15 +17,19 @@
 import com.google.gitiles.GitilesView;
 
 import org.parboiled.Rule;
+import org.parboiled.support.StringBuilderVar;
 import org.pegdown.Parser;
 import org.pegdown.ParsingTimeoutException;
 import org.pegdown.PegDownProcessor;
+import org.pegdown.ast.Node;
 import org.pegdown.ast.RootNode;
 import org.pegdown.plugins.BlockPluginParser;
 import org.pegdown.plugins.PegDownPlugins;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+import java.util.List;
+
 /**
  * Additional markdown extensions known to Gitiles.
  * <p>
@@ -66,13 +70,18 @@
     return new PegDownProcessor(MD_OPTIONS, plugins);
   }
 
+  private PegDownProcessor parser;
+
   GitilesMarkdown() {
     super(MD_OPTIONS, 2000L, DefaultParseRunnerProvider);
   }
 
   @Override
   public Rule[] blockPluginRules() {
-    return new Rule[]{ toc() };
+    return new Rule[]{
+        note(),
+        toc(),
+    };
   }
 
   public Rule toc() {
@@ -80,4 +89,32 @@
         string("[TOC]"),
         push(new TocNode()));
   }
+
+  public Rule note() {
+    StringBuilderVar body = new StringBuilderVar();
+    return NodeSequence(
+        string("***"), Sp(), typeOfNote(), Newline(),
+        oneOrMore(
+          testNot(string("***"), Newline()),
+          Line(body)),
+        string("***"), Newline(),
+        push(new DivNode(popAsString(), parse(body))));
+  }
+
+  public Rule typeOfNote() {
+    return firstOf(
+        sequence(string("note"), push(match())),
+        sequence(string("promo"), push(match())),
+        sequence(string("aside"), push(match())));
+  }
+
+  public List<Node> parse(StringBuilderVar body) {
+    // The pegdown code doesn't provide enough visibility to directly
+    // use its existing parsing rules. Recurse manually for inner text
+    // parsing within a block.
+    if (parser == null) {
+      parser = newParser();
+    }
+    return parser.parseMarkdown(body.getChars()).getChildren();
+  }
 }

diff --git a/gitiles-servlet/src/main/java/com/google/gitiles/doc/MarkdownToHtml.java b/gitiles-servlet/src/main/java/com/google/gitiles/doc/MarkdownToHtml.java
index a3feb6c..1086bab 100644
--- a/gitiles-servlet/src/main/java/com/google/gitiles/doc/MarkdownToHtml.java
+++ b/gitiles-servlet/src/main/java/com/google/gitiles/doc/MarkdownToHtml.java

@@ -100,6 +100,13 @@
   }
 
   @Override
+  public void visit(DivNode node) {
+    html.open("div").attribute("class", node.getStyleName());
+    visitChildren(node);
+    html.close("div");
+  }
+
+  @Override
   public void visit(HeaderNode node) {
     String tag = "h" + node.getLevel();
     html.open(tag);

diff --git a/gitiles-servlet/src/main/java/com/google/gitiles/doc/Visitor.java b/gitiles-servlet/src/main/java/com/google/gitiles/doc/Visitor.java
index b8cf64e..19a68cc 100644
--- a/gitiles-servlet/src/main/java/com/google/gitiles/doc/Visitor.java
+++ b/gitiles-servlet/src/main/java/com/google/gitiles/doc/Visitor.java

@@ -15,5 +15,6 @@
 package com.google.gitiles.doc;
 
 public interface Visitor extends org.pegdown.ast.Visitor {
+  void visit(DivNode node);
   void visit(TocNode node);
 }

diff --git a/gitiles-servlet/src/main/resources/com/google/gitiles/static/doc.css b/gitiles-servlet/src/main/resources/com/google/gitiles/static/doc.css
index e047f59..c324786 100644
--- a/gitiles-servlet/src/main/resources/com/google/gitiles/static/doc.css
+++ b/gitiles-servlet/src/main/resources/com/google/gitiles/static/doc.css

@@ -164,4 +164,33 @@
 }
 th {
   background-color: #f5f5f5;
-}
\ No newline at end of file
+}
+
+.note, .promo, .aside {
+  border: 1px solid;
+  border-radius: 4px;
+  margin: 10px 0;
+  padding: 10px;
+}
+.note {
+  background: #fffbe4;
+  border-color: #f8f6e6;
+}
+.promo {
+  background: #f6f9ff;
+  border-color: #eff2f9;
+}
+.aside {
+  background: #f9f9f9;
+  border-color: #f2f2f2;
+}
+.note p:first-child,
+.promo p:first-child,
+.aside p:first-child {
+  margin-top: 0;
+}
+.note p:last-child,
+.promo p:last-child,
+.aside p:last-child {
+  margin-bottom: 0;
+}