diff --git a/docs/admin/customization.md b/docs/admin/customization.md
new file mode 100644
index 00000000..e928fb38
--- /dev/null
+++ b/docs/admin/customization.md
@@ -0,0 +1,17 @@
+---
+title: 'Interface customization'
+license: 'CC-BY-SA-4.0'
+---
+
+Forgejo currently has limited capabilities for customizing the user interface.
+
+Some settings are provided to customize the look and feel of the Forgejo user interface, such as the default theme or the description that shows on the home page. See a complete list of those settings in the config cheat sheet:
+
+- In the [UI section](../config-cheat-sheet/#ui-ui) and below.
+- The `APP_NAME` setting in the [Overall section](../config-cheat-sheet/#overall-default)
+
+They are documented and supported to be backward compatible between versions.
+
+It is also possible to customize Forgejo by recompiling from the sources and changing the files. Or by extracting and modifying the relevant files with the `forgejo embedded extract` CLI. In both cases an intimate knowledge of the underlying codebase is necessary to figure out what files should be modified to achieve the desired result. They are considered an internal detail: non backward compatible changes will be introduced without warning in the release notes and they will not be documented.
+
+See also the [developer section on interface customization](../../developer/customization/) for more information.
diff --git a/docs/admin/index.md b/docs/admin/index.md
index 3e3158a3..4e129fe4 100644
--- a/docs/admin/index.md
+++ b/docs/admin/index.md
@@ -24,3 +24,4 @@ These documents are targeted to people who run Forgejo on their machines.
- [GPG Commit Signatures](./signing/)
- [Moderation tools](./moderation/)
- [Adopt existing git directories](./adopt/)
+- [Interface customization](./customization/)
diff --git a/docs/developer/customization.md b/docs/developer/customization.md
new file mode 100644
index 00000000..c0c16eb2
--- /dev/null
+++ b/docs/developer/customization.md
@@ -0,0 +1,180 @@
+---
+title: 'Interface customization'
+license: 'Apache-2.0'
+origin_url: 'https://github.com/go-gitea/gitea/blob/abe8fe352711601fbcd24bf4505f7e0b81a93c5d/docs/content/administration/customizing-gitea.en-us.md'
+---
+
+This sections documents the Forgejo interface customization that requires an intimate knowledge of the underlying codebase. The user interface customization documented and supported for Forgejo admins to use [is found in the corresponding administrator guide section](../../admin/customization/).
+
+Customizing Forgejo is typically done using the `CustomPath` folder - by default this is
+the `custom` folder from the working directory (WorkPath), 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 `forgejo 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 `FORGEJO_CUSTOM` environment variable or by
+using the `--custom-path` option on the `forgejo` binary. (The option will override the
+environment variable.)
+
+If Forgejo is deployed from binary, all default paths will be relative to the Forgejo
+binary.
+
+Application settings can be found in file `CustomConf` which is by default,
+`$FORGEJO_CUSTOM/conf/app.ini` but may be different if your build has set this differently.
+Again `forgejo help` will allow you review this variable and you can override it using the
+`--config` option on the `forgejo` binary.
+
+**Note:** Forgejo must perform a full restart to see configuration changes.
+
+## Serving custom public files
+
+To make Forgejo serve custom public files (like pages and images), use the folder
+`$FORGEJO_CUSTOM/public/` as the webroot. Symbolic links will be followed.
+At the moment, only the following files are served:
+
+- `public/robots.txt`
+- files in the `public/.well-known/` folder
+- files in the `public/assets/` folder
+
+For example, a file `image.png` stored in `$FORGEJO_CUSTOM/public/assets/`, can be accessed with
+the url `http://forgejo.domain.tld/assets/image.png`.
+
+## Changing the logo
+
+To build a custom logo and/or favicon clone the Forgejo 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 `$FORGEJO_CUSTOM/public/assets/img` on your server:
+
+- `public/assets/img/logo.svg` - Used for site icon, app icon
+- `public/assets/img/logo.png` - Used for Open Graph
+- `public/assets/img/avatar_default.png` - Used as the default avatar image
+- `public/assets/img/apple-touch-icon.png` - Used on iOS devices for bookmarks
+- `public/assets/img/favicon.svg` - Used for favicon
+- `public/assets/img/favicon.png` - Used as fallback for browsers that don't support SVG favicons
+
+## Customizing Forgejo pages and resources
+
+Forgejo'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 `$FORGEJO_CUSTOM/options/gitignore/C++`.
+
+Every single page of Forgejo can be changed. Dynamic content is generated using [go templates](https://pkg.go.dev/html/template),
+which can be modified by placing replacements below the `$FORGEJO_CUSTOM/templates` directory.
+
+To obtain any embedded file (including templates), the `forgejo embedded` CLI can be used. Alternatively, they can be found in the [`templates`](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates) directory of Forgejo source.
+
+Be aware that any statement contained inside `{{` and `}}` are Forgejo's template syntax and
+shouldn't be touched without fully understanding these components.
+
+### Customizing startpage / homepage
+
+Copy [`home.tmpl`](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/templates/home.tmpl) for your version of Forgejo from `templates` to `$FORGEJO_CUSTOM/templates`.
+Edit as you wish.
+Dont forget to restart your Forgejo 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 `$FORGEJO_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 "$FORGEJO_CUSTOM/public/assets/" directory (for instance `$FORGEJO_CUSTOM/public/assets/impressum.html`) and put a link to it in either `$FORGEJO_CUSTOM/templates/custom/extra_links.tmpl` or `$FORGEJO_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`
+
+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`](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/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 `$FORGEJO_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 `