Skip to main content
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.
Be careful when overriding templates and static files, as changes to the upstream Gogs codebase may break your customizations in future releases. Keep track of what you have overridden.

​
Override HTML templates

You can replace any HTML template (including email templates) by placing a customized version under the custom/templates/ directory.
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

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

Restart Gogs

Edits to custom HTML templates require restarting Gogs to take effect.
Override for email templates is disabled when [server] LOAD_ASSETS_FROM_DISK = true is set in your configuration. If you are using this setting, email template overrides will not be applied.

​
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
Edits to custom static files do not require restarting Gogs. Changes take effect immediately.

​
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:
FileLocationPurpose
custom/templates/inject/head.tmplInside <head>Add stylesheets, meta tags, analytics scripts
custom/templates/inject/footer.tmplBefore </body>Add scripts, tracking code, custom footer content

​
Example: custom CSS file

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

Create the CSS file

Create a file named custom.css under the custom/public/css/ directory:
custom/public/css/custom.css
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

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

Restart Gogs

Restart Gogs to load the new head.tmpl injection template. After the initial restart, future edits to the custom CSS file do not require restarting Gogs.