Overview
- Markdown H1 Class
- Markdown H1n1 Pandemic
- Discord Markdown H1
- Markdown H1 Without Underline
- Markdown H1 2
Nearly all Markdown applications support the basic syntax outlined in John Gruber’s original design document. There are minor variations and discrepancies between Markdown processors — those are noted inline wherever possible.
Headings
- From adam-p/markdown-here. Table of Contents. Headers Emphasis Lists Links Images Code and Syntax Highlighting Tables Blockquotes Inline HTML Horizontal Rule Line Breaks Youtube videos. Headers # H1 ## H2 ### H3 #### H4 ##### H5 ##### H6 Alternatively, for H1 and H2, an underline-ish style: Alt-H1 Alt-H2 - H1 H2 H3 H4 H5 H6.
- Converted Markdown h1 State Farm ? h2 Berkshire Hathaway - ### h3 Progressive Group #### h4 Liberty Mutual ##### h5 Allstate ##### h6 Travelers Group.
To create a heading, add number signs (
#
) in front of a word or phrase. The number of number signs you use should correspond to the heading level. For example, to create a heading level three (<h3>
), use three number signs (e.g., ### My Header
).Markdown | HTML | Rendered Output |
---|---|---|
# Heading level 1 | <h1>Heading level 1</h1> | |
## Heading level 2 | <h2>Heading level 2</h2> | Heading level 2 |
### Heading level 3 | <h3>Heading level 3</h3> | Heading level 3 |
#### Heading level 4 | <h4>Heading level 4</h4> | Heading level 4 |
##### Heading level 5 | <h5>Heading level 5</h5> | Heading level 5 |
###### Heading level 6 | <h6>Heading level 6</h6> | Heading level 6 |
Alternate Syntax
Alternatively, on the line below the text, add any number of characters for heading level 1 or
--
characters for heading level 2.Convert your markdown to HTML in one easy step - for free!
Markdown | HTML | Rendered Output |
---|---|---|
Heading level 1 | <h1>Heading level 1</h1> | |
Heading level 2 | <h2>Heading level 2</h2> | Heading level 2 |
Heading Best Practices
Markdown applications don’t agree on how to handle a missing space between the number signs (
#
) and the heading name. For compatibility, always put a space between the number signs and the heading name.✅ Do this | ❌ Don't do this |
---|---|
# Here's a Heading | #Here's a Heading |
Paragraphs
To create paragraphs, use a blank line to separate one or more lines of text.
Markdown | HTML | Rendered Output |
---|---|---|
I really like using Markdown. | <p>I really like using Markdown.</p> | I really like using Markdown. I think I'll use it to format all of my documents from now on. |
Paragraph Best Practices
Unless the paragraph is in a list, don’t indent paragraphs with spaces or tabs.
✅ Do this | ❌ Don't do this |
---|---|
Don't put tabs or spaces in front of your paragraphs. | This can result in unexpected formatting problems. |
Line Breaks
To create a line break (
<br>
), end a line with two or more spaces, and then type return.Markdown | HTML | Rendered Output |
---|---|---|
This is the first line. | <p>This is the first line.<br> | This is the first line. And this is the second line. |
Line Break Best Practices
You can use two or more spaces (commonly referred to as “trailing whitespace”) for line breaks in nearly every Markdown application, but it’s controversial. It’s hard to see trailing whitespace in an editor, and many people accidentally or intentionally put two spaces after every sentence. For this reason, you may want to use something other than trailing whitespace for line breaks. Fortunately, there is another option supported by nearly every Markdown application: the
<br>
HTML tag.For compatibility, use trailing white space or the
<br>
HTML tag at the end of the line.There are two other options I don’t recommend using. CommonMark and a few other lightweight markup languages let you type a backslash (
) at the end of the line, but not all Markdown applications support this, so it isn’t a great option from a compatibility perspective. And at least a couple lightweight markup languages don’t require anything at the end of the line — just type return and they’ll create a line break.✅ Do this | ❌ Don't do this |
---|---|
First line with two spaces after. | First line with a backslash after. |
Markdown H1 Class
Emphasis
You can add emphasis by making text bold or italic.
Bold
To bold text, add two asterisks or underscores before and after a word or phrase. To bold the middle of a word for emphasis, add two asterisks without spaces around the letters.
Markdown | HTML | Rendered Output |
---|---|---|
I just love **bold text**. | I just love <strong>bold text</strong>. | I just love bold text. |
I just love __bold text__. | I just love <strong>bold text</strong>. | I just love bold text. |
Love**is**bold | Love<strong>is</strong>bold | Loveisbold |
Bold Best Practices
Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to bold the middle of a word for emphasis.
✅ Do this | ❌ Don't do this |
---|---|
Love**is**bold | Love__is__bold |
Italic
To italicize text, add one asterisk or underscore before and after a word or phrase. To italicize the middle of a word for emphasis, add one asterisk without spaces around the letters.
Markdown | HTML | Rendered Output |
---|---|---|
Italicized text is the *cat's meow*. | Italicized text is the <em>cat's meow</em>. | Italicized text is the cat’s meow. |
Italicized text is the _cat's meow_. | Italicized text is the <em>cat's meow</em>. | Italicized text is the cat’s meow. |
A*cat*meow | A<em>cat</em>meow | Acatmeow |
Italic Best Practices
Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to italicize the middle of a word for emphasis.
✅ Do this | ❌ Don't do this |
---|---|
A*cat*meow | A_cat_meow |
Bold and Italic
To emphasize text with bold and italics at the same time, add three asterisks or underscores before and after a word or phrase. To bold and italicize the middle of a word for emphasis, add three asterisks without spaces around the letters.
Markdown | HTML | Rendered Output |
---|---|---|
This text is ***really important***. | This text is <strong><em>really important</em></strong>. | This text is really important. |
This text is ___really important___. | This text is <strong><em>really important</em></strong>. | This text is really important. |
This text is __*really important*__. | This text is <strong><em>really important</em></strong>. | This text is really important. |
This text is **_really important_**. | This text is <strong><em>really important</em></strong>. | This text is really important. |
This is really***very***important text. | This is really<strong><em>very</em></strong>important text. | This is reallyveryimportant text. |
Bold and Italic Best Practices
Markdown applications don’t agree on how to handle underscores in the middle of a word. For compatibility, use asterisks to bold and italicize the middle of a word for emphasis.
✅ Do this | ❌ Don't do this |
---|---|
This is really***very***important text. | This is really___very___important text. |
Blockquotes
To create a blockquote, add a
>
in front of a paragraph.The rendered output looks like this:
Dorothy followed her through many of the beautiful rooms in her castle.
Blockquotes with Multiple Paragraphs
Blockquotes can contain multiple paragraphs. Add a
>
on the blank lines between the paragraphs.The rendered output looks like this:
Dorothy followed her through many of the beautiful rooms in her castle.
The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
Nested Blockquotes
Blockquotes can be nested. Add a
>>
in front of the paragraph you want to nest.The rendered output looks like this:
Dorothy followed her through many of the beautiful rooms in her castle.
The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
Blockquotes with Other Elements
Blockquotes can contain other Markdown formatted elements. Not all elements can be used — you’ll need to experiment to see which ones work.
The rendered output looks like this:
The quarterly results look great!
- Revenue was off the chart.
- Profits were higher than ever.
Everything is going according to plan.
Lists
You can organize items into ordered and unordered lists.
Ordered Lists
To create an ordered list, add line items with numbers followed by periods. The numbers don’t have to be in numerical order, but the list should start with the number one.
Markdown | HTML | Rendered Output |
---|---|---|
1. First item | <ol> |
|
1. First item | <ol> |
|
1. First item | <ol> |
|
1. First item | <ol> |
|
Ordered List Best Practices
CommonMark and a few other lightweight markup languages let you use a parenthesis (
)
) as a delimiter (e.g., 1) First item
), but not all Markdown applications support this, so it isn’t a great option from a compatibility perspective. For compatibility, use periods only.✅ Do this | ❌ Don't do this |
---|---|
1. First item | 1) First item |
Unordered Lists
To create an unordered list, add dashes (
-
), asterisks (*
), or plus signs (+
) in front of line items. Indent one or more items to create a nested list.Markdown | HTML | Rendered Output |
---|---|---|
- First item | <ul> |
|
* First item | <ul> |
|
+ First item | <ul> |
|
- First item | <ul> |
|
Starting Unordered List Items With Numbers
If you need to start an unordered list item with a number followed by a period, you can use a backslash (
) to escape the period.Markdown | HTML | Rendered Output |
---|---|---|
- 1968. A great year! | <ul> |
|
Unordered List Best Practices
Markdown applications don’t agree on how to handle different delimiters in the same list. For compatibility, don’t mix and match delimiters in the same list — pick one and stick with it.
✅ Do this | ❌ Don't do this |
---|---|
- First item | + First item |
Adding Elements in Lists
To add another element in a list while preserving the continuity of the list, indent the element four spaces or one tab, as shown in the following examples.
Paragraphs
The rendered output looks like this:
- This is the first list item.
- Here’s the second list item.I need to add another paragraph below the second list item.
- And here’s the third list item.
Blockquotes
The rendered output looks like this:
- This is the first list item.
- Here’s the second list item.A blockquote would look great below the second list item.
- And here’s the third list item.
Code Blocks
Code blocks are normally indented four spaces or one tab. When they’re in a list, indent them eight spaces or two tabs.
The rendered output looks like this:
- Open the file.
- Find the following code block on line 21:
- Update the title to match the name of your website.
Images
The rendered output looks like this:
- Open the file containing the Linux mascot.
- Marvel at its beauty.
- Close the file.
Lists
You can nest an unordered list in an ordered list, or vice versa.
The rendered output looks like this:
- First item
- Second item
- Third item
- Indented item
- Indented item
- Fourth item
Code
To denote a word or phrase as code, enclose it in backticks (
`
).Markdown | HTML | Rendered Output |
---|---|---|
At the command prompt, type `nano`. | At the command prompt, type <code>nano</code>. | At the command prompt, type nano . |
Escaping Backticks
If the word or phrase you want to denote as code includes one or more backticks, you can escape it by enclosing the word or phrase in double backticks (
``
).Markdown | HTML | Rendered Output |
---|---|---|
``Use `code` in your Markdown file.`` | <code>Use `code` in your Markdown file.</code> | Use `code` in your Markdown file. |
Code Blocks
To create code blocks, indent every line of the block by at least four spaces or one tab.
The rendered output looks like this:
Note: To create code blocks without indenting lines, use fenced code blocks.
Horizontal Rules
To create a horizontal rule, use three or more asterisks (
***
), dashes (---
), or underscores (___
) on a line by themselves.The rendered output of all three looks identical:
Horizontal Rule Best Practices
For compatibility, put blank lines before and after horizontal rules.
✅ Do this | ❌ Don't do this |
---|---|
Try to put a blank line before.. | Without blank lines, this would be a heading. |
Links
To create a link, enclose the link text in brackets (e.g.,
[Duck Duck Go]
) and then follow it immediately with the URL in parentheses (e.g., (https://duckduckgo.com)
).The rendered output looks like this:
My favorite search engine is Duck Duck Go.
Adding Titles
You can optionally add a title for a link. This will appear as a tooltip when the user hovers over the link. To add a title, enclose it in parentheses after the URL.
The rendered output looks like this:
My favorite search engine is Duck Duck Go.
URLs and Email Addresses
To quickly turn a URL or email address into a link, enclose it in angle brackets.
The rendered output looks like this:
https://www.markdownguide.org
[email protected]
[email protected]
Formatting Links
To emphasize links, add asterisks before and after the brackets and parentheses. To denote links as code, add backticks in the brackets.
The rendered output looks like this:
I love supporting the EFF.
This is the Markdown Guide.
See the section on
This is the Markdown Guide.
See the section on
code
.Reference-style Links
Reference-style links are a special kind of link that make URLs easier to display and read in Markdown. Reference-style links are constructed in two parts: the part you keep inline with your text and the part you store somewhere else in the file to keep the text easy to read.
Formatting the First Part of the Link
The first part of a reference-style link is formatted with two sets of brackets. The first set of brackets surrounds the text that should appear linked. The second set of brackets displays a label used to point to the link you’re storing elsewhere in your document.
Although not required, you can include a space between the first and second set of brackets. The label in the second set of brackets is not case sensitive and can include letters, numbers, spaces, or punctuation.
This means the following example formats are roughly equivalent for the first part of the link:
[hobbit-hole][1]
[hobbit-hole] [1]
Formatting the Second Part of the Link
The second part of a reference-style link is formatted with the following attributes:
- The label, in brackets, followed immediately by a colon and at least one space (e.g.,
[label]:
). - The URL for the link, which you can optionally enclose in angle brackets.
- The optional title for the link, which you can enclose in double quotes, single quotes, or parentheses.
This means the following example formats are all roughly equivalent for the second part of the link:
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle 'Hobbit lifestyles'
[1]: https://en.wikipedia.org/wiki/Hobbit#Lifestyle (Hobbit lifestyles)
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> 'Hobbit lifestyles'
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> 'Hobbit lifestyles'
[1]: <https://en.wikipedia.org/wiki/Hobbit#Lifestyle> (Hobbit lifestyles)
You can place this second part of the link anywhere in your Markdown document. Some people place them immediately after the paragraph in which they appear while other people place them at the end of the document (like endnotes or footnotes).
An Example Putting the Parts Together
Say you add a URL as a standard URL link to a paragraph and it looks like this in Markdown:
Though it may point to interesting additional information, the URL as displayed really doesn’t add much to the existing raw text other than making it harder to read. To fix that, you could format the URL like this instead:
In both instances above, the rendered output would be identical:
In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an oozy smell, nor yet a dry, bare, sandy hole with nothing in it to sit down on or to eat: it was a hobbit-hole, and that means comfort.
and the HTML for the link would be:
Link Best Practices
Markdown applications don’t agree on how to handle spaces in the middle of a URL. For compatibility, try to URL encode any spaces with
%20
.✅ Do this | ❌ Don't do this |
---|---|
[link](https://www.example.com/my%20great%20page) | [link](https://www.example.com/my great page) |
Images
To add an image, add an exclamation mark (
!
), followed by alt text in brackets, and the path or URL to the image asset in parentheses. You can optionally add a title after the URL in the parentheses.The rendered output looks like this:
Linking Images
To add a link to an image, enclose the Markdown for the image in brackets, and then add the link in parentheses.
The rendered output looks like this:
Escaping Characters
To display a literal character that would otherwise be used to format text in a Markdown document, add a backslash (
) in front of the character.The rendered output looks like this:
* Without the backslash, this would be a bullet in an unordered list.
Characters You Can Escape
You can use a backslash to escape the following characters.
Character | Name |
---|---|
backslash | |
` | backtick (see also escaping backticks in code) |
* | asterisk |
_ | underscore |
{ } | curly braces |
[ ] | brackets |
< > | angle brackets |
( ) | parentheses |
# | pound sign |
+ | plus sign |
- | minus sign (hyphen) |
. | dot |
! | exclamation mark |
| | pipe (see also escaping pipe in tables) |
HTML
Many Markdown applications allow you to use HTML tags in Markdown-formatted text. This is helpful if you prefer certain HTML tags to Markdown syntax. For example, some people find it easier to use HTML tags for images. Using HTML is also helpful when you need to change the attributes of an element, like specifying the color of text or changing the width of an image.
To use HTML, place the tags in the text of your Markdown-formatted file.
The rendered output looks like this:
This word is bold. This word is italic.
HTML Best Practices
For security reasons, not all Markdown applications support HTML in Markdown documents. When in doubt, check your Markdown application’s documentation. Some applications support only a subset of HTML tags.
Use blank lines to separate block-level HTML elements like
<div>
, <table>
, <pre>
, and <p>
from the surrounding content. Try not to indent the tags with tabs or spaces — that can interfere with the formatting.You can’t use Markdown syntax inside block-level HTML tags. For example,
<p>italic and **bold**</p>
won’t work.Take your Markdown skills to the next level.
Learn Markdown in 60 pages. Designed for both novices and experts, The Markdown Guide book is a comprehensive reference that has everything you need to get started and master Markdown syntax.
Get the BookWant to learn more Markdown?
Don't stop now! ? Star the GitHub repository and then enter your email address below to receive new Markdown tutorials via email. No spam!
The Gitiles source browser automatically renders
*.md
Markdown files into HTML for simplified documentation.Access controls
Access controls for documentation is identical to source code.
Documentation stored with source files shares the same permissions. Documentation stored in a separate Git repository can use different access controls. If Gerrit Code Review is being used, branch level read permissions can be used to grant or restrict access to any documentation branches.
READMEs
Jon heyman twitter. Files named
README.md
are automatically displayed below the file's directory listing. For the top level directory this mirrors the standard GitHub presentation.README.md files are meant to provide orientation for developers browsing the repository, especially first-time users.
We recommend that Git repositories have an up-to-date top-level
README.md
file.Markdown syntax
Gitiles supports the core Markdown syntax described in Markdown Basics. Additional extensions are supported to more closely match GitHub Flavored Markdown and simplify documentation writing.
Paragraphs
Paragraphs are one or more lines of consecutive text, followed by one or more blank lines. Line breaks within a paragraph are ignored by the parser, allowing authors to line-wrap text at any comfortable column width.
Headings
Headings can be indicated by starting the line with one or more
#
marks. The number of #
used determines the depth of the heading in the document outline. Headings 1 through 6 (######
) are supported.Headings can also use the less popular two line and
------
forms to create H1 and H2 level headers:This form is discouraged as maintaining the length of the or
---
lines to match the preceding line can be tedious work that is unnecessary with the #
headers.Lists
A bullet list:
will render into HTML as:
- Fruit
- Orange
- Pear
- Cake
The second level items (above Orange, Pear) must be indented with more spaces than the item they are nested under. Above 2 spaces were used. Additionally, the entire list must be preceded and followed by a blank line.
A numbered list:
will render into HTML as:
- Fruit
- Orange
- Pear
- Cake
List items will be renumbered sequentially by the browser, which is why
5
above displays as 2
. Even with this feature it is a good idea to maintain list item numbers in the source Markdown to simplify reading the source file.Like bullet lists, numbered lists can be nested by using more leading space than the prior list item. How to bring contacts from gmail to iphone 6.
Paragraphs can be properly nested within lists by indenting with at least 2 leading spaces:
Tables
Requires
markdown.tables
to be true (default).Simple tables are supported with column alignment. The first line is the header row and subsequent lines are data rows:
will render as:
Food | Calories | Tasty? |
---|---|---|
Apple | 95 | Yes |
Pear | 102 | Yes |
Hay | 977 |
Placing
:
in the separator line indicates how the column should be aligned. A colon on the left side is a left-aligned column; a colon on the right-most side is right-aligned; a colon on both sides is center-aligned. If no alignment is specified, the column is aligned with the default for HTML <td>
tags (left-aligned by default unless overridden by css).Empty table cells are indicated by whitespace between the column dividers (
| |
) while multiple column cells omit the whitespace.Emphasis
Emphasize paragraph text with italic and bold styles. Either
_
or *
can be used for italic (1 character) and bold text (2 characters). This allows styles to be mixed within a statement:It is strongly encouraged to review documentation for typos.
Emphasis within_words_is_ignored which helps write technical documentation. Literal *bold* can be forced by prefixing the opening
*
with such as *bold*
.Strikethrough
Requires
markdown.strikethrough
to be true (default).Text can be struck out within a paragraph:
Note two tildes are required (
~~
) on either side of the struck out section of text.Blockquotes
Blockquoted text can be used to stand off text obtained from another source:
renders as:
Sir Winston Churchill once said:
A lie gets halfway around the world before the truth has a chance to get its pants on.
Code (inline)
Use
backticks
to markup inline code within a paragraph:Code (blocks)
Create a fenced code block using three backticks before and after a block of code, preceeded and followed by blank lines:
Text within a fenced code block is taken verbatim and is not processed for Markdown markup.
Syntax highlighting can optionally be enabled for common languages by adding the language name in lowercase on the opening line. Supported languages include:
Web
- css
- dart
- html
- javascript, js
- json
Markup
- tex, latex
- wiki
- xml
- xquery
- xsl
- yaml
Other
- clj (Clojure)
- erlang
- hs (Haskell)
- lisp
- matlab
- ml (OCaml, SML, F#)
- r
- rust
- sql
- vhdl
Horizontal rules
If
markdown.ghthematicbreak
is true, a horizontal rule can be inserted using GitHub style --
surrounded by blank lines. Alternatively repeating -
or *
and space on a line will also create a horizontal rule:Links
Wrap text in
[brackets]
and the link destination in parens (http://..)
such as:Links can also use references to obtain URLs from elsewhere in the same document. This style can be useful if the same URL needs to be mentioned multiple times, is too long to cleanly place within text, or the link is within a table cell:
References can be simplified if the text alone is sufficient:
Automatic hyperlinking can be used where the link text should obviously also be the URL:
Well formed URLs beginning with
https://
, http://
, and mailto:
are used as written for the link's destination. Malformed URLs may be replaced with about:invalid#zSoyz
to prevent browser evaluation of dangerous content.HTML escaping of URL characters such as
&
is handled internally by the parser/formatter. Documentation writers should insert the URL literally and allow the parser and formatter to make it HTML safe.Relative links such as
./src/api.md
are resolved relative to the current markdown's file path within the Git repository. Absolute links such as /src/api.md
are resolved relative to the top of the enclosing Git repository, but within the same branch or Git commit. Links may point to any file in the repository. A link to a *.md
file will present the rendered markdown, while a link to a source file will display the syntax highlighted source.Named anchors
Explicit anchors can be inserted anywhere in the document using
<a name='tag'></a>
, or {#tag}
if markdown.namedanchor
is true.Implicit anchors are automatically created for each heading. For example
## Section 1
will have the anchor Section-1
.Anchor generation
- letters and digits, after removing accents (á → a)
- spaces are replaced with hyphens (
-
) - other characters are replaced with underscores (
_
) - runs of hyphens and underscores are collapsed
If a document contains the same named subsection under different parents the parent anchor will prefix the subsections to disambiguate. For example the following document will have anchors
Running-Format
and Coding-Format
and Libraries
as that subsection is unique:When placed in a section header the explicit anchor will override the automatic anchor. The following are identical and associate the anchor
live-examples
with the section header instead of the automaticly generated name Examples
.Images
Similar to links but begin with
!
to denote an image reference:For images the text in brackets will be included as the alt text for screen readers.
Well formed image URLs beginning with
https://
and http://
will be used as written for the <img src='..'>
attribute. Malformed URLs will be replaced with a broken data:
reference to prevent browsers from trying to load a bad destination.Relative and absolute links to image files within the Git repository (such as
./images/banner.png
) are resolved during rendering by inserting the base64 encoding of the image using a data:
URI. Only PNG (*.png
), JPEG (*.jpg
or *.jpeg
), GIF (*.gif
) and WebP (*.webp
) image formats are supported when referenced from the Git repository.Unsupported extensions or files larger than image size limit (default 256K) will display a broken image.
Inline image caching
Gitiles allows browsers to locally cache rendered markdown pages. Cache invalidation is triggered by the markdown file being modified and having a different SHA-1 in Git. Inlined images may need a documentation file update to be refreshed when viewed through unstable URLs like
/docs/+/master/index.md
.HTML
Most HTML tags are not supported. HTML will be dropped on the floor by the parser with no warnings, and no output from that section of the document.
If
markdown.safehtml
is true there are small exceptions for <br>
, <hr>
, <a name>
and <iframe>
elements, see named anchor and HTML IFrame.Markdown extensions
Gitiles includes additional extensions to the Markdown language that make documentation writing for the web easier without using raw HTML.
Table of contents
Requires
markdown.toc
to be true.Place
[TOC]
surrounded by blank lines to insert a generated table of contents extracted from the H1, H2, and H3 headers used within the document:H1 headers are omitted from the table of contents if there is only one level one header present. This allows H1 to be used as the document title without creating an unnecessary entry in the table of contents.
Anchors are automatically extracted from the headers, see named anchors.
Notification, aside, promotion blocks
Requires
markdown.blocknote
to be true.Similar to fenced code blocks these blocks start and end with
***
, are surrounded by blank lines, and include the type of block on the opening line.Note
Aside
An aside can stand off less interesting text.
Promo
Promotions can raise awareness of an important concept.
Column layout
Markdown H1n1 Pandemic
Requires
markdown.multicolumn
to be true.Gitiles markdown includes support for up to 12 columns of text across the width of the page. By default space is divided equally between the columns.
Prettify
the page layout.
A column layout is denoted by a block starting and ending with the sequence
|||---|||
. Within the layout a new column is started for each header or note/promo/aside block and all text and formatting flow into that column until a new column is started.Column spans can be specified on the first line as a comma separated list. In the example below the first column is 4 wide or 4/12ths of the page width, the second is 2 wide (or 2/12ths) and the final column is 6 wide (6/12ths or 50%) of the page.
An empty column can be inserted by prefixing its width with
:
, for example shifting content onto the right by padding 6 columns on the left:renders as:
Right
HTML IFrame
Requires
markdown.safehtml
to be true (default).Although HTML is stripped the parser has special support for a limited subset of
<iframe>
elements:The parser allows whitespace including newlines between attributes, but strictly limits the supported attribute set to:
src : An
https://
or http://
URL of the page to embed inside of an iframe at this position in the document. Malformed URLs will cause the iframe to be silently dropped. (required)height : CSS pixel height such as
250px
defining the amount of vertical space to give to the embedded content. Only px
units are supported; a malformed dimension will drop the iframe. (required)width : CSS pixel width such as
250px
or a precentage such as 80%
defining the amount of horizontal space to give to the embedded content. Only px
units or %
are supported; a malformed dimension will drop the iframe. (required)frameborder : By default a border is drawn around the iframe by the browser. The border can be hidden by adding
frameborder='0'
to the iframe tag. (optional)Embedded source URLs must also be whitelisted by the Gitiles
markdown.allowiframe
configuration variable.Discord Markdown H1
Site layout
Gitiles includes additional support to create functional documentation sites served directly from Git repositories.
Navigation bar
A top level navigation bar is automatically included on all pages if there is a
navbar.md
file present in the top of the repository. This file should be a simple bulleted list of links to include in the navigation bar.Links are resolved relative to the current page, not
navbar.md
. Links to other files within the repository should use absolute paths to ensure they are resolved correctly from any Markdown file within the repository.Site title
A site-wide banner is displayed on all Markdown pages if
navbar.md
includes an H1 header. The text of the header is displayed on the left side of the banner.Site logo
An optional logo image is displayed in the banner to the left of the site title if a
[logo]
reference exists in navbar.md
. This image should be no taller than 45 px.Markdown H1 Without Underline
See images above for acceptable URLs and how repository relative paths are handled by inline data URIs.
Markdown H1 2
Home link
Both the site logo (if present) and site title are wrapped in a link if the
[home]
reference is declared in navbar.md
. This is typically also used in the outline for the navigation bar:Page title
Titles for pages are extracted from the first H1 heading appearing in the document. This is traditionally placed on the first line of the markdown file, e.g.:
The title is included in the HTML
<title>
element and also in the right side of the banner if navbar.md
defines a site title.Configuration
The
gitiles.config
file supporting the site contains several configuration options that impact markdown rendering. Refer to the configuration documentation for details.