config

@@ -1,6 +1,6 @@
 # vim:ft=sh:
 ngx_addon_name=ngx_http_awesomeindex_module
-ngx_module_libs="-lmd4c-html"
+ngx_module_libs="-lmarkdown"
 
 if [ "$ngx_module_link" = DYNAMIC ] ; then
     ngx_module_type=HTTP

ngx_http_awesomeindex_module.c

@@ -22,10 +22,10 @@
 #include <ngx_core.h>
 #include <ngx_http.h>
 #include <ngx_log.h>
-#include "ngx_buf.h"
 #include "ngx_string.h"
 
-#include "md4c-html.h"
+#include <mkdio.h>
+
 #include "template.h"
 
 #if defined(__GNUC__) && (__GNUC__ >= 3)
@@ -328,85 +328,7 @@ ngx_awesomeindex_conf_set_headerfooter(ngx_conf_t *cf, ngx_command_t *cmd, void
 #define ngx_has_flag(_where, _what) \
 	(((_where) & (_what)) == (_what))
 
-/*********************************
- ***  Simple grow-able buffer  ***
- *********************************/
 
-/* We render to a memory buffer instead of directly outputting the rendered
- * documents, as this allows using this utility for evaluating performance
- * of MD4C (--stat option). This allows us to measure just time of the parser,
- * without the I/O.
- */
-
-struct membuffer {
-    char* data;
-    size_t asize;
-    size_t size;
-    u_char fail;
-};
-
-static u_char
-membuf_init(struct membuffer* buf, MD_SIZE new_asize)
-{
-    buf->size = 0;
-    buf->asize = new_asize;
-    buf->data = malloc(buf->asize);
-    if(buf->data == NULL) {
-        buf->fail = 1;
-        return 1;
-    }
-    buf->fail = 0;
-    return 0;
-}
-
-static void
-membuf_free(struct membuffer* buf)
-{
-    if(buf && buf->data) free(buf->data);
-}
-
-static void
-membuf_grow(struct membuffer* buf, size_t new_asize)
-{
-    buf->data = realloc(buf->data, new_asize);
-    if(buf->data == NULL) {
-        buf->fail = 1;
-    }
-    buf->asize = new_asize;
-}
-
-static void
-membuf_append(struct membuffer* buf, const char* data, MD_SIZE size)
-{
-    if(buf->asize < buf->size + size)
-        membuf_grow(buf, buf->size + buf->size / 2 + size);
-    memcpy(buf->data + buf->size, data, size);
-    buf->size += size;
-}
-
-static void
-process_md_output(const MD_CHAR* text, MD_SIZE size, void* userdata)
-{
-    struct membuffer *buf = (struct membuffer*) userdata;
-    if (!buf->fail) membuf_append(buf, text, size);
-}
-
-static ssize_t ngx_awesomeindex_read_file(ngx_http_request_t *r, u_char* filename, size_t file_len, u_char* dest)
-{
-    ngx_file_t file;
-    ngx_memzero(&file, sizeof(ngx_file_t));
-    file.fd = ngx_open_file(filename, NGX_FILE_RDONLY, NGX_FILE_OPEN, 0);
-    if (file.fd == NGX_INVALID_FILE) {
-        ngx_log_error(NGX_LOG_ALERT, r->connection->log, ngx_errno,
-            "cannot open readme file \"%V\"", filename);
-        return NGX_ERROR;
-    }
-    file.log = r->connection->log;
-
-    ssize_t n = ngx_read_file(&file, dest, file_len, 0);
-    ngx_close_file(file.fd);
-    return n;
-}
 
 
 typedef struct {
@@ -637,21 +559,11 @@ static const ngx_str_t img_icon_pre =
     ngx_string("<img src=\"");
 static const ngx_str_t img_icon_post =
     ngx_string("\" alt=\"\" height=\"32\" width=\"32\">");
-static const ngx_str_t footer_md_pre =
-    ngx_string("<footer class=\"markup\">");
-static const ngx_str_t codeblock_pre =
-    ngx_string("<pre>");
-static const ngx_str_t codeblock_post =
-    ngx_string("</pre>");
 static const ngx_str_t footer_pre =
-    ngx_string("<footer>");
+    ngx_string("<footer class=\"markup\">");
 static const ngx_str_t footer_post =
     ngx_string("</footer>");
 
-#define README_TXT 0
-#define README_HTML 1
-#define README_MD 2
-
 
 #ifdef NGX_ESCAPE_URI_COMPONENT
 static inline uintptr_t
@@ -828,7 +740,7 @@ make_content_buf(
     ngx_dir_t    dir;
     ngx_buf_t   *b;
     u_char *readme_path = NULL;
-    u_char readme_type = README_TXT;
+    u_char readme_md = 0;
     off_t readme_file_len = 0;
 
     static const char    *sizes[]  = { "EiB", "PiB", "TiB", "GiB", "MiB", "KiB", "B" };
@@ -1013,11 +925,7 @@ make_content_buf(
                 ngx_cpystrn(readme_path, filename, allocated);
 
                 readme_file_len = entry->size;
-                readme_type = README_TXT;
+                readme_md = entry->name.len > 6 && ngx_strncasecmp(entry->name.data + 6, (u_char*) ".md", 3) == 0;
-                if (entry->name.len > 6) {
-                    if (ngx_strncasecmp(entry->name.data + 6, (u_char*) ".md", 3) == 0) readme_type = README_MD;
-                    else if (ngx_strncasecmp(entry->name.data + 6, (u_char*) ".html", 3) == 0) readme_type = README_HTML;
-                }
             }
         }
 
@@ -1033,7 +941,7 @@ make_content_buf(
 
     if (readme_path) {
         ngx_log_debug3(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
-                "http awesomeindex README: %s, type: %d, len: %d", readme_path, readme_type, readme_file_len);
+                "HTTP awesomeindex README: %s, MD%d, len: %d", readme_path, readme_md, readme_file_len);
     }
 
     /*
@@ -1111,47 +1019,21 @@ make_content_buf(
         if (entry[i].link) len += ngx_sizeof_ssz("-shortcut");
     }
 
-    struct membuffer readme_md_content = {0};
+    char *readme_md_content;
     if (readme_file_len) {
-        if (readme_type == README_MD) {
+        if (readme_md) {
-            ngx_buf_t *buf_in = ngx_create_temp_buf(r->pool, readme_file_len);
+            FILE *md_file = fopen((char *)readme_path, "r");
-            ssize_t rbts = ngx_awesomeindex_read_file(r, readme_path, readme_file_len, buf_in->last);
+            MMIOT *mkd = mkd_in(md_file, MKD_FLAGS);
-
+            mkd_compile(mkd, MKD_FLAGS);
-            if (rbts != NGX_ERROR) {
+            readme_file_len = mkd_document(mkd, &readme_md_content);
-                buf_in->last += rbts;
+            fclose(md_file);
-                ngx_log_debug(NGX_LOG_DEBUG_HTTP, r->connection->log, ngx_errno, "http awesomeindex: read %d bytes from %s", rbts, readme_path);
+            ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0, "converted %s, len=%d", readme_path, readme_file_len);
-
-                // Allocating buffer for parsing readme
-                if (!membuf_init(&readme_md_content, readme_file_len + readme_file_len/5)) {
-                    ngx_log_debug(NGX_LOG_DEBUG_HTTP, r->connection->log, ngx_errno, "MEMBUF INITTED");
-                    int ret = md_html((MD_CHAR*) buf_in->start, readme_file_len, process_md_output,
-                            &readme_md_content, MD_FLAG_PERMISSIVEURLAUTOLINKS | MD_FLAG_TABLES, 0);
-                    if (ret) {
-                        ngx_log_error(NGX_LOG_ALERT, r->connection->log, ngx_errno, "error parsing markdown %s", readme_path);
-                    } else if (readme_md_content.fail) {
-                        ngx_log_error(NGX_LOG_ALERT, r->connection->log, ngx_errno, "could not allocate memory for parsing readme");
-                    } else {
-                        ngx_log_debug(NGX_LOG_DEBUG_HTTP, r->connection->log, 0, "parsed markdown len=%d", readme_md_content.size);
-                        len += footer_md_pre.len + readme_md_content.size + footer_post.len;
-                    }
-                } else {
-                    ngx_log_error(NGX_LOG_ALERT, r->connection->log, ngx_errno, "could not allocate memory for parsing readme");
-                }
-            } else {
-                readme_md_content.fail = 1;
-                ngx_log_error(NGX_LOG_ALERT, r->connection->log, ngx_errno, "cannot read file \"%V\"", readme_path);
-            }
-        } else if (readme_type == README_TXT) {
-            len += footer_pre.len + codeblock_pre.len + readme_file_len + codeblock_post.len + footer_post.len;
-        } else {
-            len += footer_pre.len + readme_file_len + footer_post.len;
         }
+        len += footer_pre.len + readme_file_len + footer_post.len;
     }
 
-    if ((b = ngx_create_temp_buf(r->pool, len)) == NULL) {
+    if ((b = ngx_create_temp_buf(r->pool, len)) == NULL)
-        membuf_free(&readme_md_content);
         return NGX_HTTP_INTERNAL_SERVER_ERROR;
-    }
 
     /*
      * Determine the sorting criteria. URL arguments look like:
@@ -1417,26 +1299,40 @@ make_content_buf(
 
     // Readme file
     if (readme_file_len) {
-        if (readme_type == README_MD) {
+        b->last = ngx_cpymem_str(b->last, footer_pre);
-            if (!readme_md_content.fail) {
+
-                b->last = ngx_cpymem_str(b->last, footer_md_pre);
+        if (readme_md) {
-                b->last = ngx_cpymem(b->last, readme_md_content.data, readme_md_content.size);
+            b->last = ngx_cpymem(b->last, readme_md_content, readme_file_len);
-                b->last = ngx_cpymem_str(b->last, footer_post);
-            }
-            membuf_free(&readme_md_content);
         } else {
-            b->last = ngx_cpymem_str(b->last, footer_pre);
+            ngx_file_t file;
-            if (readme_type == README_TXT) b->last = ngx_cpymem_str(b->last, codeblock_pre);
+            ngx_memzero(&file, sizeof(ngx_file_t));
-
+            file.fd = ngx_open_file(readme_path, NGX_FILE_RDONLY, NGX_FILE_OPEN, 0);
-            ssize_t rbts = ngx_awesomeindex_read_file(r, readme_path, readme_file_len, b->last);
+            if (file.fd == NGX_INVALID_FILE) {
-            if (rbts != NGX_ERROR) b->last += rbts;
+                ngx_log_error(NGX_LOG_ALERT, r->connection->log, ngx_errno,
-            else {
+                    "cannot open readme file \"%V\"", readme_path);
-                ngx_log_error(NGX_LOG_ALERT, r->connection->log, ngx_errno, "cannot read file \"%V\"", readme_path);
+                return NGX_ERROR;
             }
+            file.log = r->connection->log;
+            ngx_log_debug(NGX_LOG_DEBUG_HTTP, r->connection->log, 0, "opened file %d", file);
 
-            if (readme_type == README_TXT) b->last = ngx_cpymem_str(b->last, codeblock_post);
+            ssize_t n = readme_file_len;
-            b->last = ngx_cpymem_str(b->last, footer_post);
+            while (n > 0) {
+                ssize_t rbts = ngx_read_file(&file,
+                                        b->last + file.offset,
+                                        n,
+                                        file.offset);
+                if (rbts == NGX_ERROR) {
+                    ngx_close_file(file.fd);
+                    ngx_log_error(NGX_LOG_ALERT, r->connection->log, ngx_errno,
+                        "cannot read readme file \"%V\"", readme_path);
+                    return NGX_ERROR;
+                }
+                b->last += rbts;
+                n -= rbts;
+            }
         }
+
+        b->last = ngx_cpymem_str(b->last, footer_post);
     }
 
     *pb = b;

t/README.md

@@ -1,5 +1,22 @@
 # Markdown: Syntax
 
+*   [Overview](#Overview)
+    *   [Philosophy](#Philosophy)
+*   [Block Elements](#Block-Elements)
+    *   [Paragraphs and Line Breaks](#Paragraphs-and-Line-Breaks)
+    *   [Headers](#Headers)
+    *   [Blockquotes](#Blockquotes)
+    *   [Lists](#Lists)
+    *   [Code Blocks](#Code-Blocks)
+    *   [Horizontal Rules](#Horizontal-Rules)
+*   [Span Elements](#Span-Elements)
+    *   [Links](#Links)
+    *   [Emphasis](#Emphasis)
+    *   [Code](#Code)
+    *   [Table](#Table)
+
+----
+
 ## Overview
 
 ### Philosophy

t/child-directory/README.txt

@@ -1,7 +0,0 @@
-Folder with several child directories
-
-├── c2
-│   └── c3
-│       └── empty-file.txt
-├── empty-file.txt
-└── README.txt

t/show_dotfiles/README.html

@@ -1,3 +0,0 @@
-<h1>Hello World</h1>
-
-Hello World, this is me ;-)

template.h

@@ -128,11 +128,11 @@ static const u_char t01_head1[] = ""
 "}"
 "footer {"
 "  padding: 40px 20px;"
-"  font-size: 16px;"
 "}"
 ".markup {"
 "  max-width: 790px;"
 "  word-wrap: break-word;"
+"  font-size: 16px;"
 "  overflow: hidden;"
 "  line-height: 1.5 !important;"
 "}"
@@ -385,6 +385,9 @@ static const u_char t01_head1[] = ""
 "        .meta {"
 "          border-bottom: 1px solid #212121;"
 "        }"
+"        footer code, footer pre {"
+"          background-color: rgb(8, 36, 55);"
+"        }"
 "      }"
 "    </style>"
 ;

template.html

@@ -127,11 +127,11 @@ main {
 }
 footer {
   padding: 40px 20px;
-  font-size: 16px;
 }
 .markup {
   max-width: 790px;
   word-wrap: break-word;
+  font-size: 16px;
   overflow: hidden;
   line-height: 1.5 !important;
 }
@@ -384,6 +384,9 @@ footer {
         .meta {
           border-bottom: 1px solid #212121;
         }
+        footer code, footer pre {
+          background-color: rgb(8, 36, 55);
+        }
       }
     </style>
 <!-- var NONE -->
@@ -606,287 +609,431 @@ Index of /path/to/somewhere
     </main>
 
 <!-- var NONE -->
-<footer class="markup"><h1>Markdown: Syntax</h1>
+<h1><a href="https://google.github.io/styleguide/">styleguide</a></h1>
-  <h2>Overview</h2>
-  <h3>Philosophy</h3>
-  <p>Markdown is intended to be as easy-to-read and easy-to-write as is feasible.</p>
-  <p>Readability, however, is emphasized above all else. A Markdown-formatted
-  document should be publishable as-is, as plain text, without looking
-  like it's been marked up with tags or formatting instructions. While
-  Markdown's syntax has been influenced by several existing text-to-HTML
-  filters -- including <a href="http://docutils.sourceforge.net/mirror/setext.html">Setext</a>, <a href="http://www.aaronsw.com/2002/atx/">atx</a>, <a href="http://textism.com/tools/textile/">Textile</a>, <a href="http://docutils.sourceforge.net/rst.html">reStructuredText</a>,
-  <a href="http://www.triptico.com/software/grutatxt.html">Grutatext</a>, and <a href="http://ettext.taint.org/doc/">EtText</a> -- the single biggest source of
-  inspiration for Markdown's syntax is the format of plain text email.</p>
-  <h2>Block Elements</h2>
-  <h3>Paragraphs and Line Breaks</h3>
-  <p>A paragraph is simply one or more consecutive lines of text, separated
-  by one or more blank lines. (A blank line is any line that looks like a
-  blank line -- a line containing nothing but spaces or tabs is considered
-  blank.) Normal paragraphs should not be indented with spaces or tabs.</p>
-  <p>The implication of the &quot;one or more consecutive lines of text&quot; rule is
-  that Markdown supports &quot;hard-wrapped&quot; text paragraphs. This differs
-  significantly from most other text-to-HTML formatters (including Movable
-  Type's &quot;Convert Line Breaks&quot; option) which translate every line break
-  character in a paragraph into a <code>&lt;br /&gt;</code> tag.</p>
-  <p>When you <em>do</em> want to insert a <code>&lt;br /&gt;</code> break tag using Markdown, you
-  end a line with two or more spaces, then type return.</p>
-  <h3>Headers</h3>
-  <p>Markdown supports two styles of headers, [Setext] [1] and [atx] [2].</p>
-  <p>Optionally, you may &quot;close&quot; atx-style headers. This is purely
-  cosmetic -- you can use this if you think it looks better. The
-  closing hashes don't even need to match the number of hashes
-  used to open the header. (The number of opening hashes
-  determines the header level.)</p>
-  <h3>Blockquotes</h3>
-  <p>Markdown uses email-style <code>&gt;</code> characters for blockquoting. If you're
-  familiar with quoting passages of text in an email message, then you
-  know how to create a blockquote in Markdown. It looks best if you hard
-  wrap the text and put a <code>&gt;</code> before every line:</p>
-  <blockquote>
-  <p>This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
-  consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
-  Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.</p>
-  <p>Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
-  id sem consectetuer libero luctus adipiscing.</p>
-  </blockquote>
-  <p>Markdown allows you to be lazy and only put the <code>&gt;</code> before the first
-  line of a hard-wrapped paragraph:</p>
-  <blockquote>
-  <p>This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
-  consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
-  Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.</p>
-  </blockquote>
-  <blockquote>
-  <p>Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
-  id sem consectetuer libero luctus adipiscing.</p>
-  </blockquote>
-  <p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
-  adding additional levels of <code>&gt;</code>:</p>
-  <blockquote>
-  <p>This is the first level of quoting.</p>
-  <blockquote>
-  <p>This is nested blockquote.</p>
-  </blockquote>
-  <p>Back to the first level.</p>
-  </blockquote>
-  <p>Blockquotes can contain other Markdown elements, including headers, lists,
-  and code blocks:</p>
-  <blockquote>
-  <h2>This is a header.</h2>
-  <ol>
-  <li>This is the first list item.</li>
-  <li>This is the second list item.</li>
-  </ol>
-  <p>Here's some example code:</p>
-  <pre><code>return shell_exec(&quot;echo $input | $markdown_script&quot;);
-  </code></pre>
-  </blockquote>
-  <p>Any decent text editor should make email-style quoting easy. For
-  example, with BBEdit, you can make a selection and choose Increase
-  Quote Level from the Text menu.</p>
-  <h3>Lists</h3>
-  <p>Markdown supports ordered (numbered) and unordered (bulleted) lists.</p>
-  <p>Unordered lists use asterisks, pluses, and hyphens -- interchangably
-  -- as list markers:</p>
-  <ul>
-  <li>Red</li>
-  <li>Green</li>
-  <li>Blue</li>
-  </ul>
-  <p>is equivalent to:</p>
-  <ul>
-  <li>Red</li>
-  <li>Green</li>
-  <li>Blue</li>
-  </ul>
-  <p>and:</p>
-  <ul>
-  <li>Red</li>
-  <li>Green</li>
-  <li>Blue</li>
-  </ul>
-  <p>Ordered lists use numbers followed by periods:</p>
-  <ol>
-  <li>Bird</li>
-  <li>McHale</li>
-  <li>Parish</li>
-  </ol>
-  <p>It's important to note that the actual numbers you use to mark the
-  list have no effect on the HTML output Markdown produces. The HTML
-  Markdown produces from the above list is:</p>
-  <p>If you instead wrote the list in Markdown like this:</p>
-  <ol>
-  <li>Bird</li>
-  <li>McHale</li>
-  <li>Parish</li>
-  </ol>
-  <p>or even:</p>
-  <ol start="3">
-  <li>Bird</li>
-  <li>McHale</li>
-  <li>Parish</li>
-  </ol>
-  <p>you'd get the exact same HTML output. The point is, if you want to,
-  you can use ordinal numbers in your ordered Markdown lists, so that
-  the numbers in your source match the numbers in your published HTML.
-  But if you want to be lazy, you don't have to.</p>
-  <p>To make lists look nice, you can wrap items with hanging indents:</p>
-  <ul>
-  <li>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
-  Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
-  viverra nec, fringilla in, laoreet vitae, risus.</li>
-  <li>Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
-  Suspendisse id sem consectetuer libero luctus adipiscing.</li>
-  </ul>
-  <p>But if you want to be lazy, you don't have to:</p>
-  <ul>
-  <li>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
-  Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
-  viverra nec, fringilla in, laoreet vitae, risus.</li>
-  <li>Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
-  Suspendisse id sem consectetuer libero luctus adipiscing.</li>
-  </ul>
-  <p>List items may consist of multiple paragraphs. Each subsequent
-  paragraph in a list item must be indented by either 4 spaces
-  or one tab:</p>
-  <ol>
-  <li><p>This is a list item with two paragraphs. Lorem ipsum dolor
-  sit amet, consectetuer adipiscing elit. Aliquam hendrerit
-  mi posuere lectus.</p>
-  <p>Vestibulum enim wisi, viverra nec, fringilla in, laoreet
-  vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
-  sit amet velit.</p>
-  </li>
-  <li><p>Suspendisse id sem consectetuer libero luctus adipiscing.</p>
-  </li>
-  </ol>
-  <p>It looks nice if you indent every line of the subsequent
-  paragraphs, but here again, Markdown will allow you to be
-  lazy:</p>
-  <ul>
-  <li><p>This is a list item with two paragraphs.</p>
-  <p>This is the second paragraph in the list item. You're
-  only required to indent the first line. Lorem ipsum dolor
-  sit amet, consectetuer adipiscing elit.</p>
-  </li>
-  <li><p>Another item in the same list.</p>
-  </li>
-  </ul>
-  <p>To put a blockquote within a list item, the blockquote's <code>&gt;</code>
-  delimiters need to be indented:</p>
-  <ul>
-  <li><p>A list item with a blockquote:</p>
-  <blockquote>
-  <p>This is a blockquote
-  inside a list item.</p>
-  </blockquote>
-  </li>
-  </ul>
-  <p>To put a code block within a list item, the code block needs
-  to be indented <em>twice</em> -- 8 spaces or two tabs:</p>
-  <ul>
-  <li><p>A list item with a code block:</p>
-  <pre><code>&lt;code goes here&gt;
-  </code></pre>
-  </li>
-  </ul>
-  <h3>Code Blocks</h3>
-  <p>Pre-formatted code blocks are used for writing about programming or
-  markup source code. Rather than forming normal paragraphs, the lines
-  of a code block are interpreted literally. Markdown wraps a code block
-  in both <code>&lt;pre&gt;</code> and <code>&lt;code&gt;</code> tags.</p>
-  <p>To produce a code block in Markdown, simply indent every line of the
-  block by at least 4 spaces or 1 tab.</p>
-  <p>This is a normal paragraph:</p>
-  <pre><code>This is a code block.
-  </code></pre>
-  <p>Here is an example of AppleScript:</p>
-  <pre><code>tell application &quot;Foo&quot;
-      beep
-  end tell
-  </code></pre>
-  <p>A code block continues until it reaches a line that is not indented
-  (or the end of the article).</p>
-  <p>Within a code block, ampersands (<code>&amp;</code>) and angle brackets (<code>&lt;</code> and <code>&gt;</code>)
-  are automatically converted into HTML entities. This makes it very
-  easy to include example HTML source code using Markdown -- just paste
-  it and indent it, and Markdown will handle the hassle of encoding the
-  ampersands and angle brackets. For example, this:</p>
-  <pre><code>&lt;div class=&quot;footer&quot;&gt;
-      &amp;copy; 2004 Foo Corporation
-  &lt;/div&gt;
-  </code></pre>
-  <p>Regular Markdown syntax is not processed within code blocks. E.g.,
-  asterisks are just literal asterisks within a code block. This means
-  it's also easy to use Markdown to write about Markdown's own syntax.</p>
-  <pre><code>tell application &quot;Foo&quot;
-      beep
-  end tell
-  </code></pre>
-  <h2>Span Elements</h2>
-  <h3>Links</h3>
-  <p>Markdown supports two style of links: <em>inline</em> and <em>reference</em>.</p>
-  <p>In both styles, the link text is delimited by [square brackets].</p>
-  <p>To create an inline link, use a set of regular parentheses immediately
-  after the link text's closing square bracket. Inside the parentheses,
-  put the URL where you want the link to point, along with an <em>optional</em>
-  title for the link, surrounded in quotes. For example:</p>
-  <p>This is <a href="http://example.com/">an example</a> inline link.</p>
-  <p><a href="http://example.net/">This link</a> has no title attribute.</p>
-  <h3>Emphasis</h3>
-  <p>Markdown treats asterisks (<code>*</code>) and underscores (<code>_</code>) as indicators of
-  emphasis. Text wrapped with one <code>*</code> or <code>_</code> will be wrapped with an
-  HTML <code>&lt;em&gt;</code> tag; double <code>*</code>'s or <code>_</code>'s will be wrapped with an HTML
-  <code>&lt;strong&gt;</code> tag. E.g., this input:</p>
-  <p><em>single asterisks</em></p>
-  <p><em>single underscores</em></p>
-  <p><strong>double asterisks</strong></p>
-  <p><strong>double underscores</strong></p>
-  <h3>Code</h3>
-  <p>To indicate a span of code, wrap it with backtick quotes (<code>`</code>).
-  Unlike a pre-formatted code block, a code span indicates code within a
-  normal paragraph. For example:</p>
-  <p>Use the <code>printf()</code> function.</p>
-  <h3>Table</h3>
-  <table>
-  <thead>
-  <tr>
-  <th>Item</th>
-  <th>Price</th>
-  <th># In stock</th>
-  </tr>
-  </thead>
-  <tbody>
-  <tr>
-  <td>Juicy Apples</td>
-  <td>1.99</td>
-  <td><em>7</em></td>
-  </tr>
-  <tr>
-  <td>Bananas</td>
-  <td><strong>1.89</strong></td>
-  <td>5234</td>
-  </tr>
-  <tr>
-  <td>Tomatoes</td>
-  <td><strong>1.89</strong></td>
-  <td>5234</td>
-  </tr>
-  </tbody>
-  </table>
-</footer>
-<footer>
-<pre>
-Folder with several child directories
       
-├── c2
+
-│   └── c3
+<h1 id="markdown-style-guide">Markdown style guide</h1>
-│       └── empty-file.txt
+
-├── empty-file.txt
+<p>Much of what makes Markdown great is the ability to write plain text, and get
-└── README.txt
+great formatted output as a result. To keep the slate clean for the next author,
+your Markdown should be simple and consistent with the whole corpus wherever
+possible.</p>
+
+<p>We seek to balance three goals:</p>
+
+<ol>
+<li><em>Source text is readable and portable.</em></li>
+<li><em>Markdown files are maintainable over time and across teams.</em></li>
+<li><em>The syntax is simple and easy to remember.</em></li>
+</ol>
+
+<p>Contents:</p>
+
+<ol>
+<li><a href="#document-layout">Document layout</a></li>
+<li><a href="#character-line-limit">Character line limit</a></li>
+<li><a href="#trailing-whitespace">Trailing whitespace</a></li>
+<li><a href="#headings">Headings</a>
+<ol>
+<li><a href="#atx-style-headings">ATX-style headings</a></li>
+<li><a href="#add-spacing-to-headings">Add spacing to headings</a></li>
+</ol>
+</li>
+<li><a href="#lists">Lists</a>
+<ol>
+<li><a href="#use-lazy-numbering-for-long-lists">Use lazy numbering for long lists</a></li>
+<li><a href="#nested-list-spacing">Nested list spacing</a></li>
+</ol>
+</li>
+<li><a href="#code">Code</a>
+<ol>
+<li><a href="#inline">Inline</a></li>
+<li><a href="#codeblocks">Codeblocks</a></li>
+<li><a href="#declare-the-language">Declare the language</a></li>
+<li><a href="#escape-newlines">Escape newlines</a></li>
+<li><a href="#nest-codeblocks-within-lists">Nest codeblocks within lists</a></li>
+</ol>
+</li>
+<li><a href="#links">Links</a>
+<ol>
+<li><a href="#use-informative-markdown-link-titles">Use informative Markdown link titles</a></li>
+</ol>
+</li>
+<li><a href="#images">Images</a></li>
+<li><a href="#prefer-lists-to-tables">Prefer lists to tables</a></li>
+<li><a href="#strongly-prefer-markdown-to-html">Strongly prefer Markdown to HTML</a></li>
+</ol>
+
+<h2 id="document-layout">Document layout</h2>
+
+<p>In general, most documents benefit from some variation of the following layout:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gh"># Document Title</span>
+
+Short introduction.
+
+[TOC]
+
+<span class="gu">## Topic</span>
+
+Content.
+
+<span class="gu">## See also</span>
+<span class="p">
+*</span> https://link-to-more-info
+</code></pre></div></div>
+
+<ol>
+<li>
+<p><code class="language-plaintext highlighter-rouge"># Document Title</code>: The first heading should be a level one heading, and
+should ideally be the same or nearly the same as the filename. The first
+level one heading is used as the page <code class="language-plaintext highlighter-rouge">&lt;title&gt;</code>.</p>
+</li>
+<li>
+<p><code class="language-plaintext highlighter-rouge">author</code>: <em>Optional</em>. If you’d like to claim ownership of the document or
+if you are very proud of it, add yourself under the title. However,
+revision history generally suffices.</p>
+</li>
+<li>
+<p><code class="language-plaintext highlighter-rouge">Short introduction.</code> 1-3 sentences providing a high-level overview of the
+topic. Imagine yourself as a complete newbie, who landed on your “Extending
+Foo” doc and needs to know the most basic assumptions you take for granted.
+“What is Foo? Why would I extend it?”</p>
+</li>
+<li>
+<p><code class="language-plaintext highlighter-rouge">[TOC]</code>: if you use hosting that supports table of contents, such as Gitiles,
+put <code class="language-plaintext highlighter-rouge">[TOC]</code> after the short introduction. See
+<a href="https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Table-of-contents"><code class="language-plaintext highlighter-rouge">[TOC]</code> documentation</a>.</p>
+</li>
+<li>
+<p><code class="language-plaintext highlighter-rouge">## Topic</code>: The rest of your headings should start from level 2.</p>
+</li>
+<li>
+<p><code class="language-plaintext highlighter-rouge">## See also</code>: Put miscellaneous links at the bottom for the user who wants
+to know more or didn’t find what she needed.</p>
+</li>
+</ol>
+
+<h2 id="character-line-limit">Character line limit</h2>
+
+<p>Obey projects’ character line limit wherever possible. Long URLs and tables are
+the usual suspects when breaking the rule. (Headings also can’t be wrapped, but
+we encourage keeping them short). Otherwise, wrap your text:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Lorem ipsum dolor sit amet, nec eius volumus patrioque cu, nec et commodo
+hendrerit, id nobis saperet fuisset ius.
+<span class="p">
+*</span>   Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur
+interesset. See the <span class="p">[</span><span class="nv">foo docs</span><span class="p">](</span><span class="sx">https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md</span><span class="p">)</span>.
+</code></pre></div></div>
+
+<p>Often, inserting a newline before a long link preserves readability while
+minimizing the overflow:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Lorem ipsum dolor sit amet. See the
+<span class="p">[</span><span class="nv">foo docs</span><span class="p">](</span><span class="sx">https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md</span><span class="p">)</span>
+for details.
+</code></pre></div></div>
+
+<h2 id="trailing-whitespace">Trailing whitespace</h2>
+
+<p>Don’t use trailing whitespace, use a trailing backslash.</p>
+
+<p>The <a href="http://spec.commonmark.org/0.20/#hard-line-breaks">CommonMark spec</a> decrees
+that two spaces at the end of a line should insert a <code class="language-plaintext highlighter-rouge">&lt;br /&gt;</code> tag. However, many
+directories have a trailing whitespace presubmit check in place, and many IDEs
+will clean it up anyway.</p>
+
+<p>Best practice is to avoid the need for a <code class="language-plaintext highlighter-rouge">&lt;br /&gt;</code> altogether. Markdown creates
+paragraph tags for you simply with newlines: get used to that.</p>
+
+<h2 id="headings">Headings</h2>
+
+<h3 id="atx-style-headings">ATX-style headings</h3>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gu">## Heading 2</span>
+</code></pre></div></div>
+
+<p>Headings with <code class="language-plaintext highlighter-rouge">=</code> or <code class="language-plaintext highlighter-rouge">-</code> underlines can be annoying to maintain and don’t fit
+with the rest of the heading syntax. The user has to ask: Does <code class="language-plaintext highlighter-rouge">---</code> mean H1 or
+H2?</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gh">Heading - do you remember what level? DO NOT DO THIS.
+---------
+</span></code></pre></div></div>
+
+<h3 id="add-spacing-to-headings">Add spacing to headings</h3>
+
+<p>Prefer spacing after <code class="language-plaintext highlighter-rouge">#</code> and newlines before and after:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>...text before.
+
+<span class="gh"># Heading 1</span>
+
+Text after...
+</code></pre></div></div>
+
+<p>Lack of spacing makes it a little harder to read in source:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>...text before.
+
+<span class="gh">#Heading 1</span>
+Text after... DO NOT DO THIS.
+</code></pre></div></div>
+
+<h2 id="lists">Lists</h2>
+
+<h3 id="use-lazy-numbering-for-long-lists">Use lazy numbering for long lists</h3>
+
+<p>Markdown is smart enough to let the resulting HTML render your numbered lists
+correctly. For longer lists that may change, especially long nested lists, use
+“lazy” numbering:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">1.</span>  Foo.
+<span class="p">1.</span>  Bar.
+<span class="p">    1.</span>  Foofoo.
+<span class="p">    1.</span>  Barbar.
+<span class="p">1.</span>  Baz.
+</code></pre></div></div>
+
+<p>However, if the list is small and you don’t anticipate changing it, prefer fully
+numbered lists, because it’s nicer to read in source:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">1.</span>  Foo.
+<span class="p">2.</span>  Bar.
+<span class="p">3.</span>  Baz.
+</code></pre></div></div>
+
+<h3 id="nested-list-spacing">Nested list spacing</h3>
+
+<p>When nesting lists, use a 4 space indent for both numbered and bulleted lists:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">1.</span>  2 spaces after a numbered list.
+4 space indent for wrapped text.
+<span class="p">2.</span>  2 spaces again.
+<span class="p">
+*</span>   3 spaces after a bullet.
+4 space indent for wrapped text.
+<span class="p">    1.</span>  2 spaces after a numbered list.
+  8 space indent for the wrapped text of a nested list.
+<span class="p">    2.</span>  Looks nice, don't it?
+<span class="p">*</span>   3 spaces after a bullet.
+</code></pre></div></div>
+
+<p>The following works, but it’s very messy:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span> One space,
+with no indent for wrapped text.
+<span class="p">     1.</span> Irregular nesting... DO NOT DO THIS.
+</code></pre></div></div>
+
+<p>Even when there’s no nesting, using the 4 space indent makes layout consistent
+for wrapped text:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span>   Foo,
+wrapped.
+<span class="p">
+1.</span>  2 spaces
+and 4 space indenting.
+<span class="p">2.</span>  2 spaces again.
+</code></pre></div></div>
+
+<p>However, when lists are small, not nested, and a single line, one space can
+suffice for both kinds of lists:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span> Foo
+<span class="p">*</span> Bar
+<span class="p">*</span> Baz.
+<span class="p">
+1.</span> Foo.
+<span class="p">2.</span> Bar.
+</code></pre></div></div>
+
+<h2 id="code">Code</h2>
+
+<h3 id="inline">Inline</h3>
+
+<p>`Backticks` designate <code class="language-plaintext highlighter-rouge">inline code</code>, and will render all wrapped content
+literally. Use them for short code quotations and field names:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>You'll want to run <span class="sb">`really_cool_script.sh arg`</span>.
+
+Pay attention to the <span class="sb">`foo_bar_whammy`</span> field in that table.
+</code></pre></div></div>
+
+<p>Use inline code when referring to file types in an abstract sense, rather than a
+specific file:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Be sure to update your <span class="sb">`README.md`</span>!
+</code></pre></div></div>
+
+<p>Backticks are the most common approach for “escaping” Markdown metacharacters;
+in most situations where escaping would be needed, code font just makes sense
+anyway.</p>
+
+<h3 id="codeblocks">Codeblocks</h3>
+
+<p>For code quotations longer than a single line, use a codeblock:</p>
+
+<pre>
+```python
+def Foo(self, bar):
+self.bar = bar
+```
 </pre>
 
-</footer>
+<h4 id="declare-the-language">Declare the language</h4>
+
+<p>It is best practice to explicitly declare the language, so that neither the
+syntax highlighter nor the next editor must guess.</p>
+
+<h4 id="indented-codeblocks-are-sometimes-cleaner">Indented codeblocks are sometimes cleaner</h4>
+
+<p>Four-space indenting is also interpreted as a codeblock. These can look
+cleaner and be easier to read in source, but there is no way to specify the
+language. We encourage their use when writing many short snippets:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>You'll need to run:<span class="sb">
+
+bazel run :thing -- --foo
+
+</span>And then:<span class="sb">
+
+bazel run :another_thing -- --bar
+
+</span>And again:<span class="sb">
+
+bazel run :yet_again -- --baz
+</span></code></pre></div></div>
+
+<h4 id="escape-newlines">Escape newlines</h4>
+
+<p>Because most commandline snippets are intended to be copied and pasted directly
+into a terminal, it’s best practice to escape any newlines. Use a single
+backslash at the end of the line:</p>
+
+<pre>
+```shell
+bazel run :target -- --flag --foo=longlonglonglonglongvalue \
+--bar=anotherlonglonglonglonglonglonglonglonglonglongvalue
+```
+</pre>
+
+<h4 id="nest-codeblocks-within-lists">Nest codeblocks within lists</h4>
+
+<p>If you need a codeblock within a list, make sure to indent it so as to not break
+the list:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span>   Bullet.<span class="sb">
+
+```c++
+int foo;
+```
+
+</span><span class="p">*</span>   Next bullet.
+</code></pre></div></div>
+
+<p>You can also create a nested code block with 4 spaces. Simply indent 4
+additional spaces from the list indentation:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span>   Bullet.<span class="sb">
+
+  int foo;
+
+</span><span class="p">*</span>   Next bullet.
+</code></pre></div></div>
+
+<h2 id="links">Links</h2>
+
+<p>Long links make source Markdown difficult to read and break the 80 character
+wrapping. <strong>Wherever possible, shorten your links</strong>.</p>
+
+<h3 id="use-informative-markdown-link-titles">Use informative Markdown link titles</h3>
+
+<p>Markdown link syntax allows you to set a link title, just as HTML does. Use it
+wisely.</p>
+
+<p>Titling your links as “link” or “here” tells the reader precisely nothing when
+quickly scanning your doc and is a waste of space:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>See the syntax guide for more info: <span class="p">[</span><span class="nv">link</span><span class="p">](</span><span class="sx">syntax_guide.md</span><span class="p">)</span>.
+Or, check out the style guide <span class="p">[</span><span class="nv">here</span><span class="p">](</span><span class="sx">style_guide.md</span><span class="p">)</span>.
+DO NOT DO THIS.
+</code></pre></div></div>
+
+<p>Instead, write the sentence naturally, then go back and wrap the most
+appropriate phrase with the link:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>See the <span class="p">[</span><span class="nv">syntax guide</span><span class="p">](</span><span class="sx">syntax_guide.md</span><span class="p">)</span> for more info.
+Or, check out the <span class="p">[</span><span class="nv">style guide</span><span class="p">](</span><span class="sx">style_guide.md</span><span class="p">)</span>.
+</code></pre></div></div>
+
+<h2 id="images">Images</h2>
+
+<p>Use images sparingly, and prefer simple screenshots. This guide is designed
+around the idea that plain text gets users down to the business of communication
+faster with less reader distraction and author procrastination. However, it’s
+sometimes very helpful to show what you mean.</p>
+
+<p>See <a href="https://gerrit.googlesource.com/gitiles/+/master/Documentation/markdown.md#Images">image syntax</a>.</p>
+
+<h2 id="prefer-lists-to-tables">Prefer lists to tables</h2>
+
+<p>Any tables in your Markdown should be small. Complex, large tables are difficult
+to read in source and most importantly, <strong>a pain to modify later</strong>.</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Fruit | Attribute | Notes
+--- | --- | --- | ---
+Apple | <span class="p">[</span><span class="nv">Juicy</span><span class="p">](</span><span class="sx">https://example.com/SomeReallyReallyReallyReallyReallyReallyReallyReallyLongQuery</span><span class="p">)</span>, Firm, Sweet | Apples keep doctors away.
+Banana | <span class="p">[</span><span class="nv">Convenient</span><span class="p">](</span><span class="sx">https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery</span><span class="p">)</span>, Soft, Sweet | Contrary to popular belief, most apes prefer mangoes.
+
+DO NOT DO THIS
+</code></pre></div></div>
+
+<p><a href="#lists">Lists</a> and subheadings usually suffice to present the same information
+in a slightly less compact, though much more edit-friendly way:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gu">## Fruits</span>
+
+<span class="gu">### Apple</span>
+<span class="p">
+*</span> <span class="p">[</span><span class="nv">Juicy</span><span class="p">](</span><span class="sx">https://SomeReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyReallyLongURL</span><span class="p">)</span>
+<span class="p">*</span> Firm
+<span class="p">*</span> Sweet
+
+Apples keep doctors away.
+
+<span class="gu">### Banana</span>
+<span class="p">
+*</span> <span class="p">[</span><span class="nv">Convenient</span><span class="p">](</span><span class="sx">https://example.com/SomeDifferentReallyReallyReallyReallyReallyReallyReallyReallyLongQuery</span><span class="p">)</span>
+<span class="p">*</span> Soft
+<span class="p">*</span> Sweet
+
+Contrary to popular belief, most apes prefer mangoes.
+</code></pre></div></div>
+
+<p>However, there are times when a small table is called for:</p>
+
+<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Transport | Favored by | Advantages
+--- | --- | ---
+Swallow | Coconuts | Otherwise unladen
+Bicycle | Miss Gulch | Weatherproof
+X-34 landspeeder | Whiny farmboys | Cheap since the X-38 came out
+</code></pre></div></div>
+
+<h2 id="strongly-prefer-markdown-to-html">Strongly prefer Markdown to HTML</h2>
+
+<p>Please prefer standard Markdown syntax wherever possible and avoid HTML hacks.
+If you can’t seem to accomplish what you want, reconsider whether you really
+need it. Except for <a href="#prefer-lists-to-tables">big tables</a>, Markdown meets almost
+all needs already.</p>
+
+<p>Every bit of HTML or Javascript hacking reduces the readability and portability.
+This in turn limits the usefulness of integrations with
+other tools, which may either present the source as plain text or render it. See
+<a href="/styleguide/docguide/philosophy.html">Philosophy</a>.</p>
+
+<p>Gitiles does not render HTML.</p>
 <!-- var t08_foot -->
     <script>
       var filterEl = document.getElementById("filter");