summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--docs/en/rst/using.rst14
-rw-r--r--template/en/default/bug/comment.html.tmpl1
-rw-r--r--template/en/default/pages/markdown.html.tmpl265
3 files changed, 270 insertions, 10 deletions
diff --git a/docs/en/rst/using.rst b/docs/en/rst/using.rst
index e54c34b2d..bdffb2cdb 100644
--- a/docs/en/rst/using.rst
+++ b/docs/en/rst/using.rst
@@ -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
diff --git a/template/en/default/bug/comment.html.tmpl b/template/en/default/bug/comment.html.tmpl
index 7feb6dfa4..b748b71fd 100644
--- a/template/en/default/bug/comment.html.tmpl
+++ b/template/en/default/bug/comment.html.tmpl
@@ -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 %]
diff --git a/template/en/default/pages/markdown.html.tmpl b/template/en/default/pages/markdown.html.tmpl
new file mode 100644
index 000000000..b1da19684
--- /dev/null
+++ b/template/en/default/pages/markdown.html.tmpl
@@ -0,0 +1,265 @@
+[%# 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 %]