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 dc5821
Pagure relies on the `Markdown <https: python-markdown.github.io="">`_ python</https:>
René Genz ec0022
module to do the conversion.
Pierre-Yves Chibon 87b023
It has enabled a few extensions:
Pierre-Yves Chibon 95f0c1
René Genz ec0022
- `Definition Lists <https: definition_lists="" extensions="" python-markdown.github.io="">`_</https:>
René Genz ec0022
- `Fenced Code Blocks <https: extensions="" fenced_code_blocks="" python-markdown.github.io="">`_</https:>
René Genz ec0022
- `Tables <https: extensions="" python-markdown.github.io="" tables="">`_</https:>
René Genz ec0022
- `Smart Strong <https: extensions="" python-markdown.github.io="" smart_strong="">`_</https:>
René Genz ec0022
- `Admonition <https: admonition="" extensions="" python-markdown.github.io="">`_</https:>
René Genz ec0022
- `CodeHilite <https: code_hilite="" extensions="" python-markdown.github.io="">`_</https:>
René Genz ec0022
- `Sane lists <https: extensions="" python-markdown.github.io="" sane_lists="">`_</https:>
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 87b023
README files can also rely on:
Pierre-Yves Chibon 95f0c1
René Genz ec0022
- `Abbreviations <https: abbreviations="" extensions="" python-markdown.github.io="">`_</https:>
René Genz ec0022
- `Footnotes <https: extensions="" footnotes="" python-markdown.github.io="">`_</https:>
René Genz ec0022
- `Table of Contents <https: extensions="" python-markdown.github.io="" toc="">`_</https:>
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 87b023
While comments use:
Pierre-Yves Chibon 95f0c1
René Genz ec0022
- `New Line to Break <https: extensions="" nl2br="" python-markdown.github.io="">`_</https:>
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon 95f0c1
Pierre-Yves Chibon e6d05d
.. warning:: Pagure does not support linking to remote images, if you want
Pierre-Yves Chibon e6d05d
    to link to an image on a ticket, you will have to upload it to pagure.
Pierre-Yves Chibon e6d05d
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 ef6d3a
Regular links
Pierre-Yves Chibon ef6d3a
^^^^^^^^^^^^^
Pierre-Yves Chibon ef6d3a
Pierre-Yves Chibon 95f0c1
Need to embed a link to somewhere else? No problem! You can create an
Pierre-Yves Chibon ec70f0
in-line link by wrapping the text in `[ ]` and appending 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 ef6d3a
Links to ticket/PR of the same project
Pierre-Yves Chibon ef6d3a
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pierre-Yves Chibon ef6d3a
Pierre-Yves Chibon ef6d3a
You want to link to a ticket or a pull-request in the current project? Easy
Pierre-Yves Chibon ef6d3a
just use `#` immediately followed by the identifier of the ticket or
Pierre-Yves Chibon ef6d3a
pull-request.
Pierre-Yves Chibon ef6d3a
Pierre-Yves Chibon ef6d3a
`This is an example for #2921`
Pierre-Yves Chibon ef6d3a
Pierre-Yves Chibon ef6d3a
This is an example for `#2921 <https: 2921="" issue="" pagure="" pagure.io="">`_</https:>
Pierre-Yves Chibon ef6d3a
Pierre-Yves Chibon ef6d3a
Links to ticket/PR of another project
Pierre-Yves Chibon ef6d3a
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Pierre-Yves Chibon ef6d3a
Pierre-Yves Chibon ef6d3a
You want to link to a ticket or a pull-request of a different project? Simply
Pierre-Yves Chibon ef6d3a
add the project name in front of the `#` and immediately followed by the
Pierre-Yves Chibon ef6d3a
identifier of the ticket or pull-request.
Pierre-Yves Chibon ef6d3a
Pierre-Yves Chibon ef6d3a
`This is an example for pagure#2921`
Pierre-Yves Chibon ef6d3a
Pierre-Yves Chibon ef6d3a
This is an example for `pagure#2921 <https: 2921="" issue="" pagure="" pagure.io="">`_</https:>
Pierre-Yves Chibon ef6d3a
Pierre-Yves Chibon ef6d3a
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
René Genz ec0022
one you are 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
Till Hofmann caada5
`Pagure repository <https: blob="" doc="" f="" markdown.rst="" master="" pagure="" pagure.io="" usage="">`_.</https:>