Skip to content

Commit

Permalink
docs(book): 📝 updated links in docs
Browse files Browse the repository at this point in the history
  • Loading branch information
arctic-hen7 committed Oct 9, 2021
1 parent 8169153 commit c5398a3
Show file tree
Hide file tree
Showing 31 changed files with 47 additions and 47 deletions.
2 changes: 1 addition & 1 deletion docs/0.1.x/en-US/building.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,4 +49,4 @@ The reason we don't just make this whole function asynchronous is so we don't ha

## File Storage

It may have crossed your mind as to where all these static files are stored in production, and Perseus provides an excellent solution to this problem with custom read/write systems, documented in-depth [here](./config_managers).
It may have crossed your mind as to where all these static files are stored in production, and Perseus provides an excellent solution to this problem with custom read/write systems, documented in-depth [here](:config_managers).
2 changes: 1 addition & 1 deletion docs/0.1.x/en-US/integrations/actix-web.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ If you're using [Actix Web](https://actix.rs), then Perseus can automate nearly

This integration provides a configuration function, which you can use to configure an existing web server to support Perseus, so you could even run something like [Diana](https://github.com/arctic-hen7/diana) on the same server!

This integration should support almost every use case of Perseus, but there may be some extremely advanced things that you'll need to go back to basics for. If that's the case, please let us know by [opening an issue]() (we want these integrations to be as powerful as possible), and in the meantime you can use the guide [here](./serving) to see how to set up a server without using the integrations. If you need implementation details, check out the actual source code for the integration in the [repository](https://github.com/arctic-hen7/perseus).
This integration should support almost every use case of Perseus, but there may be some extremely advanced things that you'll need to go back to basics for. If that's the case, please let us know by [opening an issue]() (we want these integrations to be as powerful as possible), and in the meantime you can use the guide [here](:serving) to see how to set up a server without using the integrations. If you need implementation details, check out the actual source code for the integration in the [repository](https://github.com/arctic-hen7/perseus).

## Installation

Expand Down
10 changes: 5 additions & 5 deletions docs/0.1.x/en-US/serving.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,16 @@ Perseus aims to be agnostic as to what framework you use to host your files, and

If you're using one of our supported integrations, you don't have to bother with this page, nearly all of it can be done for you!

- [Actix Web](./integrations/actix-web)
- [Actix Web](:integrations/actix-web)
- _More coming soon..._

## Endpoints

Here are the endpoints that a server for Perseus must serve:

- `/.perseus/page/*` – used to serve the JSON data that the app shell needs to render a page (`*` should be extractable as a filename, e.g. `{filename:.*}` in Actix Web)
- `/.perseus/bundle.js` – the JavaScript bundle file that calls your Wasm code (see [tutorial on building your first app](./tutorials/first_app/intro))
- `/.perseus/bundle.wasm` – the Wasm bundle file that contains your code (see [tutorial on building your first app](./tutorials/first_app/intro))
- `/.perseus/bundle.js` – the JavaScript bundle file that calls your Wasm code (see [tutorial on building your first app](:tutorials/first_app/intro))
- `/.perseus/bundle.wasm` – the Wasm bundle file that contains your code (see [tutorial on building your first app](:tutorials/first_app/intro))
- `*` (anything else) – any page that the user actually requests, which will return the app shell to do the heavy lifting (or more accurately an HTML file that includes the bundle)

## Usage
Expand All @@ -27,7 +27,7 @@ This example shows what would be done to acquire a page for any framework. You'l
- The page path the user requested, e.g. `/post/test` for a request to `/.perseus/page/post/test`
- Data about the HTTP request the user sent (see below)
- A map of templates produced with [`get_templates_map!`]() (API docs WIP)
- A [config manager](./config_managers)
- A [config manager](:config_managers)

```rust
use perseus::{get_page};
Expand Down Expand Up @@ -99,4 +99,4 @@ HttpRequest::new(());

## File Storage

Perseus' systems of storing files in production are documented in-depth [here](./config_managers).
Perseus' systems of storing files in production are documented in-depth [here](:config_managers).
2 changes: 1 addition & 1 deletion docs/0.1.x/en-US/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,4 +12,4 @@ perseus = "0.1"

## Project Structure

The structure of a Perseus project is described in detail in the [architecture section](./arch), but you'll need two crates, an app and a server. A great example of this is in the showcase example, which you can find on GitHub [here](). We advise setting up a Cargo workspace with an `app` and a `server` crate for development. Soon, Perseus will support a CLI to run your server for you so you can focus more on your app.
The structure of a Perseus project is described in detail in the [architecture section](:arch), but you'll need two crates, an app and a server. A great example of this is in the showcase example, which you can find on GitHub [here](). We advise setting up a Cargo workspace with an `app` and a `server` crate for development. Soon, Perseus will support a CLI to run your server for you so you can focus more on your app.
2 changes: 1 addition & 1 deletion docs/0.1.x/en-US/templates.md
Original file line number Diff line number Diff line change
Expand Up @@ -36,4 +36,4 @@ First, we define the _component function_, which is done with Sycamore. This is

You can define a template with the `Template::new()` method, which takes the template's path as an argument (with no leading or trailing slashes). In the above example, `about` renders only one page, which would be hosted at `/about`.

The only mandatory builder function after that is `.template()`, which defines your template function (the closure inside `template_fn()` in the above example). There are a number of other functions available to customize how the template renders, all of which are documented [here](./strategies/intro).
The only mandatory builder function after that is `.template()`, which defines your template function (the closure inside `template_fn()` in the above example). There are a number of other functions available to customize how the template renders, all of which are documented [here](:strategies/intro).
4 changes: 2 additions & 2 deletions docs/0.2.x/en-US/advanced/arch.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ At the core of Perseus is the [`perseus`](https://docs.rs/perseus) module, which

What is intended to be used directly is the `Template<G>` `struct`, which is integral to Perseus. This stores closures for every rendering strategy, which are executed as provided and necessary at build and runtime. Note that these are all stored in `Rc`s, and `Template<G>`s are cloned.

The other commonly used system from this crate is the `Translator` system, explained in detail in [the i18n section](../i18n/intro). `Translator`s are passed around in `Rc`s, and `TranslationsManager` on the server caches all translations by default in memory on the server.
The other commonly used system from this crate is the `Translator` system, explained in detail in [the i18n section](:i18n/intro). `Translator`s are passed around in `Rc`s, and `TranslationsManager` on the server caches all translations by default in memory on the server.

## Actix Web Integration

Expand All @@ -24,7 +24,7 @@ Note that this module provides a `configurer` function, which allows it to be mo

## CLI

As documented in [this section](../cli), the CLI simply runs commands to execute the last two components of the Perseus system, acting as a convenience. It also contains these two components inside its binary (using [`include_dir!`](https://github.com/Michael-F-Bryan/include_dir))
As documented in [this section](:cli), the CLI simply runs commands to execute the last two components of the Perseus system, acting as a convenience. It also contains these two components inside its binary (using [`include_dir!`](https://github.com/Michael-F-Bryan/include_dir))

## CLI Builder

Expand Down
2 changes: 1 addition & 1 deletion docs/0.2.x/en-US/advanced/routing.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Routing

Perseus' routing system is quite unique in that it's almost entirely _inferred_, meaning that you don't ever have to define a router or explain to the system which paths go where. Instead, they're inferred from templates in a system that's explained in detail in the [templates section](../templates/intro).
Perseus' routing system is quite unique in that it's almost entirely _inferred_, meaning that you don't ever have to define a router or explain to the system which paths go where. Instead, they're inferred from templates in a system that's explained in detail in the [templates section](:templates/intro).

## Template Selection Algorithm

Expand Down
2 changes: 1 addition & 1 deletion docs/0.2.x/en-US/deploying/exporting.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ The easiest way to deploy Perseus is as a set of static files, which is supporte

However, if your app only needs to run server-side computations at build-time, then you can export it to a set of static files without changing anything, simply by running `perseus export`. This will create a new directory called `.perseus/dist/exported`, the contents of which can be served on a system like [GitHub Pages](https:://pages.github.com). Your app should behave in the exact same way with exporting as with normal serving. If this isn't the case, please [open an issue](https://github.com/arctic-hen7/perseus/issues/new/choose).

There is only one known difference between the behavior of your exported site and your normally served site, and that's regarding [static aliases](../static-content). In a normal serving scenario, any static aliases that conflicted with a Perseus page or internal asset would be ignored, but, in an exporting context, **any static aliases that conflict with Perseus pages will override them**! If you suspect this might be happening to you, try exporting without those aliases and make sure the URL of your alias file doesn't already exist (in which case it would be a Perseus component).
There is only one known difference between the behavior of your exported site and your normally served site, and that's regarding [static aliases](:static-content). In a normal serving scenario, any static aliases that conflicted with a Perseus page or internal asset would be ignored, but, in an exporting context, **any static aliases that conflict with Perseus pages will override them**! If you suspect this might be happening to you, try exporting without those aliases and make sure the URL of your alias file doesn't already exist (in which case it would be a Perseus component).

## File Extensions

Expand Down
2 changes: 1 addition & 1 deletion docs/0.2.x/en-US/strategies/amalgamation.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,4 +10,4 @@ Here's an example from [here](https://github.com/arctic-hen7/perseus/blob/main/e
{{#include ../../../../examples/showcase/src/templates/amalgamation.rs}}
```

This example illustrates a very simple amalgamation, taking the states of both strategies to produce a new state that combines the two. Note that this also uses `StringResultWithCause` as a return type (see the section on the [_build state_](./build-state) strategy for more information). It will be passed an instance of `States`, which you can learn more about in the [API docs](https://docs.rs/perseus).
This example illustrates a very simple amalgamation, taking the states of both strategies to produce a new state that combines the two. Note that this also uses `StringResultWithCause` as a return type (see the section on the [_build state_](:strategies/build-state) strategy for more information). It will be passed an instance of `States`, which you can learn more about in the [API docs](https://docs.rs/perseus).
2 changes: 1 addition & 1 deletion docs/0.2.x/en-US/strategies/incremental.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Incremental Generation

Arguable the most powerful strategy in Perseus is _incremental generation_, which is an extension of _build paths_ such that any path in the template's root path domain (more info on that concept [here](../templates/intro)) will result in calling the _build state_ strategy while the server is running.
Arguable the most powerful strategy in Perseus is _incremental generation_, which is an extension of _build paths_ such that any path in the template's root path domain (more info on that concept [here](:templates/intro)) will result in calling the _build state_ strategy while the server is running.

A perfect example of this would be an retail site with thousands of products, all using the `product` template. If we built all these with _build paths_, and they all require fetching information from a database, builds could take a very long time. Instead, it's far more efficient to use _incremental generation_, which will allow any path under `/product` to call the _build state_ strategy, which you can then use to render the product when it's first requested. This is on-demand building. But how is this different from the _request state_ strategy? It caches the pages after they've been built the first time, meaning **you build once on-demand, and then it's static generation from there**. In other words, this strategy provides support for rendering thousands, millions, or even billions of pages from a single template while maintaining static generation times of less than a second!

Expand Down
2 changes: 1 addition & 1 deletion docs/0.2.x/en-US/strategies/request-state.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Here's an example taken from [here](https://github.com/arctic-hen7/perseus/blob/
{{#include ../../../../examples/showcase/src/templates/ip.rs}}
```

Note that, just like _build state_, this strategy generates stringified properties that will be passed to the page to render it, and it also uses `StringResultWithCause` (see the section on [build state](./build-state) for more information). The key difference though is that this strategy receives a second, very powerful parameter: the HTTP request that the user sent (`perseus::Request`).
Note that, just like _build state_, this strategy generates stringified properties that will be passed to the page to render it, and it also uses `StringResultWithCause` (see the section on [build state](:strategies/build-state) for more information). The key difference though is that this strategy receives a second, very powerful parameter: the HTTP request that the user sent (`perseus::Request`).

<details>
<summary>How do you get the user's request information?</summary>
Expand Down
4 changes: 2 additions & 2 deletions docs/0.2.x/en-US/styling.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,13 +4,13 @@
Perseus aims to make styling as easy as possible, though there are a number of things that you should definitely know about before you start to style a Perseus app!

It's very easy to import stylesheets with Perseus (be they your own, something like [TailwindCSS](https://tailwindcss.com), etc.). You just add them to the `static/` directory at the root of your project, and then they'll be available at `/.perseus/static/your-filename-here`. That's described in more detail in [this section](./static-content).
It's very easy to import stylesheets with Perseus (be they your own, something like [TailwindCSS](https://tailwindcss.com), etc.). You just add them to the `static/` directory at the root of your project, and then they'll be available at `/.perseus/static/your-filename-here`. That's described in more detail in [this section](:static-content).

## Full-Page Layouts

If you've tried to create something like a stick footer, you've probably become extremely frustrated by Perseus, which puts all your content in a container `<div>` (in addition to the `<div id="root"></div>`). Unfortunately, this is necessary until Sycamore supports creating a template for an existing DOM node, and this does lead to some styling problems.

Notably, there are actually two of these `<div>`s at the moment: one for the content that the server pre-renders in [initial loads](./advanced/initial-loads) and another for when that content is hydrated by Perseus' client-side logic. That means that, if you only style one of these, you'll get a horrible flash of unstyled content, which nobody wants. To make this as easy as possible, Perseus provides a class `__perseus_content` that applies to both of these `<div>`s. Also, note that the `<div>` for the initial content will become `display: none;` as soon as the page is ready, which means you won't get it interfering with your layouts.
Notably, there are actually two of these `<div>`s at the moment: one for the content that the server pre-renders in [initial loads](:advanced/initial-loads) and another for when that content is hydrated by Perseus' client-side logic. That means that, if you only style one of these, you'll get a horrible flash of unstyled content, which nobody wants. To make this as easy as possible, Perseus provides a class `__perseus_content` that applies to both of these `<div>`s. Also, note that the `<div>` for the initial content will become `display: none;` as soon as the page is ready, which means you won't get it interfering with your layouts.

Knowing this, the main changes you'll need to make to any full-page layout code is to apply the styles to `.__perseus_content` instead of `body` or `#root`. As with CSS generally, if you expect `.__perseus_content` to take up the whole page, you'll need to make all its parents (`#root`, `body`, `html`) also take up the whole page (you can do this by setting `height: 100vh;` on `body`).

Expand Down
2 changes: 1 addition & 1 deletion docs/0.2.x/en-US/testing/checkpoints.md
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ Perseus has a number of internal checkpoints that are listed below. Note that th
- `router_entry` -- when the Perseus router has reached a verdict and is about to either render a new page, detect the user's locale and redirect, or show an error page
- `not_found` -- when the page wasn't found
- `app_shell_entry` -- when the page was found and it's being rendered
- `initial_state_present` -- when the page has been rendered for the first time, and the server has preloaded everything (see [here](../advanced/initial-loads) for details)
- `initial_state_present` -- when the page has been rendered for the first time, and the server has preloaded everything (see [here](:advanced/initial-loads) for details)
- `page_visible` -- when the user is able to see page content (but the page isn't interactive yet)
- `page_interactive` -- when the page has been hydrated, and is now interactive
- `initial_state_not_present` -- when the initial state is not present, and the app shell will need to fetch page data from the server
Expand Down
2 changes: 1 addition & 1 deletion docs/0.2.x/en-US/testing/fantoccini-basics.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Remember, you're controlling an actual browser, so you basically have everything

## Going to a Page

You can trivially go to a page of your app by running `c.goto("...")`. The above example ensures that the URL is valid, but you shouldn't have to do this unless you're testing a page that automatically redirects the user. Also, if you're using [i18n](../i18n/intro), don't worry about testing automatic locale redirection, we've already done that for you!
You can trivially go to a page of your app by running `c.goto("...")`. The above example ensures that the URL is valid, but you shouldn't have to do this unless you're testing a page that automatically redirects the user. Also, if you're using [i18n](:i18n/intro), don't worry about testing automatic locale redirection, we've already done that for you!

Once you've arrived at a page, you should wait for the `router_entry` (this example uses `begin` because it tests internal parts of Perseus) checkpoint, which will be reached when Perseus has decided what to do with your app. If you're testing particular page logic, you should wait instead for `page_visible`, which will be reached when the user could see content on your page, and then for `page_interactive`, which will be reached when the page is completely ready. Remember though, you only need to wait for the checkpoints that you actually use (e.g. you don't need to wait for `page_visible` and `page_interactive` if you're not doing anything in between).

Expand Down
2 changes: 1 addition & 1 deletion docs/0.2.x/en-US/updating.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ _Note: if possible, it's best to start a new project for Perseus v0.2.0 due to t
3. Upgrade the Perseus CLI with `cargo install perseus-cli`.
4. Run `perseus clean` to remove the old `.perseus/` directory.
5. Change all `Rc`s to `Arc`s.
6. Change your `lib.rs` to match the [new `define_app!` macro](./define-app) and delete routing code (all that is now inferred, with no extra code from you)!.
6. Change your `lib.rs` to match the [new `define_app!` macro](:define-app) and delete routing code (all that is now inferred, with no extra code from you)!.
7. Update your code for the remaining breaking changes listed in [the CHANGELOG]().

_Note: if you're running an older machine (pre-2015), it may be worth setting the `PERSEUS_CLI_SEQUENTIAL` environment variable to `true` to disable the CLI's new multi-threading, which may overly burden older systems. You should try it first to make sure though._
Expand Down
Loading

0 comments on commit c5398a3

Please sign in to comment.