From ddbf8811d2cebac6786290d4ec833333606a057a Mon Sep 17 00:00:00 2001 From: Jose Quintana Date: Mon, 2 Oct 2023 06:47:20 +0200 Subject: [PATCH] docs: improve page content [skip ci] --- 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(-) diff --git a/docs/content/configuration/command-line-arguments.md b/docs/content/configuration/command-line-arguments.md index a2c5ba7..cea36a4 100644 --- a/docs/content/configuration/command-line-arguments.md +++ b/docs/content/configuration/command-line-arguments.md @@ -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 diff --git a/docs/content/configuration/config-file.md b/docs/content/configuration/config-file.md index bf06dc3..0e8362e 100644 --- a/docs/content/configuration/config-file.md +++ b/docs/content/configuration/config-file.md @@ -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 diff --git a/docs/content/features/basic-authentication.md b/docs/content/features/basic-authentication.md index 8ebb7ea..da025b7 100644 --- a/docs/content/features/basic-authentication.md +++ b/docs/content/features/basic-authentication.md @@ -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.
- 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. diff --git a/docs/content/features/cors.md b/docs/content/features/cors.md index 5233570..1c91901 100644 --- a/docs/content/features/cors.md +++ b/docs/content/features/cors.md @@ -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. diff --git a/docs/content/features/custom-http-headers.md b/docs/content/features/custom-http-headers.md index 4b24efa..8740f50 100644 --- a/docs/content/features/custom-http-headers.md +++ b/docs/content/features/custom-http-headers.md @@ -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 diff --git a/docs/content/features/directory-listing.md b/docs/content/features/directory-listing.md index fc630ae..3f82f90 100644 --- a/docs/content/features/directory-listing.md +++ b/docs/content/features/directory-listing.md @@ -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 diff --git a/docs/content/features/docker.md b/docs/content/features/docker.md index 6b5d246..92d06a1 100644 --- a/docs/content/features/docker.md +++ b/docs/content/features/docker.md @@ -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. diff --git a/docs/content/features/error-pages.md b/docs/content/features/error-pages.md index d8b7d0f..94f9931 100644 --- a/docs/content/features/error-pages.md +++ b/docs/content/features/error-pages.md @@ -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`. diff --git a/docs/content/features/file-descriptor-socket-passing.md b/docs/content/features/file-descriptor-socket-passing.md index 4949cdd..1c6e869 100644 --- a/docs/content/features/file-descriptor-socket-passing.md +++ b/docs/content/features/file-descriptor-socket-passing.md @@ -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 diff --git a/docs/content/features/graceful-shutdown.md b/docs/content/features/graceful-shutdown.md index f20cbad..8e1c08d 100644 --- a/docs/content/features/graceful-shutdown.md +++ b/docs/content/features/graceful-shutdown.md @@ -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 ``` - - diff --git a/docs/content/features/health-endpoint.md b/docs/content/features/health-endpoint.md index 7588836..3d34c91 100644 --- a/docs/content/features/health-endpoint.md +++ b/docs/content/features/health-endpoint.md @@ -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 diff --git a/docs/content/features/http-https-redirect.md b/docs/content/features/http-https-redirect.md index e67d4a4..7544d26 100644 --- a/docs/content/features/http-https-redirect.md +++ b/docs/content/features/http-https-redirect.md @@ -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 ....... diff --git a/docs/content/features/http-methods.md b/docs/content/features/http-methods.md index 8b7a9c9..68972dd 100644 --- a/docs/content/features/http-methods.md +++ b/docs/content/features/http-methods.md @@ -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. diff --git a/docs/content/features/ignore-files.md b/docs/content/features/ignore-files.md index d86067f..39e3d32 100644 --- a/docs/content/features/ignore-files.md +++ b/docs/content/features/ignore-files.md @@ -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) diff --git a/docs/content/features/windows-service.md b/docs/content/features/windows-service.md index fe9f93b..d3e59f6 100644 --- a/docs/content/features/windows-service.md +++ b/docs/content/features/windows-service.md @@ -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. diff --git a/docs/content/index.md b/docs/content/index.md index c73167b..7f6d4b5 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -78,6 +78,6 @@ Cross-platform and available for `Linux`, `macOS`, `Windows`, `FreeBSD`, `NetBSD -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). diff --git a/docs/content/semantic-versioning.md b/docs/content/semantic-versioning.md index d8cfaaa..2cc427a 100644 --- a/docs/content/semantic-versioning.md +++ b/docs/content/semantic-versioning.md @@ -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.
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. diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 1365499..455f0bb 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -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: -- libgit2 1.7.2