Blame doc/usage/markdown.rst

Pierre-Yves Chibon 95f0c1
Using Markdown in Pagure
Pierre-Yves Chibon 95f0c1
========================
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pagure uses `Markdown syntax highlighting
Pierre-Yves Chibon 95f0c1
<https: daringfireball.net="" markdown="" projects="" syntax="">`_ as the base for</https:>
Pierre-Yves Chibon 95f0c1
formatting comments in issues, pull requests, and in Markdown files in
Pierre-Yves Chibon 95f0c1
repositories. For basic formatting, Pagure follows common Markdown
Pierre-Yves Chibon 95f0c1
formatting, but it also has some unique syntax for more advanced
Pierre-Yves Chibon 95f0c1
formatting. This help page helps demonstrate how to use Markdown in Pagure.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 87b023
Pagure relies on the `Markdown <http: markdown="" pythonhosted.org="">`_ python</http:>
Pierre-Yves Chibon 87b023
module to do the convertion.
Pierre-Yves Chibon 87b023
It has enabled a few extensions:
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 87b023
- `Definition Lists <http: definition_lists.html="" extensions="" markdown="" pythonhosted.org="">`_</http:>
Pierre-Yves Chibon 87b023
- `Fenced Code Blocks <http: extensions="" fenced_code_blocks.html="" markdown="" pythonhosted.org="">`_</http:>
Pierre-Yves Chibon 87b023
- `Tables <http: extensions="" markdown="" pythonhosted.org="" tables.html="">`_</http:>
Pierre-Yves Chibon 87b023
- `Smart Strong <http: extensions="" markdown="" pythonhosted.org="" smart_strong.html="">`_</http:>
Pierre-Yves Chibon 87b023
- `Admonition <http: admonition.html="" extensions="" markdown="" pythonhosted.org="">`_</http:>
Pierre-Yves Chibon 87b023
- `CodeHilite <http: code_hilite.html="" extensions="" markdown="" pythonhosted.org="">`_</http:>
Pierre-Yves Chibon 87b023
- `Sane lists <http: extensions="" markdown="" pythonhosted.org="" sane_lists.html="">`_</http:>
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 87b023
README files can also rely on:
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 87b023
- `Abbreviations <http: abbreviations.html="" extensions="" markdown="" pythonhosted.org="">`_</http:>
Pierre-Yves Chibon 87b023
- `Foonotes <http: extensions="" footnotes.html="" markdown="" pythonhosted.org="">`_</http:>
Pierre-Yves Chibon 87b023
- `Table of Contents <http: extensions="" markdown="" pythonhosted.org="" toc.html="">`_</http:>
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 87b023
While comments use:
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 87b023
- `New Line to Break <http: extensions="" markdown="" nl2br.html="" pythonhosted.org="">`_</http:>
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Styling
Pierre-Yves Chibon 95f0c1
-------
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
..  role:: strike
Pierre-Yves Chibon 95f0c1
     :class: strike
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
You can mark up text with bold, italics, or strikethrough.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
* **Style**: Bold
Pierre-Yves Chibon 95f0c1
    * Syntax: `** **` or `__ __`
Pierre-Yves Chibon 95f0c1
    * Example: `**This is bold text**`
Pierre-Yves Chibon 95f0c1
    * Output: **This is bold text**
Pierre-Yves Chibon 95f0c1
* **Style**: Italics
Pierre-Yves Chibon 95f0c1
    * Syntax: `* *` or `_ _`
Pierre-Yves Chibon 95f0c1
    * Example: `_This is italicized text_`
Pierre-Yves Chibon 95f0c1
    * Output: *This is italicized text*
Pierre-Yves Chibon 95f0c1
* **Style**: Strikethrough
Pierre-Yves Chibon 95f0c1
    * Syntax: `~~ ~~`
Pierre-Yves Chibon 95f0c1
    * Example: `~~This text is no longer relevant~~`
Pierre-Yves Chibon 95f0c1
    * Output: :strike:`This text is no longer relevant`
Pierre-Yves Chibon 95f0c1
* **Style**: Bold and italics
Pierre-Yves Chibon 95f0c1
    * Syntax: `** **` and `_ _`
Pierre-Yves Chibon 95f0c1
    * Example: `** This text is the _most important thing ever_ **`
Pierre-Yves Chibon 95f0c1
    * Output: ** This text is the *most important thing ever* **
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Quoting
Pierre-Yves Chibon 95f0c1
-------
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
You can show text as being quoted with the `>` character.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
::
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
    Before merging this pull request, remember Clark Kent mentioned this:
Pierre-Yves Chibon 95f0c1
    > Double-check there's no reference to the Kryptonite library in the program since we removed that a few versions ago.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Before merging this pull request, remember Clark Kent mentioned this:
Pierre-Yves Chibon 95f0c1
> Double-check there's no reference to the Kryptonite library in the program since we removed that a few versions ago.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Code
Pierre-Yves Chibon 95f0c1
----
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
You can highlight parts of a line as code or create entire code blocks in
Pierre-Yves Chibon 95f0c1
your Markdown documents. You can do this with the backtick character (`).
Pierre-Yves Chibon 95f0c1
Text inside of backticks will not be formatted.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
::
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
    When running the program for the first time, use `superman --initialize`.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
When running the program for the first time, use ``superman --initialize``.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
To format multiple lines of code into its own block, you can wrap the text
Pierre-Yves Chibon 95f0c1
block with four tilde (~) characters
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
::
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
    Install the needed system libraries:
Pierre-Yves Chibon 95f0c1
    `~~~~`
Pierre-Yves Chibon 95f0c1
    sudo dnf install git python-virtualenv libgit2-devel \
Pierre-Yves Chibon 95f0c1
                    libjpeg-devel gcc libffi-devel redhat-rpm-config
Pierre-Yves Chibon 95f0c1
    `~~~~`
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Install the needed system libraries:
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
::
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
    sudo dnf install git python-virtualenv libgit2-devel \
Pierre-Yves Chibon 95f0c1
                 libjpeg-devel gcc libffi-devel redhat-rpm-config
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Hyperlinks
Pierre-Yves Chibon 95f0c1
----------
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Need to embed a link to somewhere else? No problem! You can create an
Pierre-Yves Chibon 95f0c1
in-line link by wrapping the text in `[ ]` and appending the the URL in
Pierre-Yves Chibon 95f0c1
parentheses `( )` immediately after.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
`Pagure is used by the [Fedora Project](https://fedoraproject.org).`
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pagure is used by the `Fedora Project <https: fedoraproject.org="">`_.</https:>
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Lists
Pierre-Yves Chibon 95f0c1
-----
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Unordered lists
Pierre-Yves Chibon 95f0c1
^^^^^^^^^^^^^^^
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
You can make unordered lists spanning multiple lines with either `-` or `*`.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
::
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
    * Superman
Pierre-Yves Chibon 95f0c1
    * Batman
Pierre-Yves Chibon 95f0c1
        * Protector of Gotham City!
Pierre-Yves Chibon 95f0c1
    * Superwoman
Pierre-Yves Chibon 95f0c1
    * Harley Quinn
Pierre-Yves Chibon 95f0c1
        * Something on this list is unlike the others...
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
* Superman
Pierre-Yves Chibon 95f0c1
* Batman
Pierre-Yves Chibon 95f0c1
    * Protector of Gotham City!
Pierre-Yves Chibon 95f0c1
* Superwoman
Pierre-Yves Chibon 95f0c1
* Harley Quinn
Pierre-Yves Chibon 95f0c1
    * Something on this list is unlike the others...
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Ordered lists
Pierre-Yves Chibon 95f0c1
^^^^^^^^^^^^^
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
You can make ordered lists by preceding each line with a number.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
::
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
    1. Superman
Pierre-Yves Chibon 95f0c1
    2. Batman
Pierre-Yves Chibon 95f0c1
        1. Protector of Gotham City!
Pierre-Yves Chibon 95f0c1
        2. He drives the Batmobile!
Pierre-Yves Chibon 95f0c1
    3. Superwoman
Pierre-Yves Chibon 95f0c1
    4. Harley Quinn
Pierre-Yves Chibon 95f0c1
        1. Something on this list is unlike the others...
Pierre-Yves Chibon 95f0c1
        2. Somebody evil lurks on this list!
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
1. Superman
Pierre-Yves Chibon 95f0c1
2. Batman
Pierre-Yves Chibon 95f0c1
    1. Protector of Gotham City!
Pierre-Yves Chibon 95f0c1
    2. He drives the Batmobile!
Pierre-Yves Chibon 95f0c1
3. Superwoman
Pierre-Yves Chibon 95f0c1
4. Harley Quinn
Pierre-Yves Chibon 95f0c1
    1. Something on this list is unlike the others...
Pierre-Yves Chibon 95f0c1
    2. Somebody evil lurks on this list!
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Tagging users
Pierre-Yves Chibon 95f0c1
-------------
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
You can tag other users on Pagure to send them a notification about an issue
Pierre-Yves Chibon 95f0c1
or pull request. To tag a user, use the `@` symbol followed by their username.
Pierre-Yves Chibon 95f0c1
Typing the `@` symbol in a comment will bring up a list of users that match
Pierre-Yves Chibon 95f0c1
the username. The list searches as you type. Once you see the name of the
Pierre-Yves Chibon 95f0c1
person you are looking for, you can click their name to automatically
Pierre-Yves Chibon 95f0c1
complete the tag.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
`@jflory7, could you please review this pull request and leave feedback?`
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
`@jflory7 <https: jflory7="" pagure.io="" user="">`_, could you please review this pull request and leave feedback?</https:>
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Tagging issues or pull requests
Pierre-Yves Chibon 95f0c1
-------------------------------
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
In a comment, you can automatically link a pull request or issue by its number.
Pierre-Yves Chibon 95f0c1
To link it, use the `#` character followed by its number. Like with tagging
Pierre-Yves Chibon 95f0c1
users, Pagure will provide suggestions for issues or pull requests as you
Pierre-Yves Chibon 95f0c1
type the number. You can select the issue in the drop-down to automatically
Pierre-Yves Chibon 95f0c1
tag the issue or pull request.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
If you need to tag an issue or pull request that is outside of the current
Pierre-Yves Chibon 95f0c1
project, you are also able to do this. For cross-projects links, you can tag
Pierre-Yves Chibon 95f0c1
them by typing `<project name="">#id` or `<username>/<project name="">#id`.</project></username></project>
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Emoji
Pierre-Yves Chibon 95f0c1
-----
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pagure natively supports emoji characters. To use emoji, you can use two
Pierre-Yves Chibon 95f0c1
colons wrapped around the emoji keyword (`:emoji:`). Typing a colon by itself
Pierre-Yves Chibon 95f0c1
will bring up a list of suggested emoji with a small preview. If you see the
Pierre-Yves Chibon 95f0c1
one you're looking for, you can click it to automatically complete the emoji.
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
`I reviewed the PR and it looks good to me. :+1: Good to merge! :clapper:`
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
I reviewed the PR and it looks good to me. 👍 Good to merge! 🎬
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Improve this documentation!
Pierre-Yves Chibon 95f0c1
---------------------------
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Notice anything that can be improved in this documentation? Find a mistake?
Pierre-Yves Chibon 95f0c1
You can improve this page! Find it in the official
Pierre-Yves Chibon 95f0c1
`Pagure repository <https: blob="" doc="" f="" markdown.md="" master="" pagure="" pagure.io="" usage="">`_.</https:>