Skip to content

bugzilla
bugzilla
Commit d416aabc authored by Koosha KM's avatar Koosha KM Committed by David Lawrence
Browse files
Options

Bug 1059685: Add user help for Markdown

r=dkl,a=sgreen
parent 1488a589
Hide whitespace changes
Inline Side-by-side
Showing with 270 additions and 10 deletions
docs/en/rst/using.rst
View file @ d416aabc
......@@ -404,7 +404,7 @@ You can use it to find a bug by its number or its alias, too.
You'll find the Quicksearch box in Bugzilla's footer area.
On Bugzilla's front page, there is an additional
`Help <../../page.cgi?id=quicksearch.html>`_
`quicksearcgh help <../../../page.cgi?id=quicksearch.html>`_
link which details how to use it.
.. _casesensitivity:
......@@ -798,15 +798,9 @@ Markdown lets you write your comments in a structured plain-text format and
have your comments generated as HTML. For example, you may use Markdown for
making a part of your comment look italic or bold in the generated HTML. Bugzilla
supports most of the structures defined by `standard Markdown <http://daringfireball.net/projects/markdown/basics>`_.
but does NOT support inline images and inline HTML.
Additionally, three Github Flavored Markdown features are supported.
- `Multiple underscores in words <https://help.github.com/articles/github-flavored-markdown#multiple-underscores-in-words>`_
- `strikethrough <https://help.github.com/articles/github-flavored-markdown#strikethrough>`_
- `fenced code blocks <https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks>`_
but does NOT support inline images and inline HTML. For a complete reference on
supported Markdown structures, please see the `syntax help <../../../page.cgi?id=markdown.html>`_
link next to the markdown checkbox for new comments.
To use the Markdown feature, make sure that ``Enable Markdown support for comments`` is set to ``on``
in your :ref:`userpreferences` and that you also check the ``Use Markdown for this comment`` option below
......
template/en/default/bug/comment.html.tmpl
View file @ d416aabc
......@@ -41,5 +41,6 @@
<input type="checkbox" name="use_markdown" id="use_markdown" value="1"
[% "checked=\"checked\"" IF user.settings.use_markdown.value == 'on' %] >
<label id="use_markdown_label" for="use_markdown">Use Markdown for this [% terms.comment %]</label>
(<a href="page.cgi?id=markdown.html" target="_blank" title="View Markdown Syntax Guide">help</a>)
</div>
[% END %]
template/en/default/pages/markdown.html.tmpl 0 → 100644
View file @ d416aabc
[%# this source code form is subject to the terms of the mozilla public
# license, v. 2.0. if a copy of the mpl was not distributed with this
# file, you can obtain one at http://mozilla.org/mpl/2.0/.
#
# this source code form is "incompatible with secondary licenses", as
# defined by the mozilla public license, v. 2.0.
#%]
[% INCLUDE global/header.html.tmpl
title = "Markdown Syntax Guide"
bodyclasses = ['narrow_page']
%]
<h2>What is Markdown?</h2>
Markdown is a simple text formatting language that enables you to write your
[%+ terms.comments %] in plain-text and have them generated as HTML. Markdown
in [%+ terms.Bugzilla %] supports the following structures:
<ul>
<li><a href="#headers">Headers</a></li>
<li><a href="#blockquotes">Blockquotes</a></li>
<li><a href="#emphasis">Emphasis</a></li>
<li><a href="#lists">Lists</a></li>
<li><a href="#code">Code</a></li>
<li><a href="#strikethroughs">Strikethroughs</a></li>
<li><a href="#links">Links</a></li>
</ul>
<h2 id="headers">Headers</h2>
You have two options for making headers. First, you may use any number of
equal signs (for first-level header) or dashes (for second-level headers).
<p>
<pre>
<code>
This is an H1 header
====================
This is an H2 header
--------------------
</code>
</pre>
</p>
Second, you can use hash signs at the beginning of the line to specify the
level of the header from 1 to 6.
<p>
<pre>
<code>
# This is the largest header (H1 level)
### This is a small header (H3 level)
###### This is the smallest header (H6 level)
</code>
</pre>
</p>
<h2 id="blockquotes">Blockquotes</h2>
Use a closing angle bracket (<code>&gt;</code>) at the beginning of the line
to indicate a line as quoted.
<p>
<pre>
<code>
&gt; Some text to be quoted.
</code>
</pre>
</p>
<h2 id="emphasis">Emphasis</h2>
Single underscores or asterisks will make the text italic. Double underscores
or asterisks will make the text bold.
<p>
<pre>
<code>
_This text will become italic_
*This text also will become italic*
__But this one will be bold__
**And this one as well**
</code>
</pre>
</p>
Turns into
<p>
<pre>
<em>This text will become italic</em>
<em>This text also will become italic</em>
<br>
<strong>But this one will be bold</strong>
<strong>And this one as well</strong>
</pre>
</p>
Use different signs to combine them nestedly in order to avoid ambiguity:
<p>
<pre>
<code>
_This [% terms.bug %] **must** be resolved ASAP._
</code>
</pre>
</p>
<strong>Note:</strong> [% terms.Bugzilla %] will skip emphasizing words that
have the form of <code>multiple_underscore_in_a_word</code>. This measure is
taken to not emphasize words that are possible programming variables. If your
word has this form and you still want it to become emphasized/bold, you must
use single/double asterisks (<code>*</code>) instead of underscores
(<code>_</code>).
<h2 id="lists">Lists</h2>
Markdown supports both unordered and ordered lists.
<h3>Unordered Lists</h3>
Use asterisks (<code>*</code>), pluses (<code>+</code>) or hyphens
(<code>-</code>) to mark the items of an unordered list.
<p>
<pre>
<code>
+ First item
+ Second item
+ Third item
</code>
</pre>
</p>
<h3>Ordered Lists</h3>
Use a number followed by a period to denote an item of an ordered list.
<p>
<pre>
<code>
1. Item one
4. Item two
3. Item three
</code>
</pre>
</p>
<strong>Note:</strong> Your numbers have no effect on the rendered item
numbers and the rendered numbers are automatically generated. Your numbers
are only used to specify the items of an ordered list.<br>
<p>
A list item can have nested lists recursively:
</p>
<p>
<pre>
<code>
1. Item one
4. Item two
3. Item three
* First sub-item
* Second sub-item
5. Item four
</code>
</pre>
</p>
<h2 id="code">Code</h2>
To make a part of your text to get generated as a piece of code, use one or
more backticks (<code>`</code>) and close that
part with the same number of backticks.
<p>
<pre>
<code>Please see the manual for `printf` function.</code>
</pre>
</p>
If you want to make some lines of code, you need to use 3 or more backticks at
the beginning of a line followed by your code lines and concluded by 3 or more
backticks.
<p>
<pre>
<code>
See my function:
```
int sum(int x, int y) {
return x + y;
}
```
</code>
</pre>
</p>
You can also use a tab or [% constants.MARKDOWN_TAB_WIDTH %] or more spaces at
the beginning of each line of your code to make the whole block look as a code
block. Please take care that you might make your lines as code blocks by
inadvertently indenting them.
<h2 id="strikethroughs">Strikethroughs</h2>
Surround your text between a pair of two tildes to have your text crossed out.
<p>
<pre>
<code>
Module ~~Foo~~ is deprecated.
</code>
</pre>
</p>
<h2 id="links">Links</h2>
Literal URLs and Email addresses get linkified automatically. Besides that,
you can define links with link texts and titles. You may define your links
either as inline or as a reference. To define a link as inline, put your link
text in square bracket immediately followed by a pair of parentheses which
containts the URL that you want your link to point to and an <em>optional</em>
link title surrounded by quotes.
<p>
<pre>
<code>
This is [Bugzilla](http://www.bugzilla.org "View Bugzilla Homepage")
[% terms.bug %] tracking system.</code>
This [example link](http://www.example.com) does not have title.
</code>
</pre>
</p>
To define your links in a reference style, define your links any where in
your [% terms.comment %] with the following format:
<p>
<pre>
<code>
[bz]: http://www.bugzilla.org "Bugzilla Homepage"
[mz]: http://www.mozilla.org (Mozilla Homepage)
</code>
</pre>
</p>
That is, define a unique ID for each link in square brackets with their
corresponding URL and optional title in quotes or parentheses. Then, point to
those links simply by writing your link text in square brackets followed by
the ID in another pair of square brackets.
<p>
<pre>
<code>
[Bugzilla][bz] is open-sourced server software designed to help groups
manage software development. [Mozilla][mz] uses [Bugzilla][bz] to track
issues with Firefox and other projects.
</code>
</pre>
</p>
[% PROCESS global/footer.html.tmpl %]
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment