Markdown: recognize special multi-column layout blocks
Documentation writers may want to organize clusters of information
and/or links into a multi-column based layout to help readers find
material quickly.
Extend the supported markdown syntax with a new multi-column region.
A multi-column region is delineated by |||---||| with other markdown
contained within it:
|||---|||
## Markdown is easy
You can write simple text.
* [Basic markdown](http://...)
* [GitHub flavor](http://github.com/...)
* [This kind](kind.md)
## Safe
No HTML found.
## Fast
Well, faster than you can get coffee.
|||---|||
Headers within the region define the columns. For each header a new
column is started and the following content is placed below it into
the same column.
The above will render as three divs next to each other:
Markdown is easy Safe Fast
You can write simple No HTML found. Well, faster than
text. you can get coffee.
* Basic markdown
* GitHub flavor
* This kind
At present up to 4 columns may be fit across a page of documentation.
Additional columns should be placed into a new |||---||| block and
will appear below these columns.
The column widths are not configurable.
Change-Id: I088115bf4d4569817aca736cb0ce02f9d777d61b
diff --git a/gitiles-servlet/src/main/java/com/google/gitiles/doc/ColsNode.java b/gitiles-servlet/src/main/java/com/google/gitiles/doc/ColsNode.java
new file mode 100644
index 0000000..00945ef
--- /dev/null
+++ b/gitiles-servlet/src/main/java/com/google/gitiles/doc/ColsNode.java
@@ -0,0 +1,36 @@
+// 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.SuperNode;
+
+import java.util.List;
+
+/**
+ * Multi-column layout delineated by {@code |||---|||}.
+ * <p>
+ * Each header within the layout creates a new column in the HTML.
+ */
+public class ColsNode extends SuperNode {
+ ColsNode(List<Node> children) {
+ super(children);
+ }
+
+ @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 43c589f..512d320 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
@@ -30,12 +30,7 @@
import java.util.List;
-/**
- * Additional markdown extensions known to Gitiles.
- * <p>
- * {@code [TOC]} as a stand-alone block will insert a table of contents
- * for the current document.
- */
+/** Parses Gitiles extensions to markdown. */
class GitilesMarkdown extends Parser implements BlockPluginParser {
private static final Logger log = LoggerFactory.getLogger(MarkdownHelper.class);
@@ -78,7 +73,8 @@
@Override
public Rule[] blockPluginRules() {
- return new Rule[]{
+ return new Rule[] {
+ cols(),
note(),
toc(),
};
@@ -108,6 +104,21 @@
sequence(string("aside"), push(match())));
}
+ public Rule cols() {
+ StringBuilderVar body = new StringBuilderVar();
+ return NodeSequence(
+ colsTag(), Newline(),
+ oneOrMore(
+ testNot(colsTag(), Newline()),
+ Line(body)),
+ colsTag(), Newline(),
+ push(new ColsNode(parse(body))));
+ }
+
+ public Rule colsTag() {
+ return string("|||---|||");
+ }
+
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
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 1086bab..a11c0e2 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
@@ -107,6 +107,26 @@
}
@Override
+ public void visit(ColsNode node) {
+ html.open("div").attribute("class", "cols");
+ boolean open = false;
+ for (Node n : node.getChildren()) {
+ if (n instanceof HeaderNode || n instanceof DivNode) {
+ if (open) {
+ html.close("div");
+ }
+ html.open("div").attribute("class", "col-3");
+ open = true;
+ }
+ n.accept(this);
+ }
+ if (open) {
+ html.close("div");
+ }
+ 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 19a68cc..8e9ea60 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,6 +15,7 @@
package com.google.gitiles.doc;
public interface Visitor extends org.pegdown.ast.Visitor {
+ void visit(ColsNode node);
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 c324786..198f8f6 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
@@ -45,7 +45,7 @@
.nav li a:hover {
color: #0000f9;
}
-.nav ul:after {
+.nav ul:after, .cols:after {
clear: both;
content: "";
display: block;
@@ -184,9 +184,9 @@
background: #f9f9f9;
border-color: #f2f2f2;
}
-.note p:first-child,
-.promo p:first-child,
-.aside p:first-child {
+.note :first-child,
+.promo :first-child,
+.aside :first-child {
margin-top: 0;
}
.note p:last-child,
@@ -194,3 +194,16 @@
.aside p:last-child {
margin-bottom: 0;
}
+
+.cols {
+ margin: 0 -1.533%;
+ width: 103.067%;
+}
+.col-3 {
+ float: left;
+ margin: 0 1.488% 20px;
+}
+.col-3 { width: 22.023%; }
+.cols hr {
+ width: 80%;
+}
