ThetaDev/ngx-awesomeindex
1
0
Fork 0
Code Issues Pull requests Projects Releases 2 Activity

Compare commits

base: ThetaDev:7756515f968f5d68bc47d4ba85fd8491449380dd
Branches Tags
ThetaDev:master
ThetaDev:v0.1.1
ThetaDev:v0.1.0
..
compare: ThetaDev:c85a9fa00b8e5e81904f19cfbe15b95a1c7b0f4f
Branches Tags
ThetaDev:master
ThetaDev:v0.1.1
ThetaDev:v0.1.0

2 commits
7756515f96 ... c85a9fa00b

Author SHA1 Message Date
ThetaDev
c85a9fa00b
feat: render txt files correctly 2024-03-15 12:07:30 +01:00
ThetaDev
f4c1d12c59
use md4c as markdown library 2024-03-15 11:27:14 +01:00
7 changed files with 441 additions and 494 deletions
Show stats Expand all files Collapse all files

2
config
View file

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

196
ngx_http_awesomeindex_module.c
View file

@ -22,10 +22,10 @@
#include <ngx_core.h> #include <ngx_core.h>
#include <ngx_http.h> #include <ngx_http.h>
#include <ngx_log.h> #include <ngx_log.h>
#include "ngx_buf.h"
#include "ngx_string.h" #include "ngx_string.h"
#include <mkdio.h> #include "md4c-html.h"
#include "template.h" #include "template.h"
#if defined(__GNUC__) && (__GNUC__ >= 3) #if defined(__GNUC__) && (__GNUC__ >= 3)
@ -328,7 +328,85 @@ ngx_awesomeindex_conf_set_headerfooter(ngx_conf_t *cf, ngx_command_t *cmd, void
#define ngx_has_flag(_where, _what) \ #define ngx_has_flag(_where, _what) \
(((_where) & (_what)) == (_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 { typedef struct {
@ -559,11 +637,21 @@ static const ngx_str_t img_icon_pre =
ngx_string("<img src=\""); ngx_string("<img src=\"");
static const ngx_str_t img_icon_post = static const ngx_str_t img_icon_post =
ngx_string("\" alt=\"\" height=\"32\" width=\"32\">"); ngx_string("\" alt=\"\" height=\"32\" width=\"32\">");
static const ngx_str_t footer_pre = static const ngx_str_t footer_md_pre =
ngx_string("<footer class=\"markup\">"); 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>");
static const ngx_str_t footer_post = static const ngx_str_t footer_post =
ngx_string("</footer>"); ngx_string("</footer>");
#define README_TXT 0
#define README_HTML 1
#define README_MD 2
#ifdef NGX_ESCAPE_URI_COMPONENT #ifdef NGX_ESCAPE_URI_COMPONENT
static inline uintptr_t static inline uintptr_t
@ -740,7 +828,7 @@ make_content_buf(
ngx_dir_t dir; ngx_dir_t dir;
ngx_buf_t *b; ngx_buf_t *b;
u_char *readme_path = NULL; u_char *readme_path = NULL;
u_char readme_md = 0; u_char readme_type = README_TXT;
off_t readme_file_len = 0; off_t readme_file_len = 0;
static const char *sizes[] = { "EiB", "PiB", "TiB", "GiB", "MiB", "KiB", "B" }; static const char *sizes[] = { "EiB", "PiB", "TiB", "GiB", "MiB", "KiB", "B" };
@ -925,7 +1013,11 @@ make_content_buf(
ngx_cpystrn(readme_path, filename, allocated); ngx_cpystrn(readme_path, filename, allocated);
readme_file_len = entry->size; readme_file_len = entry->size;
readme_md = entry->name.len > 6 && ngx_strncasecmp(entry->name.data + 6, (u_char*) ".md", 3) == 0; readme_type = README_TXT;
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;
}
} }
} }
@ -941,7 +1033,7 @@ make_content_buf(
if (readme_path) { if (readme_path) {
ngx_log_debug3(NGX_LOG_DEBUG_HTTP, r->connection->log, 0, ngx_log_debug3(NGX_LOG_DEBUG_HTTP, r->connection->log, 0,
"HTTP awesomeindex README: %s, MD%d, len: %d", readme_path, readme_md, readme_file_len); "http awesomeindex README: %s, type: %d, len: %d", readme_path, readme_type, readme_file_len);
} }
/* /*
@ -1019,21 +1111,47 @@ make_content_buf(
if (entry[i].link) len += ngx_sizeof_ssz("-shortcut"); if (entry[i].link) len += ngx_sizeof_ssz("-shortcut");
} }
char *readme_md_content; struct membuffer readme_md_content = {0};
if (readme_file_len) { if (readme_file_len) {
if (readme_md) { if (readme_type == README_MD) {
FILE *md_file = fopen((char *)readme_path, "r"); ngx_buf_t *buf_in = ngx_create_temp_buf(r->pool, readme_file_len);
MMIOT *mkd = mkd_in(md_file, MKD_FLAGS); ssize_t rbts = ngx_awesomeindex_read_file(r, readme_path, readme_file_len, buf_in->last);
mkd_compile(mkd, MKD_FLAGS);
readme_file_len = mkd_document(mkd, &readme_md_content); if (rbts != NGX_ERROR) {
fclose(md_file); buf_in->last += rbts;
ngx_log_debug2(NGX_LOG_DEBUG_HTTP, r->connection->log, 0, "converted %s, len=%d", readme_path, readme_file_len); ngx_log_debug(NGX_LOG_DEBUG_HTTP, r->connection->log, ngx_errno, "http awesomeindex: read %d bytes from %s", rbts, readme_path);
// 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; return NGX_HTTP_INTERNAL_SERVER_ERROR;
}
/* /*
* Determine the sorting criteria. URL arguments look like: * Determine the sorting criteria. URL arguments look like:
@ -1299,40 +1417,26 @@ make_content_buf(
// Readme file // Readme file
if (readme_file_len) { if (readme_file_len) {
b->last = ngx_cpymem_str(b->last, footer_pre); if (readme_type == README_MD) {
if (!readme_md_content.fail) {
if (readme_md) { b->last = ngx_cpymem_str(b->last, footer_md_pre);
b->last = ngx_cpymem(b->last, readme_md_content, readme_file_len); b->last = ngx_cpymem(b->last, readme_md_content.data, readme_md_content.size);
b->last = ngx_cpymem_str(b->last, footer_post);
}
membuf_free(&readme_md_content);
} else { } else {
ngx_file_t file; b->last = ngx_cpymem_str(b->last, footer_pre);
ngx_memzero(&file, sizeof(ngx_file_t)); if (readme_type == README_TXT) b->last = ngx_cpymem_str(b->last, codeblock_pre);
file.fd = ngx_open_file(readme_path, 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\"", 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);
ssize_t n = readme_file_len; ssize_t rbts = ngx_awesomeindex_read_file(r, readme_path, readme_file_len, b->last);
while (n > 0) { if (rbts != NGX_ERROR) b->last += rbts;
ssize_t rbts = ngx_read_file(&file, else {
b->last + file.offset, ngx_log_error(NGX_LOG_ALERT, r->connection->log, ngx_errno, "cannot read file \"%V\"", readme_path);
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;
} }
if (readme_type == README_TXT) b->last = ngx_cpymem_str(b->last, codeblock_post);
b->last = ngx_cpymem_str(b->last, footer_post);
} }
b->last = ngx_cpymem_str(b->last, footer_post);
} }
*pb = b; *pb = b;

17
t/README.md
View file

@ -1,22 +1,5 @@
# Markdown: Syntax # 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 ## Overview
### Philosophy ### Philosophy

7
t/child-directory/README.txt Normal file
View file

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

3
t/show_dotfiles/README.html Normal file
View file

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

5
template.h
View file

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

705
template.html
View file

@ -127,11 +127,11 @@ main {
} }
footer { footer {
padding: 40px 20px; padding: 40px 20px;
font-size: 16px;
} }
.markup { .markup {
max-width: 790px; max-width: 790px;
word-wrap: break-word; word-wrap: break-word;
font-size: 16px;
overflow: hidden; overflow: hidden;
line-height: 1.5 !important; line-height: 1.5 !important;
} }
@ -384,9 +384,6 @@ footer {
.meta { .meta {
border-bottom: 1px solid #212121; border-bottom: 1px solid #212121;
} }
footer code, footer pre {
background-color: rgb(8, 36, 55);
}
} }
</style> </style>
<!-- var NONE --> <!-- var NONE -->
@ -609,431 +606,287 @@ Index of /path/to/somewhere
</main> </main>
<!-- var NONE --> <!-- var NONE -->
<h1><a href="https://google.github.io/styleguide/">styleguide</a></h1> <footer class="markup"><h1>Markdown: Syntax</h1>
<h2>Overview</h2>
<h3>Philosophy</h3>
<h1 id="markdown-style-guide">Markdown style guide</h1> <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
<p>Much of what makes Markdown great is the ability to write plain text, and get document should be publishable as-is, as plain text, without looking
great formatted output as a result. To keep the slate clean for the next author, like it's been marked up with tags or formatting instructions. While
your Markdown should be simple and consistent with the whole corpus wherever Markdown's syntax has been influenced by several existing text-to-HTML
possible.</p> 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
<p>We seek to balance three goals:</p> inspiration for Markdown's syntax is the format of plain text email.</p>
<h2>Block Elements</h2>
<ol> <h3>Paragraphs and Line Breaks</h3>
<li><em>Source text is readable and portable.</em></li> <p>A paragraph is simply one or more consecutive lines of text, separated
<li><em>Markdown files are maintainable over time and across teams.</em></li> by one or more blank lines. (A blank line is any line that looks like a
<li><em>The syntax is simple and easy to remember.</em></li> blank line -- a line containing nothing but spaces or tabs is considered
</ol> 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
<p>Contents:</p> that Markdown supports &quot;hard-wrapped&quot; text paragraphs. This differs
significantly from most other text-to-HTML formatters (including Movable
<ol> Type's &quot;Convert Line Breaks&quot; option) which translate every line break
<li><a href="#document-layout">Document layout</a></li> character in a paragraph into a <code>&lt;br /&gt;</code> tag.</p>
<li><a href="#character-line-limit">Character line limit</a></li> <p>When you <em>do</em> want to insert a <code>&lt;br /&gt;</code> break tag using Markdown, you
<li><a href="#trailing-whitespace">Trailing whitespace</a></li> end a line with two or more spaces, then type return.</p>
<li><a href="#headings">Headings</a> <h3>Headers</h3>
<ol> <p>Markdown supports two styles of headers, [Setext] [1] and [atx] [2].</p>
<li><a href="#atx-style-headings">ATX-style headings</a></li> <p>Optionally, you may &quot;close&quot; atx-style headers. This is purely
<li><a href="#add-spacing-to-headings">Add spacing to headings</a></li> cosmetic -- you can use this if you think it looks better. The
</ol> closing hashes don't even need to match the number of hashes
</li> used to open the header. (The number of opening hashes
<li><a href="#lists">Lists</a> determines the header level.)</p>
<ol> <h3>Blockquotes</h3>
<li><a href="#use-lazy-numbering-for-long-lists">Use lazy numbering for long lists</a></li> <p>Markdown uses email-style <code>&gt;</code> characters for blockquoting. If you're
<li><a href="#nested-list-spacing">Nested list spacing</a></li> familiar with quoting passages of text in an email message, then you
</ol> know how to create a blockquote in Markdown. It looks best if you hard
</li> wrap the text and put a <code>&gt;</code> before every line:</p>
<li><a href="#code">Code</a> <blockquote>
<ol> <p>This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
<li><a href="#inline">Inline</a></li> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
<li><a href="#codeblocks">Codeblocks</a></li> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.</p>
<li><a href="#declare-the-language">Declare the language</a></li> <p>Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
<li><a href="#escape-newlines">Escape newlines</a></li> id sem consectetuer libero luctus adipiscing.</p>
<li><a href="#nest-codeblocks-within-lists">Nest codeblocks within lists</a></li> </blockquote>
</ol> <p>Markdown allows you to be lazy and only put the <code>&gt;</code> before the first
</li> line of a hard-wrapped paragraph:</p>
<li><a href="#links">Links</a> <blockquote>
<ol> <p>This is a blockquote with two paragraphs. Lorem ipsum dolor sit amet,
<li><a href="#use-informative-markdown-link-titles">Use informative Markdown link titles</a></li> consectetuer adipiscing elit. Aliquam hendrerit mi posuere lectus.
</ol> Vestibulum enim wisi, viverra nec, fringilla in, laoreet vitae, risus.</p>
</li> </blockquote>
<li><a href="#images">Images</a></li> <blockquote>
<li><a href="#prefer-lists-to-tables">Prefer lists to tables</a></li> <p>Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse
<li><a href="#strongly-prefer-markdown-to-html">Strongly prefer Markdown to HTML</a></li> id sem consectetuer libero luctus adipiscing.</p>
</ol> </blockquote>
<p>Blockquotes can be nested (i.e. a blockquote-in-a-blockquote) by
<h2 id="document-layout">Document layout</h2> adding additional levels of <code>&gt;</code>:</p>
<blockquote>
<p>In general, most documents benefit from some variation of the following layout:</p> <p>This is the first level of quoting.</p>
<blockquote>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gh"># Document Title</span> <p>This is nested blockquote.</p>
</blockquote>
Short introduction. <p>Back to the first level.</p>
</blockquote>
[TOC] <p>Blockquotes can contain other Markdown elements, including headers, lists,
and code blocks:</p>
<span class="gu">## Topic</span> <blockquote>
<h2>This is a header.</h2>
Content. <ol>
<li>This is the first list item.</li>
<span class="gu">## See also</span> <li>This is the second list item.</li>
<span class="p"> </ol>
*</span> https://link-to-more-info <p>Here's some example code:</p>
</code></pre></div></div> <pre><code>return shell_exec(&quot;echo $input | $markdown_script&quot;);
</code></pre>
<ol> </blockquote>
<li> <p>Any decent text editor should make email-style quoting easy. For
<p><code class="language-plaintext highlighter-rouge"># Document Title</code>: The first heading should be a level one heading, and example, with BBEdit, you can make a selection and choose Increase
should ideally be the same or nearly the same as the filename. The first Quote Level from the Text menu.</p>
level one heading is used as the page <code class="language-plaintext highlighter-rouge">&lt;title&gt;</code>.</p> <h3>Lists</h3>
</li> <p>Markdown supports ordered (numbered) and unordered (bulleted) lists.</p>
<li> <p>Unordered lists use asterisks, pluses, and hyphens -- interchangably
<p><code class="language-plaintext highlighter-rouge">author</code>: <em>Optional</em>. If you’d like to claim ownership of the document or -- as list markers:</p>
if you are very proud of it, add yourself under the title. However, <ul>
revision history generally suffices.</p> <li>Red</li>
</li> <li>Green</li>
<li> <li>Blue</li>
<p><code class="language-plaintext highlighter-rouge">Short introduction.</code> 1-3 sentences providing a high-level overview of the </ul>
topic. Imagine yourself as a complete newbie, who landed on your “Extending <p>is equivalent to:</p>
Foo” doc and needs to know the most basic assumptions you take for granted. <ul>
“What is Foo? Why would I extend it?”</p> <li>Red</li>
</li> <li>Green</li>
<li> <li>Blue</li>
<p><code class="language-plaintext highlighter-rouge">[TOC]</code>: if you use hosting that supports table of contents, such as Gitiles, </ul>
put <code class="language-plaintext highlighter-rouge">[TOC]</code> after the short introduction. See <p>and:</p>
<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> <ul>
</li> <li>Red</li>
<li> <li>Green</li>
<p><code class="language-plaintext highlighter-rouge">## Topic</code>: The rest of your headings should start from level 2.</p> <li>Blue</li>
</li> </ul>
<li> <p>Ordered lists use numbers followed by periods:</p>
<p><code class="language-plaintext highlighter-rouge">## See also</code>: Put miscellaneous links at the bottom for the user who wants <ol>
to know more or didn’t find what she needed.</p> <li>Bird</li>
</li> <li>McHale</li>
</ol> <li>Parish</li>
</ol>
<h2 id="character-line-limit">Character line limit</h2> <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
<p>Obey projects’ character line limit wherever possible. Long URLs and tables are Markdown produces from the above list is:</p>
the usual suspects when breaking the rule. (Headings also can’t be wrapped, but <p>If you instead wrote the list in Markdown like this:</p>
we encourage keeping them short). Otherwise, wrap your text:</p> <ol>
<li>Bird</li>
<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 <li>McHale</li>
hendrerit, id nobis saperet fuisset ius. <li>Parish</li>
<span class="p"> </ol>
*</span> Malorum moderatius vim eu. In vix dico persecuti. Te nam saperet percipitur <p>or even:</p>
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>. <ol start="3">
</code></pre></div></div> <li>Bird</li>
<li>McHale</li>
<p>Often, inserting a newline before a long link preserves readability while <li>Parish</li>
minimizing the overflow:</p> </ol>
<p>you'd get the exact same HTML output. The point is, if you want to,
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Lorem ipsum dolor sit amet. See the you can use ordinal numbers in your ordered Markdown lists, so that
<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> the numbers in your source match the numbers in your published HTML.
for details. But if you want to be lazy, you don't have to.</p>
</code></pre></div></div> <p>To make lists look nice, you can wrap items with hanging indents:</p>
<ul>
<h2 id="trailing-whitespace">Trailing whitespace</h2> <li>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
<p>Don’t use trailing whitespace, use a trailing backslash.</p> viverra nec, fringilla in, laoreet vitae, risus.</li>
<li>Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
<p>The <a href="http://spec.commonmark.org/0.20/#hard-line-breaks">CommonMark spec</a> decrees Suspendisse id sem consectetuer libero luctus adipiscing.</li>
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 </ul>
directories have a trailing whitespace presubmit check in place, and many IDEs <p>But if you want to be lazy, you don't have to:</p>
will clean it up anyway.</p> <ul>
<li>Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
<p>Best practice is to avoid the need for a <code class="language-plaintext highlighter-rouge">&lt;br /&gt;</code> altogether. Markdown creates Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
paragraph tags for you simply with newlines: get used to that.</p> viverra nec, fringilla in, laoreet vitae, risus.</li>
<li>Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
<h2 id="headings">Headings</h2> Suspendisse id sem consectetuer libero luctus adipiscing.</li>
</ul>
<h3 id="atx-style-headings">ATX-style headings</h3> <p>List items may consist of multiple paragraphs. Each subsequent
paragraph in a list item must be indented by either 4 spaces
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="gu">## Heading 2</span> or one tab:</p>
</code></pre></div></div> <ol>
<li><p>This is a list item with two paragraphs. Lorem ipsum dolor
<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 sit amet, consectetuer adipiscing elit. Aliquam hendrerit
with the rest of the heading syntax. The user has to ask: Does <code class="language-plaintext highlighter-rouge">---</code> mean H1 or mi posuere lectus.</p>
H2?</p> <p>Vestibulum enim wisi, viverra nec, fringilla in, laoreet
vitae, risus. Donec sit amet nisl. Aliquam semper ipsum
<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. sit amet velit.</p>
--------- </li>
</span></code></pre></div></div> <li><p>Suspendisse id sem consectetuer libero luctus adipiscing.</p>
</li>
<h3 id="add-spacing-to-headings">Add spacing to headings</h3> </ol>
<p>It looks nice if you indent every line of the subsequent
<p>Prefer spacing after <code class="language-plaintext highlighter-rouge">#</code> and newlines before and after:</p> paragraphs, but here again, Markdown will allow you to be
lazy:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>...text before. <ul>
<li><p>This is a list item with two paragraphs.</p>
<span class="gh"># Heading 1</span> <p>This is the second paragraph in the list item. You're
only required to indent the first line. Lorem ipsum dolor
Text after... sit amet, consectetuer adipiscing elit.</p>
</code></pre></div></div> </li>
<li><p>Another item in the same list.</p>
<p>Lack of spacing makes it a little harder to read in source:</p> </li>
</ul>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>...text before. <p>To put a blockquote within a list item, the blockquote's <code>&gt;</code>
delimiters need to be indented:</p>
<span class="gh">#Heading 1</span> <ul>
Text after... DO NOT DO THIS. <li><p>A list item with a blockquote:</p>
</code></pre></div></div> <blockquote>
<p>This is a blockquote
<h2 id="lists">Lists</h2> inside a list item.</p>
</blockquote>
<h3 id="use-lazy-numbering-for-long-lists">Use lazy numbering for long lists</h3> </li>
</ul>
<p>Markdown is smart enough to let the resulting HTML render your numbered lists <p>To put a code block within a list item, the code block needs
correctly. For longer lists that may change, especially long nested lists, use to be indented <em>twice</em> -- 8 spaces or two tabs:</p>
“lazy” numbering:</p> <ul>
<li><p>A list item with a code block:</p>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">1.</span> Foo. <pre><code>&lt;code goes here&gt;
<span class="p">1.</span> Bar. </code></pre>
<span class="p"> 1.</span> Foofoo. </li>
<span class="p"> 1.</span> Barbar. </ul>
<span class="p">1.</span> Baz. <h3>Code Blocks</h3>
</code></pre></div></div> <p>Pre-formatted code blocks are used for writing about programming or
markup source code. Rather than forming normal paragraphs, the lines
<p>However, if the list is small and you don’t anticipate changing it, prefer fully of a code block are interpreted literally. Markdown wraps a code block
numbered lists, because it’s nicer to read in source:</p> 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
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">1.</span> Foo. block by at least 4 spaces or 1 tab.</p>
<span class="p">2.</span> Bar. <p>This is a normal paragraph:</p>
<span class="p">3.</span> Baz. <pre><code>This is a code block.
</code></pre></div></div> </code></pre>
<p>Here is an example of AppleScript:</p>
<h3 id="nested-list-spacing">Nested list spacing</h3> <pre><code>tell application &quot;Foo&quot;
beep
<p>When nesting lists, use a 4 space indent for both numbered and bulleted lists:</p> end tell
</code></pre>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">1.</span> 2 spaces after a numbered list. <p>A code block continues until it reaches a line that is not indented
4 space indent for wrapped text. (or the end of the article).</p>
<span class="p">2.</span> 2 spaces again. <p>Within a code block, ampersands (<code>&amp;</code>) and angle brackets (<code>&lt;</code> and <code>&gt;</code>)
<span class="p"> are automatically converted into HTML entities. This makes it very
*</span> 3 spaces after a bullet. easy to include example HTML source code using Markdown -- just paste
4 space indent for wrapped text. it and indent it, and Markdown will handle the hassle of encoding the
<span class="p"> 1.</span> 2 spaces after a numbered list. ampersands and angle brackets. For example, this:</p>
8 space indent for the wrapped text of a nested list. <pre><code>&lt;div class=&quot;footer&quot;&gt;
<span class="p"> 2.</span> Looks nice, don't it? &amp;copy; 2004 Foo Corporation
<span class="p">*</span> 3 spaces after a bullet. &lt;/div&gt;
</code></pre></div></div> </code></pre>
<p>Regular Markdown syntax is not processed within code blocks. E.g.,
<p>The following works, but it’s very messy:</p> 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>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span> One space, <pre><code>tell application &quot;Foo&quot;
with no indent for wrapped text. beep
<span class="p"> 1.</span> Irregular nesting... DO NOT DO THIS. end tell
</code></pre></div></div> </code></pre>
<h2>Span Elements</h2>
<p>Even when there’s no nesting, using the 4 space indent makes layout consistent <h3>Links</h3>
for wrapped text:</p> <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>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span> Foo, <p>To create an inline link, use a set of regular parentheses immediately
wrapped. after the link text's closing square bracket. Inside the parentheses,
<span class="p"> put the URL where you want the link to point, along with an <em>optional</em>
1.</span> 2 spaces title for the link, surrounded in quotes. For example:</p>
and 4 space indenting. <p>This is <a href="http://example.com/">an example</a> inline link.</p>
<span class="p">2.</span> 2 spaces again. <p><a href="http://example.net/">This link</a> has no title attribute.</p>
</code></pre></div></div> <h3>Emphasis</h3>
<p>Markdown treats asterisks (<code>*</code>) and underscores (<code>_</code>) as indicators of
<p>However, when lists are small, not nested, and a single line, one space can emphasis. Text wrapped with one <code>*</code> or <code>_</code> will be wrapped with an
suffice for both kinds of lists:</p> 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>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="p">*</span> Foo <p><em>single asterisks</em></p>
<span class="p">*</span> Bar <p><em>single underscores</em></p>
<span class="p">*</span> Baz. <p><strong>double asterisks</strong></p>
<span class="p"> <p><strong>double underscores</strong></p>
1.</span> Foo. <h3>Code</h3>
<span class="p">2.</span> Bar. <p>To indicate a span of code, wrap it with backtick quotes (<code>`</code>).
</code></pre></div></div> Unlike a pre-formatted code block, a code span indicates code within a
normal paragraph. For example:</p>
<h2 id="code">Code</h2> <p>Use the <code>printf()</code> function.</p>
<h3>Table</h3>
<h3 id="inline">Inline</h3> <table>
<thead>
<p>`Backticks` designate <code class="language-plaintext highlighter-rouge">inline code</code>, and will render all wrapped content <tr>
literally. Use them for short code quotations and field names:</p> <th>Item</th>
<th>Price</th>
<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>. <th># In stock</th>
</tr>
Pay attention to the <span class="sb">`foo_bar_whammy`</span> field in that table. </thead>
</code></pre></div></div> <tbody>
<tr>
<p>Use inline code when referring to file types in an abstract sense, rather than a <td>Juicy Apples</td>
specific file:</p> <td>1.99</td>
<td><em>7</em></td>
<div class="language-markdown highlighter-rouge"><div class="highlight"><pre class="highlight"><code>Be sure to update your <span class="sb">`README.md`</span>! </tr>
</code></pre></div></div> <tr>
<td>Bananas</td>
<p>Backticks are the most common approach for “escaping” Markdown metacharacters; <td><strong>1.89</strong></td>
in most situations where escaping would be needed, code font just makes sense <td>5234</td>
anyway.</p> </tr>
<tr>
<h3 id="codeblocks">Codeblocks</h3> <td>Tomatoes</td>
<td><strong>1.89</strong></td>
<p>For code quotations longer than a single line, use a codeblock:</p> <td>5234</td>
</tr>
</tbody>
</table>
</footer>
<footer>
<pre> <pre>
```python Folder with several child directories
def Foo(self, bar):
self.bar = bar ├── c2
``` │ └── c3
│ └── empty-file.txt
├── empty-file.txt
└── README.txt
</pre> </pre>
<h4 id="declare-the-language">Declare the language</h4> </footer>
<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 --> <!-- var t08_foot -->
<script> <script>
var filterEl = document.getElementById("filter"); var filterEl = document.getElementById("filter");