Skip to content

Commit

Permalink
Revert markdown formatting but keep spelling fixes and updated docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@Tanja-4732
Tanja-4732 committed Apr 6, 2021
1 parent 0e9025a commit f72448a
Show file tree
Hide file tree
Showing 5 changed files with 20 additions and 68 deletions.
26 changes: 8 additions & 18 deletions site/content/_index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,8 @@ 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.

```bash
# Install via homebrew on Mac, Linux or Windows (WSL).
brew install trunk
Expand All @@ -22,25 +19,22 @@ wget -qO- https://github.com/thedodd/trunk/releases/download/${VERSION}/trunk-x8
# Install via cargo.
cargo install --locked trunk
```

<small>Release binaries can be found on the [Github releases page](https://github.com/thedodd/trunk/releases).</small>

Next, we will need to install `wasm-bindgen-cli`. In the future Trunk will handle this for you.

```zsh
```sh
cargo install wasm-bindgen-cli
```

If using wasm-opt, we will need to install `wasm-opt` which is part of `binaryen`. On MacOS we can install it with Homebrew:

```zsh
```sh
brew install binaryen
```

Some linux distributions provide a `binaryen` package in their package managers but if it's not available, outdated or you're on Windows, then we can grab a [pre-compiled release](https://github.com/WebAssembly/binaryen/releases), extract it and put the `wasm-opt` binary in some location that's available on the PATH.

## App Setup

Get setup with your favorite `wasm-bindgen` based framework. [Yew](https://github.com/yewstack/yew) & [Seed](https://github.com/seed-rs/seed) are the most popular options today, but there are others. Trunk will work with any `wasm-bindgen` based framework. The easiest way to ensure that your application launches properly is to [setup your app as an executable](https://doc.rust-lang.org/cargo/guide/project-layout.html) with a standard `main` function:

```rust
Expand All @@ -54,7 +48,7 @@ Trunk uses a source HTML file to drive all asset building and bundling. Trunk al
```html
<html>
<head>
<link data-trunk rel="scss" href="path/to/index.scss" />
<link data-trunk rel="scss" href="path/to/index.scss"/>
</head>
</html>
```
Expand All @@ -64,10 +58,10 @@ Trunk uses a source HTML file to drive all asset building and bundling. Trunk al
```html
<html>
<head>
<link rel="stylesheet" href="/index.700471f89cef12e4.css" />
<link rel="stylesheet" href="/index.700471f89cef12e4.css">
<script type="module">
import init from "/index-719b4e04e016028b.js";
init("/index-719b4e04e016028b_bg.wasm");
import init from '/index-719b4e04e016028b.js';
init('/index-719b4e04e016028b_bg.wasm');
</script>
</head>
</html>
Expand All @@ -76,21 +70,17 @@ Trunk uses a source HTML file to drive all asset building and bundling. Trunk al
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.

- [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.

# Contributing

Anyone and everyone is welcome to contribute! Please review the [CONTRIBUTING.md](https://github.com/thedodd/trunk/blob/master/CONTRIBUTING.md) document for more details. The best way to get started is to find an open issue, and then start hacking on implementing it. Letting other folks know that you are working on it, and sharing progress is a great approach. Open pull requests early and often, and please use Github's draft pull request feature.
# Contributing
Anyone and everyone is welcome to contribute! Please review the [CONTRIBUTING.md](https://github.com/thedodd/trunk/blob/master/CONTRIBUTING.md) document for more details. The best way to get started is to find an open issue, and then start hacking on implementing it. Letting other folks know that you are working on it, and sharing progress is a great approach. Open pull requests early and often, and please use GitHub's draft pull request feature.

# License

<!-- TODO remove this `p` tag -->

<p>
<span><img src="https://img.shields.io/badge/license-MIT%2FApache--2.0-blue?style=flat-square"/></span>
<br/>
Expand Down
37 changes: 9 additions & 28 deletions site/content/assets.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,79 +5,60 @@ weight = 1
+++

Declaring assets to be processed by Trunk is simple and extensible. All assets to be processed by Trunk must follow these three rules:

- Must be declared as a valid HTML `link` tag.
- Must have the attribute `data-trunk`.
- Must have the attribute `rel="{type}"`, where `{type}` is one of the asset types listed below.

This will typically look like: `<link data-trunk rel="{type}" href="{path}" ..other options here.. />`. Each asset type described below specifies the required and optional attributes for its asset type. All `<link data-trunk .../>` HTML elements will be replaced with the output HTML of the associated pipeline.

# Asset Types

## rust

✅ `rel="rust"`: Trunk will compile the specified Cargo project as the main WASM application. This is optional. If not specified, Trunk will look for a `Cargo.toml` in the parent directory of the source HTML file.

- `href`: (optional) the path to the `Cargo.toml` of the Rust project. If a directory is specified, then Trunk will look for the `Cargo.toml` in the given directory. If no value is specified, then Trunk will look for a `Cargo.toml` in the parent directory of the source HTML file.
- `data-bin`: (optional) the name of the binary to compile and use as the main WASM application. If the Cargo project has multiple binaries, this value will be required for proper functionality.
- `data-wasm-opt`: (optional) run wasm-opt with the set optimization level. wasm-opt is **turned off by default** but that may change in the future. The possible values are `0`, `1`, `2`, `3`, `4`, `s`, `z` or an _empty value_ for wasm-opt's default. Set this option to `0` to disable wasm-opt explicitly. The values `1-4` are increasingly stronger optimization levels for speed. `s` and `z` (z means more optimization) optimize for binary size instead.
- `data-keep-debug`: (optional) instruct `wasm-bindgen` to preserve debug info in the final WASM output, even for `--release` mode.
- `data-no-demangle`: (optional) instruct `wasm-bindgen` to not demangle Rust symbol names.
- `href`: (optional) the path to the `Cargo.toml` of the Rust project. If a directory is specified, then Trunk will look for the `Cargo.toml` in the given directory. If no value is specified, then Trunk will look for a `Cargo.toml` in the parent directory of the source HTML file.
- `data-bin`: (optional) the name of the binary to compile and use as the main WASM application. If the Cargo project has multiple binaries, this value will be required for proper functionality.
- `data-wasm-opt`: (optional) run wasm-opt with the set optimization level. wasm-opt is **turned off by default** but that may change in the future. The possible values are `0`, `1`, `2`, `3`, `4`, `s`, `z` or an _empty value_ for wasm-opt's default. Set this option to `0` to disable wasm-opt explicitly. The values `1-4` are increasingly stronger optimization levels for speed. `s` and `z` (z means more optimization) optimize for binary size instead.
- `data-keep-debug`: (optional) instruct `wasm-bindgen` to preserve debug info in the final WASM output, even for `--release` mode.
- `data-no-demangle`: (optional) instruct `wasm-bindgen` to not demangle Rust symbol names.

## sass/scss

✅ `rel="sass"` or `rel="scss"`: Trunk ships with a [built-in sass/scss compiler](https://github.com/compass-rs/sass-rs). Just link to your sass files from your source HTML, and Trunk will handle the rest. This content is hashed for cache control. The `href` attribute must be included in the link pointing to the sass/scss file to be processed.

- `data-inline`: (optional) this attribute will inline the compiled CSS from the SASS/SCSS fille into a `<style>` tag instead of using a `<link rel="stylesheet">` tag

## css

✅ `rel="css"`: Trunk will copy linked css files found in the source HTML without content modification. This content is hashed for cache control. The `href` attribute must be included in the link pointing to the css file to be processed.

- In the future, Trunk will resolve local `@imports`, will handle minification (see [trunk#7](https://github.com/thedodd/trunk/issues/3)), and we may even look into a pattern where any CSS found in the source tree will be bundled, which would enable a nice zero-config "component styles" pattern. See [trunk#3](https://github.com/thedodd/trunk/issues/3) for more details.
- In the future, Trunk will resolve local `@imports`, will handle minification (see [trunk#7](https://github.com/thedodd/trunk/issues/3)), and we may even look into a pattern where any CSS found in the source tree will be bundled, which would enable a nice zero-config "component styles" pattern. See [trunk#3](https://github.com/thedodd/trunk/issues/3) for more details.

## icon

✅ `rel="icon"`: Trunk will copy the icon image specified in the `href` attribute to the `dist` dir. This content is hashed for cache control.

## inline

✅ `rel="inline"`: Trunk will inline the content of the file specified in the `href` attribute into `index.html`. This content is copied exactly, no hashing is performed.

- `type`: (optional) either `html`, `css`, or `js`. If not present, the type is inferred by the file extension. `css` is wrapped in `style` tags, while
- `type`: (optional) either `html`, `css`, or `js`. If not present, the type is inferred by the file extension. `css` is wrapped in `style` tags, while
`js` is wrapped in `script` tags.

## copy-file

✅ `rel="copy-file"`: Trunk will copy the file specified in the `href` attribute to the `dist` dir. This content is copied exactly, no hashing is performed.

## copy-dir

✅ `rel="copy-dir"`: Trunk will recursively copy the directory specified in the `href` attribute to the `dist` dir. This content is copied exactly, no hashing is performed.

## rust-worker

⏳ `rel="rust-worker"`: (in-progress) Trunk will compile the specified Rust project as a WASM web worker. The following attributes are required:

- `href`: (optional) the path to the `Cargo.toml` of the Rust project. If a directory is specified, then Trunk will look for the `Cargo.toml` in the given directory. If no value is specified, then Trunk will look for a `Cargo.toml` in the parent directory of the source HTML file.
- `data-bin`: (optional) the name of the binary to compile and use as the web worker. If the Cargo project has multiple binaries, this value will be required for proper functionality.
- `href`: (optional) the path to the `Cargo.toml` of the Rust project. If a directory is specified, then Trunk will look for the `Cargo.toml` in the given directory. If no value is specified, then Trunk will look for a `Cargo.toml` in the parent directory of the source HTML file.
- `data-bin`: (optional) the name of the binary to compile and use as the web worker. If the Cargo project has multiple binaries, this value will be required for proper functionality.

Trunk is still a young project, and new asset types will be added as we move forward. Keep an eye on [trunk#3](https://github.com/thedodd/trunk/issues/3) for more information on planned asset types, implementation status, and please contribute to the discussion if you think something is missing.

# JS Snippets

JS snippets generated from the [wasm-bindgen JS snippets feature](https://rustwasm.github.io/docs/wasm-bindgen/reference/js-snippets.html) are automatically copied to the dist dir, hashed and ready to rock. No additional setup is required. Just use the feature in your application, and Trunk will take care of the rest.

# Images & Other Resources

Images and other resource types can be copied into the `dist` dir by adding a link like this to your source HTML: `<link data-trunk rel="copy-file" href="path/to/image"/>`. Any normal file type is supported. This will cause Trunk to find the target resource, and copy it to the `dist` dir unmodified. No hashing will be applied. The link itself will be removed from the HTML. To copy an entire directory of assets/images, you can use the following HTML: `<link data-trunk rel="copy-dir" href="path/to/images-dir"/>`.

This will allow your WASM application to reference images directly from the `dist` dir, and Trunk will ensure that the images are available in the `dist` dir to be served.

**NOTE:** as Trunk continues to mature, we will find better ways to include images and other resources. Hashing content for cache control is great, we just need to find a nice pattern to work with images referenced in Rust components. Please contribute to the discussion over in [trunk#9](https://github.com/thedodd/trunk/issues/9)! See you there.

# Directives

You can instruct Trunk to write the URL passed to `--public-url` to the HTML output by adding this to your `<head>`: `<base data-trunk-public-url/>`.

Trunk will set the `href` attribute of the element to the public URL. This changes the behavior of relative URLs to be relative to the public URL instead of the current location.
Expand Down
6 changes: 1 addition & 5 deletions site/content/blog/2021-02-03-release-0_8_0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,6 @@ author = "Doddzilla"
Hello fellow Rustaceans! Welcome to the very first official blog post of the Trunk community. In case you don't know, Trunk is a WASM web application bundler for Rust. It works out of the box with any web UI framework based on `wasm-bindgen`, and supports bundling of a good number of asset types including SASS/SCSS, CSS, JS snippets, images, and more. There's a lot to cover here, so let's dig in.

# New Site & New Blog

First off, if you are reading this blog post, then you've found our new Trunk website. All of our documentation is here, and the maintainers team plans on continuing to expand this site, adding new documentation and improving the site as we go. This is a community driven website, so if you see things which you would like to improve, content you would like to add (including new blog posts), or any other sorts of changes, please open a PR! Just to make that process even easier, let's talk about how the site is built.

We are using the excellent [Zola static site engine](https://getzola.org). It is another great Rust project. Putting together this entire site from nothing took only a few hours. Sure there's not too much here, but the quality is quite solid, and Zola really delivered on providing a robust development process. Using Zola to make changes to this site will be quite simple for newcomers and experienced users alike.
Expand All @@ -22,13 +21,11 @@ Overall, adding a new blog post for maintainers and community members will typic
Last thing I will say about the site, we are in the process of adding some new art work. Right now we've got a placeholder Ferris holding down the fort. They're doing a great job, but we're looking for some Trunk specific art, images, Ferris logos, etc. We've got some discussion going on over in [Trunk #120](https://github.com/thedodd/trunk/issues/120). I am especially excited about the possibility of an SVG of a bunch of little Ferris crabs packing a trunk full of sea shells, assets logos, scripts/scrolls, coral chunks and the like. If you've got some skills on this front, and you would like to jump on this hype train, DO IT!!! **We would love to show off your skills on the site.**

# New Maintainers

The biggest news we have, and probably one of the best things for the Trunk project itself, is that we have 3 new maintainers!!! 🎉🍻 Rakshith Ravi, Philip Peterson and Martin Kavik. I'm very excited to have these guys on the team, they've each already contributed in many ways to the Trunk project, and having a strong group of maintainers is very important for the long-term success of any open source project. We are all stronger together!

If you are interested in helping out as a maintainer, the best way to get started is with PR reviews, reviewing issues and making sure they are ready to be moved to the coding phase, and then actually getting your hands dirty with some code! Trunk so far has been able to maintain a pretty solid and enjoyable code base. Now is a great time to get involved.

# Trunk v0.8.0 has Landed

Trunk v0.8.0 has now been released. See the [release page](https://github.com/thedodd/trunk/releases/tag/v0.8.0) for all of the details. In summary:

- The `trunk watch` & `trunk serve` commands now accept the `--watch` option which allows users to specify multiple different directories and files to be watched, triggering new builds as changes are detected. A community member `@malobre` knocked this one out.
Expand All @@ -37,17 +34,16 @@ Trunk v0.8.0 has now been released. See the [release page](https://github.com/th
- Lastly, `@MartinKavik` fixed an infinite rebuild loop bug on Windows.

# Immediate Plans

In the immediate term, we have a few community lead efforts for cutting Trunk over to the Tokio ecosystem. This is primarily to address our need for a robust WebSockets & SSE solution, and the Tokio community happens to have some pretty solid options on that front.

We've also got another community lead effort on getting `wasm-opt` integrated into the standard Trunk build pipeline.

Both of these initiatives are exciting and will go far to provide an even better experience for folks building Rust WASM applications using Trunk.

# Conclusion

I am quite excited and optimistic about Rust's future with WebAssembly. WebAssembly has a long way to go, but it has already come so far. Working together to continue making Rust the best option for WebAssembly, and to ship more safe, robust, and powerful Rust code to the web is definitely for the better as far as I can see.

**BONUS:** head on over to [the next blog post](/blog/plugin-system/) where we discuss design patterns around a Trunk plugin system.

Let's keep on doing this. Cheers!

Loading

0 comments on commit f72448a

Please sign in to comment.