Skip to content

Commit

Permalink
Custom template
Browse files Browse the repository at this point in the history
  • Loading branch information
@unknwon
unknwon committed Feb 17, 2020
1 parent ce50887 commit b72c79b
Show file tree
Hide file tree
Showing 2 changed files with 47 additions and 39 deletions.
44 changes: 21 additions & 23 deletions en-US/features/custom_template.md
View file
@@ -1,44 +1,42 @@
---
name: Custom Template
name: Custom template
---

# Customizing Templates
# Customizing templates

There are two types of template customizations you can utilize:
1. Template replacement
* The core template is superseded by the custom template and thus the original will not execute.
* Future template changes must be manually integrated into your custom override templates.
2. Code injection
* This keeps the original template, but simply injects additional code.
* Future template changes are automatically integrated when you upgrade to newer releases.

## Override HTML templates

## Replace With a Custom Template
You can replace/override core templates by creating a custom version. Your replacement templates will survive code updates, but you may want to keep tabs on them in case functionality changes. Be careful when replacing core templates as you may break things in future releases.
You can override HTML templates (including templates for emails) by creating a customized version by creating a customized version under `custom/templates/` directory. Your version of HTML templates will survive code updates, but you may want to keep tabs on them in case functionality changes. Be careful when overriding HTML templates as you may break things in future releases.

A great example is to customize the look and contents of the home page.
An example is to customize the look and contents of the home page:

1. Copy the existing template `/templates/home.tmpl`
2. Save edited file as `custom/templates/home.tmpl`
1. Copy the content of template file `templates/home.tmpl`.
2. Save edited file as `custom/templates/home.tmpl`.

Edits to the custom template file(s) do not require restart Gogs
⚠ Edits to the custom HTML templates **require restarting Gogs**.

Other templates can also be replaced by saving the customized template in the same relative location as the original, but under the `custom/templates` directory. Create subdirectories as needed in the `custom/templates` directory to match the corresponding template file you wish to override.
## Override static files

To create a custom replacement 404 template, you would save it as `custom/templates/status/404.tmpl`
You can override static files (CSS, JavaScript, images, etc.) by creating a customized version under `custom/public/` directory. Your version of static files will survive code updates, but you may want to keep tabs on them in case functionality changes. Be careful when overriding static files as you may break things in future releases.

For example, you can override the site favicon by putting your version of favicon to `custom/public/img/favicon.png`.

⚠ Edits to the custom static files **DO NOT require restarting Gogs**.

## Inject content into existing templates

## Inject Code Into Existing Template
You can inject your custom head or footer content to Gogs without touching source code of main repository. This is useful if you want to add analytics code or include custom static resources.

[You can read more about injecting a custom head and footer here.](https://discuss.gogs.io/t/how-to-inject-custom-head-and-footer/943).

## Include Custom CSS File
This approach is recommended whenever possible because it has the minimum impact on templates.

### Inject custom CSS file

Here is an example of how you can include a custom CSS file in your Gogs instance. Names and directories are just for demonstration, you can put it anywhere as long as it can be accessed via network requests.

1. Create a file named `custom.css` under `public/css` directory.
1. Create a file named `custom.css` under `custom/public/css/` directory.
2. Put some CSS rules into the file.
3. Edit file `custom/templates/inject/head.tmpl` and add a line `<link rel="stylesheet" href="/css/custom.css">`
4. Restart Gogs
5. Further changes to the custom CSS file do not require restarting Gogs.
4. Restart Gogs.
5. Future edits to the custom CSS file **DO NOT require restarting Gogs**.
42 changes: 26 additions & 16 deletions zh-CN/features/custom_template.md
View file
Expand Up @@ -4,29 +4,39 @@ name: 自定义模板

# 自定义模板

您可以不需要修改仓库源码就能注入自定义头部和尾部内容，这对添加分析代码和自定义静态资源非常有用。
## 重载 HTML 模板

了解更多有关 [注入自定义头部和尾部](https://discuss.gogs.io/t/how-to-inject-custom-head-and-footer/943)。
用户可以通过在 `custom/templates/` 目录下创建一个自定义版本的副本实现 HTML 模板重载（包括邮件模板），该文件不会因为版本升级而受到影响，但可以会因为改动过大导致与后续版本不兼容。

## 添加自定义 CSS 文件
例如，可以通过以下步骤自定义站点首页：

这里展示如何为您的 Gogs 实例添加自定义 CSS 文件，目录和文件名都是为了方便演示，您可以把文件放在任何能够通过网络访问的目录。
1. 复制模板文件 `templates/home.tmpl` 的内容
2. 将修改保存到文件 `custom/templates/home.tmpl`

1. 在 `public/css` 目录下创建一个名为 `custom.css` 的文件
2. 向文件中添加一些 CSS 规则
3. 编辑 `custom/templates/inject/head.tmpl` 文件并添加一行内容 `<link rel="stylesheet" href="/css/custom.css">`
4. 重启 Gogs
5. 后续对自定义 CSS 文件的编辑不需要重启 Gogs
⚠ 所有针对自定义模板的修改都**需要重启 Gogs 实例**

## 重载静态文件

# 自定义首页
用户可以通过在 `custom/public/` 目录下创建一个自定义版本的副本实现静态文件重载（CSS、JavaScript、图片等等），该文件不会因为版本升级而受到影响，但可以会因为改动过大导致与后续版本不兼容。

首页内容属于仓库源码，首页修改不包括自定义头部和尾部内容。
例如，可以通过保存自定义图标到 `custom/public/img/favicon.png` 实现站点图标的重载。

## 修改首页内容
⚠ 所有针对自定义静态文件的修改都**不需要重启 Gogs 实例**

首页源码位置 `templates/home.tmpl`
## 注入自定义内容到模板中

您可以不需要修改仓库源码就能注入自定义头部和尾部内容，这对添加分析代码和自定义静态资源非常有用。

1. 保留该文件的头部和尾部引用
注意保留：头：{{template "base/head" .}}，尾：{{template "base/footer" .}}
2. 编辑自定义首页中间部分 `templates/home.tmpl`
了解更多有关 [注入自定义头部和尾部](https://discuss.gogs.io/t/how-to-inject-custom-head-and-footer/943)。

在条件允许的情况下，尽可能使用该方案以减少对模板渲染的影响。

### 注入自定义 CSS 文件

这里展示如何为您的 Gogs 实例添加自定义 CSS 文件，目录和文件名都是为了方便演示，您可以把文件放在任何能够通过网络访问的目录。

1. 在 `custom/public/css/` 目录下创建一个名为 `custom.css` 的文件
2. 向文件中添加一些 CSS 规则
3. 编辑 `custom/templates/inject/head.tmpl` 文件并添加一行内容 `<link rel="stylesheet" href="/css/custom.css">`
4. 重启 Gogs
5. 后续对自定义 CSS 文件的编辑**不需要重启 Gogs 实例**

0 comments on commit b72c79b

Please sign in to comment.