Blame doc/usage/theming.rst

Ryan Lerch 2a8d61
Theming Guide
Pierre-Yves Chibon 704577
=================
Pierre-Yves Chibon 704577
Ryan Lerch 2a8d61
Pagure is built on Flask, and uses Jinja2 for templates. Pagure also
Ryan Lerch 2a8d61
includes the ability to apply different themes that control the look
Ryan Lerch 2a8d61
and feel of your pagure instance, or add or remove elements from the
Ryan Lerch 2a8d61
interface.
Pierre-Yves Chibon 704577
Ryan Lerch 2a8d61
Setting a theme
Ryan Lerch 2a8d61
---------------
Pierre-Yves Chibon 96aaa1
The theme is set in the Pagure configuration file. The theme name is defined by
Pierre-Yves Chibon 96aaa1
the name of the directory in the /themes/ folder that contains the theme. For
Pierre-Yves Chibon 96aaa1
example to enable the theme that is used on Pagure.io, add the following line
Pierre-Yves Chibon 96aaa1
to your Pagure configuration:
Pierre-Yves Chibon 704577
Ryan Lerch 2a8d61
::
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon eac6d9
    THEME = "pagureio"
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 9dd1c0
Ryan Lerch 2a8d61
Theme contents
Ryan Lerch 2a8d61
---------------
Ryan Lerch 2a8d61
A theme requires two directories (`templates` and `static`) in the directory
Ryan Lerch 2a8d61
that contains the theme. The only other required file is theme.html which
Ryan Lerch 2a8d61
is placed in the templates directory
Pierre-Yves Chibon 9dd1c0
Ryan Lerch 2a8d61
templates/
Ryan Lerch 2a8d61
~~~~~~~~~~
Ryan Lerch 2a8d61
The `templates` directory is where pagure will look for the `theme.html`
Ryan Lerch 2a8d61
template. Additionally, if you wish to override any template in Pagure,
Ryan Lerch 2a8d61
place it in the theme templates/ directory, and pagure will use that
Ryan Lerch 2a8d61
template rather than the standard one.
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 96aaa1
.. warning:: Take care when overriding templates, as any changes to Pagure
Pierre-Yves Chibon 96aaa1
            upstream will need to be backported to your theme template override.
Pierre-Yves Chibon 1342a6
Ryan Lerch 2a8d61
static/
Ryan Lerch 2a8d61
~~~~~~~
Ryan Lerch 2a8d61
The `static` directory contains all the static elements for the theme,
Ryan Lerch 2a8d61
including additional a favicon, images, Javascript, and CSS files. To
Ryan Lerch 2a8d61
reference a file in the theme static directory use the jinja2 tag
Ryan Lerch 2a8d61
`{{ url_for('theme.static', filename='filename')}}`. For example:
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
::
Pierre-Yves Chibon 1342a6
Ryan Lerch 2a8d61
    
Ryan Lerch 2a8d61
          rel="stylesheet" type="text/css" />
Ryan Lerch 2a8d61
Ryan Lerch 2a8d61
Ryan Lerch 2a8d61
templates/theme.html
Ryan Lerch 2a8d61
~~~~~~~~~~~~~~~~~~~~
Ryan Lerch 2a8d61
The theme.html file defines a subset of items in the Pagure interface that
Ryan Lerch 2a8d61
are commonly changed when creating a new theme. Theming is a new feature in
Ryan Lerch 2a8d61
Pagure, so this set is currently small, but please file issues or PRs against
Ryan Lerch 2a8d61
pagure with ideas of new items to include.
Pierre-Yves Chibon 1342a6
Ryan Lerch 2a8d61
The current items configurable in theme.html are:
Ryan Lerch 2a8d61
Pierre-Yves Chibon 96aaa1
Ryan Lerch 2a8d61
`masthead_class` variable
Ryan Lerch 2a8d61
#########################
Ryan Lerch 2a8d61
Ryan Lerch 2a8d61
A string of additional CSS class(es) to be added to the `.masthead` element.
Ryan Lerch 2a8d61
The masthead is the topbar in Pagure. For example:
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
::
Pierre-Yves Chibon 1342a6
Ryan Lerch 2a8d61
    {% set masthead_class = "bg-dark" %}
Ryan Lerch 2a8d61
Pierre-Yves Chibon 1342a6
Ryan Lerch 2a8d61
`masthead_nav_class` variable
Ryan Lerch 2a8d61
#############################
Ryan Lerch 2a8d61
Ryan Lerch 2a8d61
A string of additional CSS class(es) to be added to the bootstrap
Ryan Lerch 2a8d61
`navbar` element that is used as the top level menu in the top right
Ryan Lerch 2a8d61
of the Pagure interface. This is primarily used to control the text
Ryan Lerch 2a8d61
color of the nav elements. For example, if you have a dark colour for
Ryan Lerch 2a8d61
the masthead, you would set this:
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
::
Pierre-Yves Chibon 1342a6
Ryan Lerch 2a8d61
    {% set masthead_nav_class = "navbar-dark" %}
Ryan Lerch 2a8d61
Pierre-Yves Chibon 96aaa1
Ryan Lerch 2a8d61
`site_title` variable
Ryan Lerch 2a8d61
#############################
Pierre-Yves Chibon 1342a6
Ryan Lerch 2a8d61
A string containing the text to append at the end of the html title
Ryan Lerch 2a8d61
on every page on the site. Usage:
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 1342a6
::
Pierre-Yves Chibon 1342a6
Ryan Lerch 2a8d61
    {% set site_title = "Pagure" %}
Ryan Lerch 2a8d61
Pierre-Yves Chibon 96aaa1
Ryan Lerch 2a8d61
`head_imports()` macro
Ryan Lerch 2a8d61
######################
Pierre-Yves Chibon 1342a6
Ryan Lerch 2a8d61
A Jinja macro that defines the additional items in the html head to
Ryan Lerch 2a8d61
be imported. The base templates do not include the bootstrap CSS, so
Ryan Lerch 2a8d61
this needs to be included in this macro in your theme. Additionally,
Ryan Lerch 2a8d61
include your favicon here, and a link to any additional CSS files your
Ryan Lerch 2a8d61
theme uses. Example:
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon c669d2
::
Pierre-Yves Chibon c669d2
Ryan Lerch 2a8d61
    {% macro head_imports() %}
Ryan Lerch 2a8d61
        
Ryan Lerch 2a8d61
              href="{{ url_for('theme.static', filename='favicon.ico')}}"/>
Ryan Lerch 2a8d61
        <link href="{{ url_for('theme.static', filename='bootstrap/bootstrap.min.css')}}" rel="stylesheet">
Ryan Lerch 2a8d61
        <link href="{{ url_for('theme.static', filename='theme.css') }}" rel="stylesheet" type="text/css">
Ryan Lerch 2a8d61
    {% endmacro %}
Pierre-Yves Chibon 1342a6
Pierre-Yves Chibon 96aaa1
Ryan Lerch 2a8d61
`js_imports()` macro
Ryan Lerch 2a8d61
######################
Pierre-Yves Chibon d66fc1
Ryan Lerch 2a8d61
A Jinja macro that defines the additional javascript files to
Ryan Lerch 2a8d61
be imported. The base templates do not include the bootstrap JS, so
Ryan Lerch 2a8d61
this needs to be included in this macro in your theme. Example:
Pierre-Yves Chibon d66fc1
Ryan Lerch 2a8d61
::
Pierre-Yves Chibon d66fc1
Ryan Lerch 2a8d61
    {% macro js_imports() %}
Ryan Lerch 2a8d61
        <script src="{{ url_for('theme.static', filename='bootstrap/bootstrap.bundle.min.js')}}"></script>
Ryan Lerch 2a8d61
    {% endmacro %}
Pierre-Yves Chibon d66fc1
Pierre-Yves Chibon 96aaa1
Ryan Lerch 2a8d61
`footer()` macro
Ryan Lerch 2a8d61
######################
Pierre-Yves Chibon d66fc1
Ryan Lerch 2a8d61
A Jinja macro that defines the footer of the Pagure site. Example:
Pierre-Yves Chibon d66fc1
Ryan Lerch 2a8d61
::
Pierre-Yves Chibon d66fc1
Ryan Lerch 2a8d61
    {% macro footer() %}
Ryan Lerch 2a8d61
        
Ryan Lerch 2a8d61
            
Ryan Lerch 2a8d61
                

Ryan Lerch 2a8d61
            Powered by
Ryan Lerch 2a8d61
            Pagure
Ryan Lerch 2a8d61
            {{ g.version }}
Ryan Lerch 2a8d61
                

Ryan Lerch 2a8d61
                

SSH Hostkey/Fingerprint | Documentation

Ryan Lerch 2a8d61
            
Ryan Lerch 2a8d61
        
Ryan Lerch 2a8d61
    {% endmacro %}