From 12387a88bbe018b5867997e0af6156c268b535c2 Mon Sep 17 00:00:00 2001 From: Matthias Schoettle Date: Sun, 1 Dec 2024 07:22:16 -0500 Subject: [PATCH] docs: improve docs configuration and fix anchor links (#504) * Fix anchor links in documentation * Move strict to mkdocs config * add mkdocs to CI --------- Co-authored-by: Jose Quintana <1700322+joseluisq@users.noreply.github.com> --- .github/workflows/devel.yml | 6 ++++++ docs/content/features/cors.md | 4 ++-- docs/content/features/health-endpoint.md | 2 +- docs/content/features/logging.md | 4 ++-- docs/content/features/trailing-slash-redirect.md | 2 +- docs/docker-compose.yml | 1 - docs/mkdocs.yml | 12 +++++++++++- 7 files changed, 23 insertions(+), 8 deletions(-) diff --git a/.github/workflows/devel.yml b/.github/workflows/devel.yml index d4992940..e517e83e 100644 --- a/.github/workflows/devel.yml +++ b/.github/workflows/devel.yml @@ -9,6 +9,7 @@ on: - .cargo/config.toml - Cargo.lock - Cargo.toml + - docs/** - src/** - tests/** push: @@ -19,6 +20,7 @@ on: - .cargo/config.toml - Cargo.lock - Cargo.toml + - docs/** - src/** - tests/** schedule: @@ -326,3 +328,7 @@ jobs: - name: Check crate docs run: | cargo doc --lib --no-deps + + - name: Check mkdocs + run: | + docker compose -f docs/docker-compose.yml run --rm server mkdocs build diff --git a/docs/content/features/cors.md b/docs/content/features/cors.md index 53d3976b..aa7c0c73 100644 --- a/docs/content/features/cors.md +++ b/docs/content/features/cors.md @@ -27,7 +27,7 @@ This feature depends on `--cors-allow-origins` to be used along with this featur !!! info "Tips" - The default allowed headers value is `origin, content-type, authorization`. - - 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). + - 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#preflight-requests-in-cors). Below is an example of how to CORS. @@ -47,7 +47,7 @@ This feature depends on `--cors-allow-origins` to be used along with this featur !!! info "Tips" - 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). + - 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#preflight-requests-in-cors). Below is an example of how to CORS. diff --git a/docs/content/features/health-endpoint.md b/docs/content/features/health-endpoint.md index 3d34c91d..ef7b23c2 100644 --- a/docs/content/features/health-endpoint.md +++ b/docs/content/features/health-endpoint.md @@ -5,7 +5,7 @@ When the `/health` is requested, SWS will generate a log only at the `debug` le 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. +This feature is disabled by default and can be controlled by the boolean `--health` option or the equivalent [SERVER_HEALTH](../configuration/environment-variables.md#server_health) env. ## Usage with Kubernetes liveness probe diff --git a/docs/content/features/logging.md b/docs/content/features/logging.md index dd100ab7..41202661 100644 --- a/docs/content/features/logging.md +++ b/docs/content/features/logging.md @@ -48,11 +48,11 @@ When used behind a reverse proxy the reported `remote_addr` indicates the proxie The Proxy server can be configured to provide the [X-Forwarded-For header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For), containing a comma-separated list of IP addresses, starting with the *real remote client IP*, and all following intermediate proxies (if any). -To enable logging of the real remote IP, enable the `--log-forwarded-for` option or the equivalent [SERVER_LOG_FORWARDED_FOR](/docs/content/configuration/environment-variables.md#serverlogforwardedfor) env. By default this will log all requests which have a correctly formatted `X-Forwarded-For` header. +To enable logging of the real remote IP, enable the `--log-forwarded-for` option or the equivalent [SERVER_LOG_FORWARDED_FOR](../configuration/environment-variables.md#server_log_forwarded_for) env. By default this will log all requests which have a correctly formatted `X-Forwarded-For` header. Since the content of the `X-Forwarded-For` header can be changed by all proxies in the chain, the remote IP address reported may not be trusted. -To restrict the logging to only trusted proxy IPs, you can use the `--trusted-proxies` option, or the equivalent [SERVER_TRUSTED_PROXIES](/docs/content/configuration/environment-variables.md#servertrustedproxies) env. This should be a list of IPs, separated by commas. An empty list (the default) indicates that all IPs should be trusted. +To restrict the logging to only trusted proxy IPs, you can use the `--trusted-proxies` option, or the equivalent [SERVER_TRUSTED_PROXIES](../configuration/environment-variables.md#server_trusted_proxies) env. This should be a list of IPs, separated by commas. An empty list (the default) indicates that all IPs should be trusted. Command used for the following examples: ```sh diff --git a/docs/content/features/trailing-slash-redirect.md b/docs/content/features/trailing-slash-redirect.md index a0e99ba6..30d52179 100644 --- a/docs/content/features/trailing-slash-redirect.md +++ b/docs/content/features/trailing-slash-redirect.md @@ -2,7 +2,7 @@ **`SWS`** provides automatic trailing slash redirect support for directory requests. -This feature is enabled by default and can be controlled by the boolean `--redirect-trailing-slash` option or the equivalent [SERVER_REDIRECT_TRAILING_SLASH](./../configuration/environment-variables.md#redirect_trailing_slash) env. +This feature is enabled by default and can be controlled by the boolean `--redirect-trailing-slash` option or the equivalent [SERVER_REDIRECT_TRAILING_SLASH](../configuration/environment-variables.md#server_redirect_trailing_slash) env. ```sh static-web-server \ diff --git a/docs/docker-compose.yml b/docs/docker-compose.yml index 373ce172..92560f94 100644 --- a/docs/docker-compose.yml +++ b/docs/docker-compose.yml @@ -1,4 +1,3 @@ -version: "3.3" services: server: container_name: static-web-server-docs diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 2a769b8c..f9bd997f 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -3,13 +3,13 @@ site_name: Static Web Server site_description: 'A cross-platform, high-performance and asynchronous web server for static files-serving ⚡' site_author: 'Jose Quintana' site_url: https://static-web-server.net -dev_addr: 0.0.0.0:8000 # Repository repo_name: static-web-server/static-web-server repo_url: https://github.com/static-web-server/static-web-server/ edit_uri: edit/master/docs/content/ +strict: true docs_dir: 'docs/content' site_dir: '/tmp/docs' extra_css: @@ -175,3 +175,13 @@ nav: - 'Report Security Issues': 'report-security-issues.md' - 'Contributions': 'contributions.md' - 'License': 'license.md' + +not_in_nav: | + download-and-install.template.md + +# https://www.mkdocs.org/user-guide/configuration/#validation +validation: + omitted_files: warn + absolute_links: warn + unrecognized_links: warn + anchors: warn