Skip to content

Commit

Permalink
docs(book): updated tutorials for new examples layout
Browse files Browse the repository at this point in the history
  • Loading branch information
arctic-hen7 committed Feb 3, 2022
1 parent 0449fea commit 28f1af1
Show file tree
Hide file tree
Showing 6 changed files with 49 additions and 49 deletions.
2 changes: 1 addition & 1 deletion docs/next/en-US/reference/exporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@ There is only one known difference between the behavior of your exported site an

One slight hiccup with Perseus' static exporting system comes with regards to the `.html` file extension. Perseus' server expects that pages shouldn't have such extensions (hence `/about` rather than `/about.html`), but, when statically generated, they must have these extensions in the filesystem. So, if you don't want these extensions for your users (and if you want consistent behavior between exporting and serving), it's up to whatever system you're hosting your files with to strip these extensions. Many systems do this automatically, though some (like Python's `http.server`) do not.

One of the best systems for testing static exporting on your local machine is the [`serve`](https://github.com/vercel/serve) JavaScript package, which can be run from the command-line without touching any JavaScript, and it handles this problem automatically. However, other solutions certainly exist if you don't want any JS polluting your system!
Note that, in development, you can easily serve your app with `perseus export -s`, which will spin up a local server automatically!
4 changes: 2 additions & 2 deletions docs/next/en-US/reference/static-content.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,10 @@ One problem with making all static content available under `/.perseus/static/` i

_Static aliases_ allow you to handle these conditions with ease, as they let you define static content to be available at any given path, and to map to any given file in your project's directory.

You can define static aliases in the `define_app!` macro's `static_aliases` parameter. Here's an example from [here](https://github.com/arctic-hen7/perseus/blob/main/examples/core/basic/src/lib.rs):
You can define static aliases in the `define_app!` macro's `static_aliases` parameter. Here's an example from [here](https://github.com/arctic-hen7/perseus/blob/main/examples/core/static_content/src/lib.rs):

```rust
{{#include ../../../examples/core/basic/src/lib.rs}}
{{#include ../../../examples/core/static_content/src/lib.rs}}
```

### Security
Expand Down
4 changes: 2 additions & 2 deletions docs/next/en-US/reference/templates/setting-headers.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,10 +2,10 @@

Most of the time, you shouldn't need to touch the HTTP headers of your Perseus templates, but sometimes you will need to. A particular example of this is if you want your users' browsers to only cache a page for a certain amount of time (the default for Perseus if five minutes), then you'd need to set the [`Cache-Control`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control) header.

Perseus supports inserting arbitrary HTTP headers for any response from the server that successfully returns a page generated from the template those headers are defined for. You can do this like so (taken from [here](https://github.com/arctic-hen7/perseus/blob/main/examples/core/basic/src/templates/index.rs)):
Perseus supports inserting arbitrary HTTP headers for any response from the server that successfully returns a page generated from the template those headers are defined for. You can do this like so (taken from [here](https://github.com/arctic-hen7/perseus/blob/main/examples/core/set_headers/src/templates/index.rs)):

```rust
{{#include ../../../../examples/core/basic/src/templates/index.rs}}
{{#include ../../../../examples/core/set_headers/src/templates/index.rs}}
```

Of note here is the `set_headers_fn` function, which returns a `HeaderMap`. This is then used on the template with `.set_headers_fn()`. Note that the function you provide will be given the state as an argument (ignored here, but it will be deserialized for you with `#[perseus::autoserde(set_headers)]`), and you must return some headers (you can't return an error).
6 changes: 3 additions & 3 deletions docs/next/en-US/tutorials/hello-world.md
Original file line number Diff line number Diff line change
Expand Up @@ -51,7 +51,7 @@ Now, create a new directory called `src` and add a new file inside called `lib.r

First, we import some things that'll be useful:

- `perseus::{define_app, ErrorPages, Template}` -- the -`define_app!` macro, which tells Perseus how your app works; the `ErrorPages` `struct`, which lets you tell Perseus how to handle errors (like _404 Not Found_ if the user goes to a nonexistent page); and the `Template` `struct`, which is how Perseus manages pages in your app
- `perseus::{define_app, ErrorPages, Template}` -- the `define_app!` macro, which tells Perseus how your app works; the `ErrorPages` `struct`, which lets you tell Perseus how to handle errors (like _404 Not Found_ if the user goes to a nonexistent page); and the `Template` `struct`, which is how Perseus manages pages in your app
- `sycamore::view` -- Sycamore's `view!` macro, which lets you write HTML-like code in Rust

Then, we use the `define_app!` macro to declare the different aspects of the app, starting with the _templates_. We only have one template, which we've called `index` (a special name that makes it render at the root of your app), and then we define how that should look, creating a paragraph (`p`) containing the text `Hello World!`.
Expand All @@ -65,13 +65,13 @@ Now install the Perseus CLI with `cargo install perseus-cli` (you'll need `wasm-
<details>
<summary>Why do I need a CLI?</summary>

Perseus is a _very_ complex system, and, if you had to write all that complexity yourself, that _Hello World!_ example would be more like 1700 lines of code than 17! The CLI lets you abstract away all that complexity into a directory that you might have noticed appear called `.perseus/`. If you take a look inside, you'll actually find two crates (Rust packages): one for your app, and another for the server that serves your app. These are what actually run your app, and they import the code you've written. The `define_app!` macro defines a series of functions and constants at compile-time that make this possible.
Perseus is a _very_ complex system, and, if you had to write all that complexity yourself, that _Hello World!_ example would be more like 1200 lines of code than 12! The CLI lets you abstract away all that complexity into a directory that you might have noticed appear called `.perseus/`. If you take a look inside, you'll actually find two crates (Rust packages): one for your app, and another for the server that serves your app. These are what actually run your app, and they import the code you've written. The `define_app!` macro defines a series of functions and constants at compile-time that make this possible.

When you run `perseus serve`, the `.perseus/` directory is created and added to your `.gitignore`, and then three stages occur in parallel (they're shown in your terminal):

- _🔨 Generating your app_ -- here, your app is built to a series of static files in `.perseus/dist/static`, which makes your app lightning-fast (your app's pages are ready before it's even been deployed, which is called _static site generation_, or SSG)
- _🏗️ Building your app to Wasm_ -- here, your app is built to [WebAssembly](https://webassembly.org), which is what lets a low-level programming language like Rust run in the browser
- _📡 Building server_ -- here, Perseus builds its internal server based on your code, and prepares to serve your app
- _📡 Building server_ -- here, Perseus builds its internal server based on your code, and prepares to serve your app (note that an app this simple can actually use [static exporting](:reference/exporting), but we'll deal with that later)

The first time you run this command, it can take quite a while to get everything ready, but after that it'll be really fast. And, if you haven't changed any code (_at all_) since you last ran it, you can run `perseus serve --no-build` to run the server basically instantaneously.

Expand Down
Loading

0 comments on commit 28f1af1

Please sign in to comment.