Custom templates

Override HTML templates, static files, and inject custom content

Content injection through inject/head.tmpl and inject/footer.tmpl, static file overrides under custom/public/, and email template overrides all remain fully supported.

Gogs allows you to customize the appearance and behavior of your instance by overriding HTML templates, replacing static files, and injecting custom content. All customizations are placed under the custom/ directory and survive code updates.

Override HTML templates

You can replace any HTML template (including email templates) by placing a customized version under the custom/templates/ directory.

1. 1
   Find the original template

   Locate the template file you want to customize in the templates/ directory of the Gogs source code. For example, to customize the home page, find templates/home.tmpl.

2. 2
   Copy and edit

   Copy the content of the template file and save your edited version to the corresponding path under custom/templates/. For example:

   custom/templates/home.tmpl

3. 3
   Restart Gogs

   Edits to custom HTML templates require restarting Gogs to take effect.

Override static files

You can replace static files (CSS, JavaScript, images, etc.) by placing customized versions under the custom/public/ directory.

For example, to override the site favicon, place your version at:

custom/public/img/favicon.png

Inject custom content

You can inject custom HTML into the head or footer of every page without touching the main repository source code. This is useful for adding analytics code, custom stylesheets, or other static resources.

This approach is recommended whenever possible because it has the minimum impact on templates and is less likely to break during upgrades.

The injection points are:

Example: custom CSS file

The following example shows how to include a custom CSS file in your Gogs instance:

1. 1
   Create the CSS file

   Create a file named custom.css under the custom/public/css/ directory:

   custom/public/css/custom.css

2. 2
   Add your CSS rules

   Write your CSS rules in the file. For example:

   /* custom/public/css/custom.css */
   .dashboard .news .news-item .header {
     color: #333;
   }
   
   footer {
     background-color: #f5f5f5;
   }

3. 3
   Link the stylesheet

   Edit the file custom/templates/inject/head.tmpl and add a link to your CSS file:

   <link rel="stylesheet" href="/css/custom.css">

4. 4
   Restart Gogs

   Restart Gogs to load the new head.tmpl injection template. A production server reads the injection templates once at startup, so later edits to head.tmpl or footer.tmpl require another restart. Edits to the custom CSS file it links do not require a restart.