1
0

theming.rst 6.4 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207
  1. Theming Guide
  2. =============
  3. Pagure is built on Flask, and uses Jinja2 for templates. Pagure also
  4. includes the ability to apply different themes that control the look
  5. and feel of your pagure instance, or add or remove elements from the
  6. interface.
  7. Setting a theme
  8. ---------------
  9. The theme is set in the Pagure configuration file. The theme name is defined by
  10. the name of the directory in the /themes/ folder that contains the theme. For
  11. example to enable the theme that is used on Pagure.io, add the following line
  12. to your Pagure configuration:
  13. ::
  14. THEME = "pagureio"
  15. Theme contents
  16. --------------
  17. A theme requires two directories (`templates` and `static`) in the directory
  18. that contains the theme. The only other required file is theme.html which
  19. is placed in the templates directory
  20. templates/
  21. ~~~~~~~~~~
  22. The `templates` directory is where pagure will look for the `theme.html`
  23. template. Additionally, if you wish to override any template in Pagure,
  24. place it in the theme templates/ directory, and pagure will use that
  25. template rather than the standard one.
  26. .. warning:: Take care when overriding templates, as any changes to Pagure
  27. upstream will need to be backported to your theme template override.
  28. static/
  29. ~~~~~~~
  30. The `static` directory contains all the static elements for the theme,
  31. including additional a favicon, images, Javascript, and CSS files. To
  32. reference a file in the theme static directory use the jinja2 tag
  33. `{{ url_for('theme.static', filename='filename')}}`. For example:
  34. ::
  35. <link href="{{ url_for('theme.static', filename='theme.css') }}"
  36. rel="stylesheet" type="text/css" />
  37. templates/theme.html
  38. ~~~~~~~~~~~~~~~~~~~~
  39. The theme.html file defines a subset of items in the Pagure interface that
  40. are commonly changed when creating a new theme. Theming is a new feature in
  41. Pagure, so this set is currently small, but please file issues or PRs against
  42. pagure with ideas of new items to include.
  43. The current items configurable in theme.html are:
  44. `masthead_class` variable
  45. #########################
  46. A string of additional CSS class(es) to be added to the navbar element.
  47. This navbar element is the topbar in Pagure. For example:
  48. ::
  49. {% set masthead_class = "navbar-dark bg-dark" %}
  50. `site_title` variable
  51. #####################
  52. A string containing the text to append at the end of the html title
  53. on every page on the site. Usage:
  54. ::
  55. {% set site_title = "Pagure" %}
  56. `projectstring(Bool:plural)` macro
  57. ##################################
  58. A macro that returns a string used to refer to Projects in Pagure
  59. The plural parameter informs if the string to be returned is the
  60. plural form.
  61. This macro is optional.
  62. Usage:
  63. ::
  64. {% macro projectstring(plural=False) -%}
  65. {% if plural %}
  66. Repositories
  67. {% else %}
  68. Repository
  69. {% endif %}
  70. {% endmacro -%}
  71. `projecticon` variable
  72. ######################
  73. A string containing the name of the fontawesome icon to use for
  74. Projects. This variable is optional. Usage:
  75. ::
  76. {% set projecticon = "Package" %}
  77. `head_imports()` macro
  78. ######################
  79. A Jinja macro that defines the additional items in the html head to
  80. be imported. The base templates do not include the bootstrap CSS, so
  81. this needs to be included in this macro in your theme. Additionally,
  82. include your favicon here, and a link to any additional CSS files your
  83. theme uses. Example:
  84. ::
  85. {% macro head_imports() %}
  86. <link rel="shortcut icon" type="image/vnd.microsoft.icon"
  87. href="{{ url_for('theme.static', filename='favicon.ico')}}"/>
  88. <link rel="stylesheet" href="{{ url_for('theme.static', filename='bootstrap/bootstrap.min.css')}}" />
  89. <link href="{{ url_for('theme.static', filename='theme.css') }}" rel="stylesheet" type="text/css" />
  90. {% endmacro %}
  91. `js_imports()` macro
  92. ####################
  93. A Jinja macro that defines the additional javascript files to
  94. be imported. The base templates do not include the bootstrap JS, so
  95. this needs to be included in this macro in your theme. Example:
  96. ::
  97. {% macro js_imports() %}
  98. <script src="{{ url_for('theme.static', filename='bootstrap/bootstrap.bundle.min.js')}}"></script>
  99. {% endmacro %}
  100. `browseheader_message(select)` macro
  101. ####################################
  102. An optional Jinja macro that defines the welcome message that is shown
  103. above the tabs on the Browse Pages (Projects, Users, and Groups). The
  104. select parameter is a string with the name of the page being shown
  105. Example:
  106. ::
  107. {% macro browseheader_message(select) %}
  108. {% if select == 'projects' %}
  109. <div class="row justify-content-around">
  110. <div class="col-md-8">
  111. <div class="jumbotron bg-transparent m-0 py-4 text-center">
  112. <h1 class="display-5">Welcome to my Pagure</h1>
  113. <p class="lead">Pagure is an Open Source software code hosting system.</p>
  114. </div>
  115. </div>
  116. </div>
  117. {% endif %}
  118. {% endmacro %}
  119. `footer()` macro
  120. ################
  121. A Jinja macro that defines the footer of the Pagure site. Example:
  122. ::
  123. {% macro footer() %}
  124. <div class="footer py-3 bg-light border-top text-center">
  125. <div class="container">
  126. <p class="text-muted credit">
  127. Powered by
  128. <a href="https://pagure.io/pagure">Pagure</a>
  129. {{ g.version }}
  130. </p>
  131. <p><a href="{{ url_for('ui_ns.ssh_hostkey') }}">SSH Hostkey/Fingerprint</a> | <a href="https://docs.pagure.org/pagure/usage/index.html">Documentation</a></p>
  132. </div>
  133. </div>
  134. {% endmacro %}
  135. `about_page()` macro
  136. ######################
  137. A Jinja macro that defines the content of the About page (available at /about). You may want to replace the links to contact links for your own instance. Example:
  138. ::
  139. {% macro about_page() %}
  140. <div class="container mt-5">
  141. <h1>About</h1>
  142. <p>This is an instance of Pagure, a git forge.</p>
  143. <p>If you experience a bug or security concern, please <a href="https://pagure.io/pagure/issues">submit an issue</a>.</p>
  144. <p>You may also post questions to the Pagure Development list by emailing: <a href="mailto:pagure-devel@lists.pagure.io">pagure-devel@lists.pagure.io</a> or <a href="https://lists.pagure.io/admin/lists/pagure-devel.lists.pagure.io/">subscribe to the list</a>.</p>
  145. <p><a href="https://lists.pagure.io/admin/lists/pagure-announce.lists.pagure.io/">Subscribe to announcements</a> about Pagure.</p>
  146. </div>
  147. {% endmacro %}