docs: improve page content [skip ci]
Diff
docs/content/configuration/command-line-arguments.md | 2 +-
docs/content/configuration/config-file.md | 14 ++++++++++++++
docs/content/features/basic-authentication.md | 2 +-
docs/content/features/cors.md | 4 ++--
docs/content/features/custom-http-headers.md | 6 +++---
docs/content/features/directory-listing.md | 2 +-
docs/content/features/docker.md | 4 ++--
docs/content/features/error-pages.md | 2 +-
docs/content/features/file-descriptor-socket-passing.md | 2 +-
docs/content/features/graceful-shutdown.md | 2 --
docs/content/features/health-endpoint.md | 4 ++--
docs/content/features/http-https-redirect.md | 2 +-
docs/content/features/http-methods.md | 2 +-
docs/content/features/ignore-files.md | 2 +-
docs/content/features/windows-service.md | 2 +-
docs/content/index.md | 2 +-
docs/content/semantic-versioning.md | 4 ++--
docs/mkdocs.yml | 2 +-
18 files changed, 36 insertions(+), 24 deletions(-)
@@ -91,7 +91,7 @@ Options:
## Windows
The following options and commands are Windows platform specific.
The following options and commands are Windows platform-specific.
```
-s, --windows-service <windows-service>
@@ -124,10 +124,24 @@ health = false
# [[advanced.rewrites]]
# source = "**/*.{png,ico,gif}"
# destination = "/assets/favicon.ico"
## Optional redirection
# redirect = 301
# [[advanced.rewrites]]
# source = "**/*.{jpg,jpeg}"
# destination = "/images/sws.png"
### Virtual Hosting
# [[advanced.virtual-hosts]]
## But if the "Host" header matches this...
# host = "sales.example.com"
## ...then files will be served from here instead
# root = "/var/sales/html"
# [[advanced.virtual-hosts]]
# host = "blog.example.com"
# root = "/var/blog/html"
```
### General options
@@ -31,7 +31,7 @@ htpasswd -nBC10 "username"
!!! tip "Docker Compose Advice"
If you are using `SERVER_BASIC_AUTH` env via a `docker-compose.yml` file don't forget to replace the single `$` (dollar sign) with a `$$` (double-dollar sign) if you want those individual `$` dollar signs in your configuration to be treated by Docker as literals.<br>
More details at [Docker Compose file: variable substitution](https://docs.docker.com/compose/compose-file/compose-file-v2/#variable-substitution)
More details in [the Docker Compose file: variable substitution](https://docs.docker.com/compose/compose-file/compose-file-v2/#variable-substitution) page.
Finally, assign the credentials and run the server.
@@ -41,12 +41,12 @@ static-web-server \
## Exposed headers
The server also supports a list of [CORS exposed headers to scripts](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers) separated by commas.
The server also supports a list of [CORS-exposed headers to scripts](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Expose-Headers) separated by commas.
This feature depends on `--cors-allow-origins` to be used along with this feature. It can be controlled by the string `--cors-expose-headers` option or the equivalent [SERVER_CORS_EXPOSE_HEADERS](../configuration/environment-variables.md#server_cors_expose_headers) env.
!!! info "Tips"
- The default exposed headers value is `origin, content-type`.
- The default exposed header's is `origin, content-type`.
- The server also supports [preflight requests](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) via the `OPTIONS` method. See [Preflighted requests in CORS](./http-methods.md#preflighted-requests-in-cors).
Below is an example of how to CORS.
@@ -14,11 +14,11 @@ Each table entry should have two key/value pairs:
A particular set of HTTP headers can only be applied when a `source` matches against the request URI.
!!! info "Custom HTTP headers take precedence over existing ones"
Whatever custom HTTP header could **replace** an existing one if it was previously defined (E.g server default headers) and matches its `source`.
Whatever custom HTTP header could **replace** an existing one if it was previously defined (e.g. server default headers) and matches its `source`.
The headers order is important since it determines its precedence.
The header's order is important because determines its precedence.
**Example:** if the feature `--cache-control-headers=true` is enabled but also a custom `cache-control` header was defined then the custom header will have priority.
**Example:** If the feature `--cache-control-headers=true` is enabled but also a custom `cache-control` header was defined then the custom header will have priority.
### Source
@@ -114,7 +114,7 @@ static-web-server \
--directory-listing-format="json"
```
And below and client request example to illustrate how the feature works.
And below is a client request example to illustrate how the feature works.
```sh
curl -iH "content-type: application/json" http://localhost:8787
@@ -17,11 +17,11 @@ All Docker images are [Multi-Arch](https://www.docker.com/blog/how-to-rapidly-bu
- `linux/arm64`
!!! tip "SWS statically-linked binary"
All the Docker images use the SWS statically-linked binary, meaning that the binary is highly-optimized, performant, and dependency-free thanks to [musl libc](https://www.musl-libc.org/).
All the Docker images use the SWS statically-linked binary, meaning that the binary is highly optimized, performant, and dependency-free thanks to [musl libc](https://www.musl-libc.org/).
## Run a container
To give the server a quick try then just run the following commands.
To give the server a quick try just run the following commands.
!!! tip "Tips"
- [The SWS CLI arguments](../configuration/command-line-arguments.md) can be provided directly to the container or omitted as shown below.
@@ -19,7 +19,7 @@ static-web-server \
## Fallback Page for use with Client Routers
HTML file path that is used for `GET` requests when the requested path doesn't exist. The fallback page is served with a `200` status code, useful when using client routers like `React Router` or similar. If the path is not specified or simply doesn't exist then this feature will not be active.
An HTML file path that is used for `GET` requests when the requested path doesn't exist. The fallback page is served with a `200` status code, useful when using client routers like `React Router` or similar. If the path is not specified or simply doesn't exist then this feature will not be active.
It can be set with the `SERVER_FALLBACK_PAGE` environment variable or with the CLI argument `--page-fallback`.
@@ -79,7 +79,7 @@ sudo systemd-analyze security static-web-server.service
Alternatively, the lightweight [`systemfd`](https://github.com/mitsuhiko/systemfd) utility may be useful, especially for testing purposes.
For example, using `systemfd` utility as follow:
For example, using `systemfd` utility as follows:
```sh
sudo systemfd --no-pid -s http::8091 -- path/to/static-web-server --fd 0
@@ -24,5 +24,3 @@ Here is an example of delaying the graceful shutdown process by `10` seconds aft
```sh
static-web-server -p 8787 -d ./public/ -g trace --grace-period 10
```
@@ -7,9 +7,9 @@ The HTTP methods supported are `GET` and `HEAD`.
This feature is disabled by default and can be controlled by the boolean `--health` option or the equivalent [SERVER_HEALTH](./../configuration/environment-variables.md#health) env.
## Usage with kubernetes liveness probe
## Usage with Kubernetes liveness probe
The health endpoint is well suited for the kubernetes liveness probe:
The health endpoint is well suited for the Kubernetes liveness probe:
```yaml
apiVersion: v1
@@ -45,7 +45,7 @@ static-web-server -p 4433 -d public/ -g trace \
# --https-redirect-from-hosts = "localhost,127.0.0.1"
```
After running the server, the logs should look as follow.
After running the server, the logs should look as follows.
```log
.......
@@ -19,7 +19,7 @@ curl -I -X OPTIONS http://localhost:8787/assets/main.js
# date: Thu, 10 Mar 2022 21:26:01 GMT
```
### Preflighted requests in CORS
### Preflight requests in CORS
The HTTP [OPTIONS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/OPTIONS) method can also be used to send a request asking if it is acceptable to send requests to the server and if it is aware of using specific methods and headers.
@@ -1,6 +1,6 @@
# Ignore files
SWS provides some options to ignore files or directories from being served and displayed if the directory listing is enabled.
**`SWS`** provides some options to ignore files or directories from being served and displayed if the directory listing is enabled.
## Ignore hidden files (dotfiles)
@@ -25,7 +25,7 @@ We recommend a Powershell session with administrator privileges.
To install the SWS service use the `install` command along with a [configuration file](../configuration/config-file.md) for further SWS options customization.
Make sure to provide a configuration file to run SWS service properly. In particular, configure the server `address`, `port` and `root` directory accordingly.
If not so then the service might not start.
If not then the service might not start.
The following command will create the SWS service called `static-web-server` with a "`Static Web Server`" display name.
@@ -78,6 +78,6 @@ Cross-platform and available for `Linux`, `macOS`, `Windows`, `FreeBSD`, `NetBSD
<img title="SWS - Benchmarks April 2023" src="https://raw.githubusercontent.com/static-web-server/benchmarks/master/data/2023-04/benchmark-2023-04.png" width="860">
For more details see [benchmarks repository](https://github.com/static-web-server/benchmarks).
For more details see [the benchmarks repository](https://github.com/static-web-server/benchmarks).
For feedback or questions feel free to reach us on [the discussions page](https://github.com/static-web-server/static-web-server/discussions).
@@ -1,10 +1,10 @@
# Semantic Versioning
**`SWS`** project adheres to [Semantic Versioning](https://semver.org/) for every release like [`v1`](https://github.com/static-web-server/static-web-server/blob/1.x/CHANGELOG.md) and the latest [`v2`](https://github.com/static-web-server/static-web-server/blob/master/CHANGELOG.md).
**`SWS`** project adheres to [Semantic Versioning](https://semver.org/) (SemVer) for every release like [`v1`](https://github.com/static-web-server/static-web-server/blob/1.x/CHANGELOG.md) and the latest [`v2`](https://github.com/static-web-server/static-web-server/blob/master/CHANGELOG.md).
## Breaking changes
Only switches between ***major*** versions "could" contain *breaking changes* or not depending on the particular case.<br>
However, this project tries to keep away from any kind of _breaking change_ possible between ***major*** versions. But it still supports and prioritizes ***"no breaking changes"*** for ***minor*** and ***patch*** (bug fixes) versions.
On the other hand, if a *breaking change* is found to be *"strictly necessary"* to do. Then a new ***major*** version must be promoted as well as users informed accordingly so they can do a seamless transition.
On the other hand, if a *breaking change* is found to be *"strictly necessary"* to do. Then a new ***major*** version must be promoted as well and users informed accordingly so they can do a seamless transition.
@@ -59,7 +59,7 @@ theme:
font:
text: 'Open Sans'
code: 'Droid Sans Mono'
favicon: https://camo.githubusercontent.com/a08032a2db94aea229991af8f73c45cc95174c8066dc7a6b1f88a79c94cf1093/68747470733a2f2f75706c6f61642e77696b696d656469612e6f72672f77696b6970656469612f636f6d6d6f6e732f7468756d622f642f64352f527573745f70726f6772616d6d696e675f6c616e67756167655f626c61636b5f6c6f676f2e7376672f3130323470782d527573745f70726f6772616d6d696e675f6c616e67756167655f626c61636b5f6c6f676f2e7376672e706e67
favicon: https://static-web-server.net/assets/sws.svg
extra:
social:
