https://github.com/flant/web-router
Go HTTP-server for software documentation websites. Adds the ability to have several documentation versions on the site: generates page partials for a menu, routes traffic, etc.
https://github.com/flant/web-router
Last synced: about 1 year ago
JSON representation
Go HTTP-server for software documentation websites. Adds the ability to have several documentation versions on the site: generates page partials for a menu, routes traffic, etc.
- Host: GitHub
- URL: https://github.com/flant/web-router
- Owner: flant
- License: apache-2.0
- Created: 2021-11-03T08:23:37.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2022-11-21T00:02:40.000Z (over 3 years ago)
- Last Synced: 2025-03-23T01:02:45.308Z (over 1 year ago)
- Language: Go
- Homepage:
- Size: 42 KB
- Stars: 0
- Watchers: 12
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Web Version Router (v-router)
**STAGE: Development**
Go HTTP-server for software documentation websites.
Adds the ability to have several documentation versions on the site: generates page partials for a menu, routes traffic, etc.
## Channel names
The following channel names used (from less stable to more stable): Alpha, Beta, EarlyAccess, Stable, RockSolid.
The `VROUTER_USE_LATEST_CHANNEL` env adds `latest` channel the the channels list.
## Configuration
web-router uses the following environment variables:
- `VROUTER_PATH_CHANNELS_FILE` — file in [appropriate format](#channels-file-format) containing information about versions and channels
- `VROUTER_PATH_STATIC` — path for static files to serve
- `VROUTER_PATH_TPLS` — directory inside the `VROUTER_PATHSTATIC`, where templates resides. It is also a URL-location. Default — `/includes`.
- `VROUTER_LOG_FORMAT` — Log format to use (json|text|color). Default — text.
- `VROUTER_LOG_LEVEL` — Logging level (`info`, `debug`, `trace`)
- `VROUTER_LISTEN_PORT` — IP port to listen on (default - '8080')
- `VROUTER_LISTEN_ADDRESS` — IP ddress to listen on (default - '0.0.0.0')
- `VROUTER_LOCATION_VERSIONS` — URL-location where versions will be accessed (default - `/documentation`).
- `VROUTER_DEFAULT_GROUP` — The default group name according to the used channel file. E.g. - "v1" or "1" (the leading 'v' can be ommited).
- `VROUTER_DEFAULT_CHANNEL` — The default channel name. E.g. - "stable".
- `VROUTER_SHOW_LATEST_CHANNEL` — Whether to show the 'latest' channel in the menu (default - `false`).
- `VROUTER_URL_VALIDATION` — Whether to use URL checking before redirect (use false on test environments or protected with authentication).
- `VROUTER_DOMAIN_MAP` — JSON structure to map language to domain. Example: '{"en" : "global.company.com", "cn" : "company.cn"}'
- `VROUTER_I18N_TYPE` — Localization method. Can be `domain`, `location` or `separate-domain` (default - `location`).
- `location` - Versioned pages URL is like `//`. E.g `/en/documentation/`.
- `domain` - Versioned pages URL is like `.somedomain//`. E.g `ru.product.my/documentation/`.
- `separate-domain` - Use a separate domain for each language. Fill the `VROUTER_DOMAIN_MAP` value to use this mode.
### Templates
All the templates should be placed in the `/includes`
### Channels file format
A file, containing information about which version is assigned to which channel, is the channel file. It can be YAML or JSON formatted.
Specify a path to the channels file in the `VROUTER_PATHCHANNELSFILE` environment variable. The default path to the channels file is 'channels.yaml' (relative to the directory where web-router starts).
YAML Example:
```yaml
groups:
- name: "1.1"
channels:
- name: alpha
version: 1.1.23+fix50
- name: beta
version: 1.1.23+fix25
- name: ea
version: 1.1.22+fix40
- name: stable
version: 1.1.21+fix40
- name: rock-solid
version: 1.1.21
- name: "1.2"
channels:
- name: alpha
version: 1.2.34 # Feature X was implemented
- name: beta
version: 1.2.33 # Feature Y was implemented
- name: ea
version: 1.2.27+fix3
```
JSON example:
```json
{
"groups": [
{
"name": "1.1",
"channels": [
{
"name": "alpha",
"version": "1.1.23+fix50"
},
{
"name": "beta",
"version": "1.1.23+fix25"
},
{
"name": "ea",
"version": "1.1.22+fix40"
},
{
"name": "stable",
"version": "1.1.21+fix40"
},
{
"name": "rock-solid",
"version": "1.1.21"
}
]
},
{
"name": "1.2",
"channels": [
{
"name": "alpha",
"version": "1.2.34"
},
{
"name": "beta",
"version": "1.2.33"
},
{
"name": "ea",
"version": "1.2.27+fix3"
}
]
}
]
}
```
## Healthchecks, probes and status information
- `/health` — normal response is JSON: `{"status": "ok"}`
- `/status` — retrieves content of a [channel file](#channels-file-format) used
## How to debug
Compile:
```
go build -gcflags "all=-N -l" -v -o server ./cmd/web-router
```
Run:
```
dlv --listen=:2345 --headless=true --api-version=2 --accept-multiclient exec ./server
```
Connect to localhost:2345