Update readme / change defaults

This commit is contained in:
Simon Gregor Ebner 2025-02-20 23:32:17 +01:00
parent 4f438ef88c
commit b749679e17
2 changed files with 42 additions and 11 deletions

View File

@ -1,14 +1,29 @@
__INFO: preliminary documentation ... more to come__
# Overview # Overview
This is an all in one pages server for [Gitea](https://gitea.com). With default settings it works and uses similar/same conventions as [Github Pages](https://pages.github.com). This is an all-in-one pages server for [Gitea](https://gitea.com). It works and uses similar/same conventions as [Github Pages](https://pages.github.com).
You can operate it in 2 modes, either __simple__ (default) or __classic__ (similar to how Github Pages operates). You can operate it in 2 modes, either __simple__ (default) or __classic__ (similar to how Github Pages operates).
In __simple__ mode no special DNS setup is required and the access to the hosted sides are always according to the pattern __http(s)://<your-server-hostname>/<organization>/<repository>__ __simple:__
In __classic__ mode the access to the pages goes according to these two patterns: __http(s)://<organization>.<your-server-hostname>/<repository>__ or __http(s)://<organization>.<your-server-hostname>__ (with default configuration this serves the content of the repo named __<organization>.github.io__ of the organization) This requires that you setup a wildcard CNAME in DNS for your gitea host (see below for more details). You also need a wildcard HTTPS certificate if you want to run with HTTPS. In __simple__ mode no special DNS setup is required and the access to the hosted sides are always according to the pattern
__http(s)://<your-server-hostname>/<organization>/<repository>__
__classic:__
In __classic__ mode the access to the pages goes according to these two patterns:
__http(s)://<organization>.<your-server-hostname>/<repository>__
or
__http(s)://<organization>.<your-server-hostname>__
The latter url scheme with serves the content of the repo named __<organization>.gitea-pages__ of the organization (with default settings).
Classic mode requires that you setup a _wildcard CNAME_ in DNS for your gitea pages host (see below for more details). You also need a _wildcard HTTPS_ certificate if you want to run with HTTPS.
# Usage # Usage
@ -44,16 +59,32 @@ These are the possible configuration options with their defaults:
gitea-pages { gitea-pages {
server https://your-gitea-server server https://your-gitea-server
token gitea-access-token token gitea-access-token
pages_branch gh-pages pages_branch gitea-pages
postfix_pages_repository github.io postfix_pages_repository gitea.io
url_scheme simple url_scheme simple
} }
log { log {
level debug level debug
} }
``` ```
For __url_scheme__ defines the operation mode, it accepts _simple_ and _classic_. | Option | Description |
|----|----|
| server | The URL of your Gitea server. |
| token | Your access token for the Gitea API. This token is used to authenticate requests made to the Gitea server.|
| pages_branch | The branch in your repository that contains the static files for your website or documentation. By default, this would be the branch "gitea-pages" |
| postfix_pages_repository | The (domain) postfix used for the pages repository. (This could be the domain where your site will be accessible, such as "gitea.io".) |
| url_scheme | The URL scheme to use for the pages. "simple" or "classic |
For example, if you want to assemble the same "look and feel" then on github you could set following settings in the config:
|||
|----|----|
| pages_branch | gh-pages |
| postfix_pages_repository | github.io |
| url_scheme | classic |
# Development # Development

View File

@ -74,10 +74,10 @@ func (module *GiteaPagesModule) UnmarshalCaddyfile(d *caddyfile.Dispenser) error
// Set defaults // Set defaults
if module.PagesBranch == "" { if module.PagesBranch == "" {
module.PagesBranch = "gh-pages" module.PagesBranch = "gitea-pages"
} }
if module.PostfixPagesRepository == "" { if module.PostfixPagesRepository == "" {
module.PostfixPagesRepository = "github.io" module.PostfixPagesRepository = "gitea.io"
} }
if module.URLScheme == "" { if module.URLScheme == "" {