From e8433b7fe6dd1dfa5ecf0633568cc3e34caeb0f9 Mon Sep 17 00:00:00 2001 From: Lunny Xiao Date: Thu, 23 Mar 2023 23:18:24 +0800 Subject: Restructure documentation. Now the documentation has installation, administration, usage, development, contributing the 5 main parts (#23629) - **Installation**: includes how to install Gitea and related other tools, also includes upgrade Gitea - **Administration**: includes how to configure Gitea, customize Gitea and manage Gitea instance out of Gitea admin UI - **Usage**: includes how to use Gitea's functionalities. A sub documentation is about packages, in future we could also include CI/CD and others. - **Development**: includes how to integrate with Gitea's API, how to develop new features within Gitea - **Contributing**: includes how to contribute code to Gitea repositories. After this is merged, I think we can have a sub-documentation of `Usage` part named `Actions` to describe how to use Gitea actions --------- Co-authored-by: John Olheiser --- .../doc/advanced/customizing-gitea.en-us.md | 372 --------------------- 1 file changed, 372 deletions(-) delete mode 100644 docs/content/doc/advanced/customizing-gitea.en-us.md (limited to 'docs/content/doc/advanced/customizing-gitea.en-us.md') diff --git a/docs/content/doc/advanced/customizing-gitea.en-us.md b/docs/content/doc/advanced/customizing-gitea.en-us.md deleted file mode 100644 index 4c0235c04a..0000000000 --- a/docs/content/doc/advanced/customizing-gitea.en-us.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -date: "2017-04-15T14:56:00+02:00" -title: "Customizing Gitea" -slug: "customizing-gitea" -weight: 9 -toc: false -draft: false -menu: - sidebar: - parent: "advanced" - name: "Customizing Gitea" - identifier: "customizing-gitea" - weight: 9 ---- - -# Customizing Gitea - -Customizing Gitea is typically done using the `CustomPath` folder - by default this is -the `custom` folder from the running directory, but may be different if your build has -set this differently. This is the central place to override configuration settings, -templates, etc. You can check the `CustomPath` using `gitea help`. You can also find -the path on the _Configuration_ tab in the _Site Administration_ page. You can override -the `CustomPath` by setting either the `GITEA_CUSTOM` environment variable or by -using the `--custom-path` option on the `gitea` binary. (The option will override the -environment variable.) - -If Gitea is deployed from binary, all default paths will be relative to the Gitea -binary. If installed from a distribution, these paths will likely be modified to -the Linux Filesystem Standard. Gitea will attempt to create required folders, including -`custom/`. Distributions may provide a symlink for `custom` using `/etc/gitea/`. - -Application settings can be found in file `CustomConf` which is by default, -`$GITEA_CUSTOM/conf/app.ini` but may be different if your build has set this differently. -Again `gitea help` will allow you review this variable and you can override it using the -`--config` option on the `gitea` binary. - -- [Quick Cheat Sheet](https://docs.gitea.io/en-us/config-cheat-sheet/) -- [Complete List](https://github.com/go-gitea/gitea/blob/main/custom/conf/app.example.ini) - -If the `CustomPath` folder can't be found despite checking `gitea help`, check the `GITEA_CUSTOM` -environment variable; this can be used to override the default path to something else. -`GITEA_CUSTOM` might, for example, be set by an init script. You can check whether the value -is set under the "Configuration" tab on the site administration page. - -- [List of Environment Variables](https://docs.gitea.io/en-us/environment-variables/) - -**Note:** Gitea must perform a full restart to see configuration changes. - -**Table of Contents** - -{{< toc >}} - -## Serving custom public files - -To make Gitea serve custom public files (like pages and images), use the folder -`$GITEA_CUSTOM/public/` as the webroot. Symbolic links will be followed. - -For example, a file `image.png` stored in `$GITEA_CUSTOM/public/`, can be accessed with -the url `http://gitea.domain.tld/assets/image.png`. - -## Changing the logo - -To build a custom logo and/or favicon clone the Gitea source repository, replace `assets/logo.svg` and/or `assets/favicon.svg` and run -`make generate-images`. `assets/favicon.svg` is used for the favicon only. This will update below output files which you can then place in `$GITEA_CUSTOM/public/img` on your server: - -- `public/img/logo.svg` - Used for site icon, app icon -- `public/img/logo.png` - Used for Open Graph -- `public/img/avatar_default.png` - Used as the default avatar image -- `public/img/apple-touch-icon.png` - Used on iOS devices for bookmarks -- `public/img/favicon.svg` - Used for favicon -- `public/img/favicon.png` - Used as fallback for browsers that don't support SVG favicons - -In case the source image is not in vector format, you can attempt to convert a raster image using tools like [this](https://www.aconvert.com/image/png-to-svg/). - -## Customizing Gitea pages and resources - -Gitea's executable contains all the resources required to run: templates, images, style-sheets -and translations. Any of them can be overridden by placing a replacement in a matching path -inside the `custom` directory. For example, to replace the default `.gitignore` provided -for C++ repositories, we want to replace `options/gitignore/C++`. To do this, a replacement -must be placed in `$GITEA_CUSTOM/options/gitignore/C++` (see about the location of the `CustomPath` -directory at the top of this document). - -Every single page of Gitea can be changed. Dynamic content is generated using [go templates](https://golang.org/pkg/html/template/), -which can be modified by placing replacements below the `$GITEA_CUSTOM/templates` directory. - -To obtain any embedded file (including templates), the [`gitea embedded` tool]({{< relref "doc/advanced/cmd-embedded.en-us.md" >}}) can be used. Alternatively, they can be found in the [`templates`](https://github.com/go-gitea/gitea/tree/main/templates) directory of Gitea source (Note: the example link is from the `main` branch. Make sure to use templates compatible with the release you are using). - -Be aware that any statement contained inside `{{` and `}}` are Gitea's template syntax and -shouldn't be touched without fully understanding these components. - -### Customizing startpage / homepage - -Copy [`home.tmpl`](https://github.com/go-gitea/gitea/blob/main/templates/home.tmpl) for your version of Gitea from `templates` to `$GITEA_CUSTOM/templates`. -Edit as you wish. -Dont forget to restart your Gitea to apply the changes. - -### Adding links and tabs - -If all you want is to add extra links to the top navigation bar or footer, or extra tabs to the repository view, you can put them in `extra_links.tmpl` (links added to the navbar), `extra_links_footer.tmpl` (links added to the left side of footer), and `extra_tabs.tmpl` inside your `$GITEA_CUSTOM/templates/custom/` directory. - -For instance, let's say you are in Germany and must add the famously legally-required "Impressum"/about page, listing who is responsible for the site's content: -just place it under your "$GITEA_CUSTOM/public/" directory (for instance `$GITEA_CUSTOM/public/impressum.html`) and put a link to it in either `$GITEA_CUSTOM/templates/custom/extra_links.tmpl` or `$GITEA_CUSTOM/templates/custom/extra_links_footer.tmpl`. - -To match the current style, the link should have the class name "item", and you can use `{{AppSubUrl}}` to get the base URL: -`Impressum` - -For more information, see [Adding Legal Pages](https://docs.gitea.io/en-us/adding-legal-pages). - -You can add new tabs in the same way, putting them in `extra_tabs.tmpl`. -The exact HTML needed to match the style of other tabs is in the file -`templates/repo/header.tmpl` -([source in GitHub](https://github.com/go-gitea/gitea/blob/main/templates/repo/header.tmpl)) - -### Other additions to the page - -Apart from `extra_links.tmpl` and `extra_tabs.tmpl`, there are other useful templates you can put in your `$GITEA_CUSTOM/templates/custom/` directory: - -- `header.tmpl`, just before the end of the `` tag where you can add custom CSS files for instance. -- `body_outer_pre.tmpl`, right after the start of ``. -- `body_inner_pre.tmpl`, before the top navigation bar, but already inside the main container `
`. -- `body_inner_post.tmpl`, before the end of the main container. -- `body_outer_post.tmpl`, before the bottom `