1
0

markdown.rst 7.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270
  1. Using Markdown in Pagure
  2. ========================
  3. Pagure uses `Markdown syntax highlighting
  4. <https://daringfireball.net/projects/markdown/syntax>`_ as the base for
  5. formatting comments in issues, pull requests, and in Markdown files in
  6. repositories. For basic formatting, Pagure follows common Markdown
  7. formatting, but it also has some unique syntax for more advanced
  8. formatting. This help page helps demonstrate how to use Markdown in Pagure.
  9. Pagure relies on the `Markdown <https://python-markdown.github.io/>`_ python
  10. module to do the conversion.
  11. It has enabled a few extensions:
  12. - `Definition Lists <https://python-markdown.github.io/extensions/definition_lists/>`_
  13. - `Fenced Code Blocks <https://python-markdown.github.io/extensions/fenced_code_blocks/>`_
  14. - `Tables <https://python-markdown.github.io/extensions/tables/>`_
  15. - `Smart Strong <https://python-markdown.github.io/extensions/smart_strong/>`_
  16. - `Admonition <https://python-markdown.github.io/extensions/admonition/>`_
  17. - `CodeHilite <https://python-markdown.github.io/extensions/code_hilite/>`_
  18. - `Sane lists <https://python-markdown.github.io/extensions/sane_lists/>`_
  19. README files can also rely on:
  20. - `Abbreviations <https://python-markdown.github.io/extensions/abbreviations/>`_
  21. - `Footnotes <https://python-markdown.github.io/extensions/footnotes/>`_
  22. - `Table of Contents <https://python-markdown.github.io/extensions/toc/>`_
  23. While comments use:
  24. - `New Line to Break <https://python-markdown.github.io/extensions/nl2br/>`_
  25. .. warning:: Pagure does not support linking to remote images, if you want
  26. to link to an image on a ticket, you will have to upload it to pagure.
  27. Styling
  28. -------
  29. .. role:: strike
  30. :class: strike
  31. You can mark up text with bold, italics, or strikethrough.
  32. * **Style**: Bold
  33. * Syntax: `** **` or `__ __`
  34. * Example: `**This is bold text**`
  35. * Output: **This is bold text**
  36. * **Style**: Italics
  37. * Syntax: `* *` or `_ _`
  38. * Example: `_This is italicized text_`
  39. * Output: *This is italicized text*
  40. * **Style**: Strikethrough
  41. * Syntax: `~~ ~~`
  42. * Example: `~~This text is no longer relevant~~`
  43. * Output: :strike:`This text is no longer relevant`
  44. * **Style**: Bold and italics
  45. * Syntax: `** **` and `_ _`
  46. * Example: `** This text is the _most important thing ever_ **`
  47. * Output: ** This text is the *most important thing ever* **
  48. Quoting
  49. -------
  50. You can show text as being quoted with the `>` character.
  51. ::
  52. Before merging this pull request, remember Clark Kent mentioned this:
  53. > Double-check there's no reference to the Kryptonite library in the program since we removed that a few versions ago.
  54. Before merging this pull request, remember Clark Kent mentioned this:
  55. Double-check there's no reference to the Kryptonite library in the program since we removed that a few versions ago.
  56. You can also make a line-wrapping blockquote using <br/>.
  57. ::
  58. Remember what Solomon said:
  59. > I don't want to survive. <br/> I want to live.
  60. Remember what Solomon said:
  61. I don't want to survive.
  62. I want to live.
  63. For more details regarding Blockquote, refer
  64. `Blockquote <https://daringfireball.net/projects/markdown/syntax#blockquote>`_.
  65. Code
  66. ----
  67. You can highlight parts of a line as code or create entire code blocks in
  68. your Markdown documents. You can do this with the backtick character (`).
  69. Text inside of backticks will not be formatted.
  70. ::
  71. When running the program for the first time, use `superman --initialize`.
  72. When running the program for the first time, use ``superman --initialize``.
  73. To format multiple lines of code into its own block, you can wrap the text
  74. block with four tilde (~) characters
  75. ::
  76. Install the needed system libraries:
  77. `~~~~`
  78. sudo dnf install git python-virtualenv libgit2-devel \
  79. libjpeg-devel gcc libffi-devel redhat-rpm-config
  80. `~~~~`
  81. Install the needed system libraries:
  82. ::
  83. sudo dnf install git python-virtualenv libgit2-devel \
  84. libjpeg-devel gcc libffi-devel redhat-rpm-config
  85. Hyperlinks
  86. ----------
  87. Regular links
  88. ^^^^^^^^^^^^^
  89. Need to embed a link to somewhere else? No problem! You can create an
  90. in-line link by wrapping the text in `[ ]` and appending the URL in
  91. parentheses `( )` immediately after.
  92. `Pagure is used by the [Fedora Project](https://fedoraproject.org).`
  93. Pagure is used by the `Fedora Project <https://fedoraproject.org>`_.
  94. Links to ticket/PR of the same project
  95. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  96. You want to link to a ticket or a pull-request in the current project? Easy
  97. just use `#` immediately followed by the identifier of the ticket or
  98. pull-request.
  99. `This is an example for #2921`
  100. This is an example for `#2921 <https://pagure.io/pagure/issue/2921>`_
  101. Links to ticket/PR of another project
  102. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  103. You want to link to a ticket or a pull-request of a different project? Simply
  104. add the project name in front of the `#` and immediately followed by the
  105. identifier of the ticket or pull-request.
  106. `This is an example for pagure#2921`
  107. This is an example for `pagure#2921 <https://pagure.io/pagure/issue/2921>`_
  108. Lists
  109. -----
  110. Unordered lists
  111. ^^^^^^^^^^^^^^^
  112. You can make unordered lists spanning multiple lines with either `-` or `*`.
  113. ::
  114. * Superman
  115. * Batman
  116. * Protector of Gotham City!
  117. * Superwoman
  118. * Harley Quinn
  119. * Something on this list is unlike the others...
  120. * Superman
  121. * Batman
  122. * Protector of Gotham City!
  123. * Superwoman
  124. * Harley Quinn
  125. * Something on this list is unlike the others...
  126. Ordered lists
  127. ^^^^^^^^^^^^^
  128. You can make ordered lists by preceding each line with a number.
  129. ::
  130. 1. Superman
  131. 2. Batman
  132. 1. Protector of Gotham City!
  133. 2. He drives the Batmobile!
  134. 3. Superwoman
  135. 4. Harley Quinn
  136. 1. Something on this list is unlike the others...
  137. 2. Somebody evil lurks on this list!
  138. 1. Superman
  139. 2. Batman
  140. 1. Protector of Gotham City!
  141. 2. He drives the Batmobile!
  142. 3. Superwoman
  143. 4. Harley Quinn
  144. 1. Something on this list is unlike the others...
  145. 2. Somebody evil lurks on this list!
  146. Tagging users
  147. -------------
  148. You can tag other users on Pagure to send them a notification about an issue
  149. or pull request. To tag a user, use the `@` symbol followed by their username.
  150. Typing the `@` symbol in a comment will bring up a list of users that match
  151. the username. The list searches as you type. Once you see the name of the
  152. person you are looking for, you can click their name to automatically
  153. complete the tag.
  154. `@jflory7, could you please review this pull request and leave feedback?`
  155. `@jflory7 <https://pagure.io/user/jflory7>`_, could you please review this pull request and leave feedback?
  156. Tagging issues or pull requests
  157. -------------------------------
  158. In a comment, you can automatically link a pull request or issue by its number.
  159. To link it, use the `#` character followed by its number. Like with tagging
  160. users, Pagure will provide suggestions for issues or pull requests as you
  161. type the number. You can select the issue in the drop-down to automatically
  162. tag the issue or pull request.
  163. If you need to tag an issue or pull request that is outside of the current
  164. project, you are also able to do this. For cross-projects links, you can tag
  165. them by typing `<project name>#id` or `<username>/<project name>#id`.
  166. Emoji
  167. -----
  168. Pagure natively supports emoji characters. To use emoji, you can use two
  169. colons wrapped around the emoji keyword (`:emoji:`). Typing a colon by itself
  170. will bring up a list of suggested emoji with a small preview. If you see the
  171. one you are looking for, you can click it to automatically complete the emoji.
  172. `I reviewed the PR and it looks good to me. :+1: Good to merge! :clapper:`
  173. I reviewed the PR and it looks good to me. 👍 Good to merge! 🎬
  174. Improve this documentation!
  175. ---------------------------
  176. Notice anything that can be improved in this documentation? Find a mistake?
  177. You can improve this page! Find it in the official
  178. `Pagure repository <https://pagure.io/pagure/blob/master/f/doc/usage/markdown.rst>`_.