chore: only have the guide as the sole source of truth for the docs

guide/book.toml

@@ -16,7 +16,7 @@ edition = "2021"
 
 [preprocessor.admonish]
 command = "mdbook-admonish"
-assets_version = "3.0.2" # do not edit: managed by `mdbook-admonish install`
+assets_version = "3.0.3" # do not edit: managed by `mdbook-admonish install`
 
 [output.html]
 git-repository-url = "https://github.com/trunk-rs/trunk"

guide/src/configuration/index.md

@@ -111,3 +111,132 @@ This also supports pre-release requirements, which allows adopting upcoming feat
 Versions prior do `0.19.0-alpha.2` currently do not support this check, and so they will silently ignore
 such an error for now.
 ```
+
+## Build section
+
+The build section has configuration settings for the build process. These
+control the arguments passed to Cargo when building the application, and the
+generation of the assets.
+
+```toml
+[build]
+target = "index.html"       # The index HTML file to drive the bundling process.
+html_output = "index.html"  # The name of the output HTML file.
+release = false             # Build in release mode.
+dist = "dist"               # The output dir for all final assets.
+public_url = "/"            # The public URL from which assets are to be served.
+filehash = true             # Whether to include hash values in the output file names.
+inject_scripts = true       # Whether to inject scripts (and module preloads) into the finalized output.
+offline = false             # Run without network access
+frozen = false              # Require Cargo.lock and cache are up to date
+locked = false              # Require Cargo.lock is up to date
+minify = "never"            # Control minification: can be one of: never, on_release, always
+no_sri = false              # Allow disabling sub-resource integrity (SRI)
+```
+
+## Watch section
+
+Trunk has built-in support for watching for source file changes, which triggers
+a rebuild and a refresh in the browser. In this section, you can override what
+paths to watch and set files to be ignored.
+
+```toml
+[watch]
+watch = []  # Paths to watch. The `build.target`'s parent folder is watched by default.
+ignore = [] # Paths to ignore.
+```
+
+## Server section
+
+Trunk has a built-in server for serving the application when running `trunk serve`.
+This section lets you override how this works.
+
+```toml
+[serve]
+addresses = ["127.0.0.1"]  # The address to serve on.
+port = 8080                # The port to serve on.
+aliases = ["http://localhost.mywebsite.com"] # The aliases to serve on.
+open = false               # Open a browser tab once the initial build is complete.
+no_spa = false             # Whether to disable fallback to index.html for missing files.
+no_autoreload = false      # Disable auto-reload of the web app.
+no_error_reporting = false # Disable error reporting
+ws_protocol = "ws"         # Protocol used for autoreload WebSockets connection.
+# Additional headers set for responses.
+headers = { "test-header" = "header value", "test-header2" = "header value 2" }
+# The certificate/private key pair to use for TLS, which is enabled if both are set.
+tls_key_path = "self_signed_certs/key.pem"
+tls_cert_path = "self_signed_certs/cert.pem"
+```
+
+## Clean section
+
+The clean section controls the behaviour when running `trunk clean`, which will
+remove build artifacts.
+
+```toml
+[clean]
+dist = "dist" # The output dir for all final assets.
+cargo = false # Optionally perform a cargo clean.
+```
+
+## Proxy section
+
+The `Trunk.toml` config file accepts multiple `[[proxy]]` sections, which
+allows for multiple proxies to be configured. Each section requires at least
+the `backend` field, and optionally accepts the `rewrite` and `ws` fields, both
+corresponding to the `--proxy-*` CLI flags discussed below.
+
+As it is with other Trunk config, a proxy declared via CLI will take final
+precedence and will cause any config file proxies to be ignored, even if there
+are multiple proxies declared in the config file.
+
+```toml
+[[proxy]]
+backend = "https://localhost:9000/api/v1" # Address to proxy requests to
+ws = false                                # Use WebSocket for this proxy
+insecure = false                          # Disable certificate validation
+no_system_proxy = false                   # Disable system proxy
+rewrite = ""                              # Strip the given prefix off paths
+no_redirect = false                       # Disable following redirects of proxy responses
+```
+
+## Hooks section
+
+Hooks are tasks that are run before, during or after the build. You can run
+arbitrary commands here, and you can specify multiple hooks to run.
+
+```toml
+[[hooks]]
+stage = "post_build"  # When to run hook, must be one of "pre_build", "build", "post_build"
+command = "ls"        # Command to run
+command_arguments = [] # Arguments to pass to command
+```
+
+# Environment Variables
+
+Trunk environment variables mirror the `Trunk.toml` config schema. All Trunk environment variables have the following 3 part form `TRUNK_<SECTION>_<ITEM>`, where `TRUNK_` is the required prefix, `<SECTION>` is one of the `Trunk.toml` sections, and `<ITEM>` is a specific configuration item from the corresponding section. E.G., `TRUNK_SERVE_PORT=80` will cause `trunk serve` to listen on port `80`. The equivalent CLI invocation would be `trunk serve --port=80`.
+
+In addition, there is the variable `TRUNK_SKIP_VERSION_CHECK` which allows to control the update check (if that is)
+compiled into the version of trunk.
+
+# CLI Arguments & Options
+
+The final configuration layer is the CLI itself. Any arguments / options provided on the CLI will take final precedence over any other config layer.
+
+# Proxy
+
+Trunk ships with a built-in proxy which can be enabled when running `trunk serve`. There are two ways to configure the proxy, each discussed below. All Trunk proxies will transparently pass along the request body, headers, and query parameters to the proxy backend.
+
+## Proxy CLI Flags
+
+The `trunk serve` command accepts two proxy related flags.
+
+`--proxy-backend` specifies the URL of the backend server to which requests should be proxied. The URI segment of the given URL will be used as the path on the Trunk server to handle proxy requests. E.G., `trunk serve --proxy-backend=http://localhost:9000/api/` will proxy any requests received on the path `/api/` to the server listening at `http://localhost:9000/api/`. Further path segments or query parameters will be seamlessly passed along.
+
+`--proxy-rewrite` specifies an alternative URI on which the Trunk server is to listen for proxy requests. Any requests received on the given URI will be rewritten to match the URI of the proxy backend, effectively stripping the rewrite prefix. E.G., `trunk serve --proxy-backend=http://localhost:9000/ --proxy-rewrite=/api/` will proxy any requests received on `/api/` over to `http://localhost:9000/` with the `/api/` prefix stripped from the request, while everything following the `/api/` prefix will be left unchanged.
+
+`--proxy-insecure` allows the `--proxy-backend` url to use a self signed certificate for https (or any officially [invalid](https://docs.rs/reqwest/latest/reqwest/struct.ClientBuilder.html#method.danger_accept_invalid_certs) certs, including expired). This would be used when proxying to https such as `trunk serve --proxy-backend=https://localhost:3001/ --proxy-insecure` where the ssl cert was self signed, such as with [mkcert](https://github.com/FiloSottile/mkcert), and routed through an https reverse proxy for the backend, such as [local-ssl-proxy](https://github.com/cameronhunter/local-ssl-proxy) or [caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy).
+
+`--proxy-no-sytem-proxy` bypasses the system proxy when contacting the proxy backend.
+
+`--proxy-ws` specifies that the proxy is for a WebSocket endpoint.

site/config.toml

@@ -20,3 +20,6 @@ juice_extra_menu = [
     { title = "Guide", link = "https://trunkrs.dev/guide"},
     { title = "GitHub", link = "https://github.com/trunk-rs/trunk"}
 ]
+
+# hide these ad they have moved
+juice_exclude_menu = [ "Advanced", "Assets", "Commands", "Configuration" ]

site/content/_index.md

@@ -5,72 +5,7 @@ sort_by = "weight"
 
 Trunk is a WASM web application bundler for Rust. Trunk uses a simple, optional-config pattern for building & bundling WASM, JS snippets & other assets (images, css, scss) via a source HTML file.
 
-# Getting Started
-
-## Install
-
-First, install Trunk via one of the following options.
-
-### Plain cargo
-
-Download the sources and build them yourself:
-
-```bash
-cargo install --locked trunk
-```
-
-You can also toggle some features using the `--features` flag:
-
-<dl>
-<dt><code>rustls</code></dt><dd>Use rustls for client and server sockets</dd>
-<dt><code>native-tls</code> (default)</dt><dd>Enable the use of the system native TLS stack for client sockets, and `openssl` for server sockets</dd>
-<dt><code>update_check</code> (default)</dt><dd>Enable the update check on startup</dd>
-</dl>
-
-**NOTE:** If both `rustls` and `native-tls` are enabled, `rustls` will be used. You can disable the default `rustls` using
-`--no-default-features`.
-
-### Cargo binstall
-
-You can download a released binary from GitHub releases through [`binstall`](https://github.com/cargo-bins/cargo-binstall).
-
-```bash
-cargo binstall trunk
-```
-
-### GitHub release download
-
-Fetch and unpack a released binary from the [release page](https://github.com/trunk-rs/trunk/releases).
-
-For example (be sure to check for the most recent version):
-
-```bash
-wget -qO- https://github.com/trunk-rs/trunk/releases/download/0.17.10/trunk-x86_64-unknown-linux-gnu.tar.gz | tar -xzf-
-```
-
-### NixOS
-
-```bash
-nix-env -i trunk
-```
-
-### Brew
-
-```bash
-brew install trunk
-```
-
-## Additional tools
-
-Any additional tools like `wasm-bindgen` and `wasm-opt` are automatically downloaded and managed by trunk. Therefore, no further steps required 🎉.
-
-**Note:** Until `wasm-bindgen` has pre-built binaries for Apple M1, M1 users will need to install `wasm-bindgen` manually.
-
-```bash
-cargo install --locked wasm-bindgen-cli
-```
-
-## App Setup
+# Motivation
 
 Any `wasm-bindgen`-based framework will work with Trunk. If you're new to [frontend development in Rust][], [Yew][] and [Leptos][] are two popular options.
 
@@ -122,15 +57,9 @@ dispatchEvent(new CustomEvent("TrunkApplicationStarted", {detail: {wasm}}));
 
 The contents of your `dist` dir are now ready to be served on the web.
 
-# Next Steps
-
-That's not all! Trunk has even more useful features. Head on over to the following sections to learn more about how to use Trunk effectively.
+# Installing
 
-- [Assets](@/assets.md): learn about all of Trunk's supported asset types.
-- [Configuration](@/configuration.md): learn about Trunk's configuration system and how to use the Trunk proxy.
-- [Commands](@/commands.md): learn about Trunk's CLI commands for use in your development workflows.
-- [Advanced topics](@/advanced.md): learn about some more advanced topics.
-- Join us on Discord by following this link [![](https://img.shields.io/discord/793890238267260958?logo=discord&style=flat-square "Discord Chat")](https://discord.gg/JEPdBujTDr)
+Please refer to the [guide](https://trunkrs.dev/guide).
 
 # Contributing
 

site/content/advanced.md

@@ -3,124 +3,4 @@ title = "Advanced"
 description = "Advanced topics"
 weight = 4
 +++
-
-## JavaScript interoperability
-
-Trunk will create the necessary JavaScript code to bootstrap and run the WebAssembly based application. It will also
-include all JavaScript snippets generated by `wasm-bindgen` for interfacing with JavaScript functionality.
-
-By default, functions exported from Rust, using `wasm-bingen`, can be accessed in the JavaScript code through the global
-variable `window.wasmBindings`. This behavior can be disabled, and the name can be customized. For more information
-see the [`rust` asset type](@/assets.md#rust).
-
-## Library crate
-
-Aside from having a `main` function, it is also possible to up your project as a `cdylib` project. In order to do that,
-add the following to your `Cargo.toml`:
-
-```toml
-[lib]
-crate-type = ["cdylib", "rlib"]
-```
-
-And then, define the entrypoint in your `lib.rs` like (does not need to be `async`):
-
-```rust
-#[wasm_bindgen(start)]
-pub async fn run() {}
-```
-
-## Initializer
-
-Since: `0.19.0-alpha.1`.
-
-Trunk supports tapping into the initialization process of the WASM application. By
-default, this is not active and works the same way as with previous versions.
-
-The default process is that trunk injects a small JavaScript snippet, which imports the JavaScript loader generated
-by `wasm_bindgen` and calls the `init` method. That will fetch the WASM blob and run it.
-
-The downside with is, that during this process, there's no feedback to the user. Neither when it takes a bit longer to
-load the WASM file, nor when something goes wrong.
-
-Now it is possible to tap into this process by setting `data-initializer` to a JavaScript module file. This module file
-is required to (default) export a function, which returns the "initializer" instance. Here is an example:
-
-```javascript
-export default function myInitializer () {
-  return {
-    onStart: () => {
-      // called when the loading starts
-    },
-    onProgress: ({current, total}) => {
-      // the progress while loading, will be called periodically.
-      // "current" will contain the number of bytes of the WASM already loaded
-      // "total" will either contain the total number of bytes expected for the WASM, or if the server did not provide
-      //   the content-length header it will contain 0.
-    },
-    onComplete: () => {
-      // called when the initialization is complete (successfully or failed)
-    },
-    onSuccess: (wasm) => {
-      // called when the initialization is completed successfully, receives the `wasm` instance
-    },
-    onFailure: (error) => {
-      // called when the initialization is completed with an error, receives the `error`
-    }
-  }
-};
-```
-
-For a full example, see: <https://github.com/trunk-rs/trunk/tree/main/examples/initializer>.
-
-## Update check
-
-Since: `0.19.0-alpha.2`.
-
-Trunk has an update check built in. By default, it will check the `trunk` crate on `crates.io` for a newer
-(non pre-release) version. If one is found, the information will be shown in the command line.
-
-This check can be disabled entirely, but not enabled the cargo feature `update_check`. It can also be disabled during
-runtime using the environment variable `TRUNK_SKIP_VERSION_CHECK`, or using the command line switch
-`--skip-version-check`.
-
-The check is only performed every 24 hours.
-
-## Base URLs, public URLs, paths & reverse proxies
-
-Since: `0.19.0-alpha.3`.
-
-Originally `trunk` had a single `--public-url`, which allowed to set the base URL of the hosted application.
-Plain and simple. This was a prefix for all URLs generated and acted as a base for `trunk serve`.
-
-Unfortunately, life isn't that simple and naming is hard.
-
-Today `trunk` was three paths:
-
-* The "public base URL": acting as a prefix for all generated URLs
-* The "serve base": acting as a scope/prefix for all things served by `trunk serve`
-* The "websocket base": acting as a base path for the auto-reload websocket
-
-All three can be configured, but there are reasonable defaults in place. By default, the serve base and websocket base
-default to the absolute path of the public base. The public base will have a slash appended if it doesn't have one. The
-public base can be one of:
-
-* Unset/nothing/default (meaning `/`)
-* An absolute URL (e.g. `http://domain/path/app`)
-* An absolute path (e.g. `/path/app`)
-* A relative path (e.g. `foo` or `./`)
-
-If the public base is an absolute URL, then the path of that URL will be used as serve and websocket base. If the public
-base is a relative path, then it will be turned into an absolute one. Both approaches might result in a dysfunctional
-application, based on your environment. There will be a warning on the console. However, by providing an explicit
-value using serve-base or ws-base, this can be fixed.
-
-Why is this necessary and when is it useful? It's mostly there to provide all the knobs/configurations for the case
-that weren't considered. The magic of public-url worked for many, but not for all. To support such cases, it
-is now possible to tweak all the settings, at the cost of more complexity. Having reasonable defaults should keep it
-simple for the simple cases.
-
-An example use case is a reverse proxy *in front* of `trunk serve`, which can't be configured to serve the trunk
-websocket at the location `trunk serve` expects it. Now, it is possible to have `--public-url` to choose the base when
-generating links, so that it looks correct when being served by the proxy. But also use `--serve-base /` to keep
-serving resource from the root.
+{{ redirect_to_guide() }}