Rust library to generate static websites
feat: a lot of docs fixes
+105
-43
+1
-1
examples/basics/Cargo.toml
+1
-1
examples/basics/Cargo.toml
+1
-1
examples/blog/Cargo.toml
+1
-1
examples/blog/Cargo.toml
+1
-1
examples/empty/Cargo.toml
+1
-1
examples/empty/Cargo.toml
+1
-1
examples/image-processing/Cargo.toml
+1
-1
examples/image-processing/Cargo.toml
+1
-1
examples/kitchen-sink/Cargo.toml
+1
-1
examples/kitchen-sink/Cargo.toml
+1
-1
examples/library/Cargo.toml
+1
-1
examples/library/Cargo.toml
+1
-1
examples/markdown-components/Cargo.toml
+1
-1
examples/markdown-components/Cargo.toml
+8
website/assets/prin.css
+8
website/assets/prin.css
+1
-1
website/content/docs/content.md
+1
-1
website/content/docs/content.md
+2
website/content/docs/installation.md
+2
website/content/docs/installation.md
+26
-6
website/content/docs/javascript.md
+26
-6
website/content/docs/javascript.md
···
4
4
section: "core-concepts"
5
5
---
6
6
7
-
JavaScript and TypeScript files can be added to pages using the `ctx.assets.add_script()` method.
7
+
Maudit supports adding JavaScript and TypeScript files to your site.
8
8
9
-
In [supported templating languages](/docs/templating/), the return value of `ctx.assets.add_script()` can be used directly in the template.
9
+
To import a script, add it anywhere in your project's directory, and use the `ctx.assets.add_script()` method to add it to a page's assets. Paths are relative to the project's current working directory, not the file where the method is called.
10
10
11
11
```rs
12
12
use maudit::route::prelude::*;
13
-
use maud::{html};
13
+
use maud::{html, Markup};
14
14
15
15
#[route("/")]
16
16
pub struct Index;
···
19
19
fn render(&self, ctx: &mut PageContext) -> impl Into<RenderResult> {
20
20
let script = ctx.assets.add_script("script.js");
21
21
22
+
// Access the URL of the script using the `url()` method.
23
+
// This is useful when you want to manually add the script to your template.
24
+
format!(
25
+
r#"<script src="{}" type="module"></script>"#,
26
+
script.url()
27
+
);
28
+
29
+
// In supported templating languages, the return value of `ctx.assets.add_script()` can be used directly in the template.
22
30
html! {
23
31
(script) // Generates <script src="SCRIPT_URL" type="module"></script>
24
32
}
···
26
34
}
27
35
```
28
36
29
-
The `include_script()` method can be used to automatically include the script in the page, which can be useful when using layouts or other shared templates.
37
+
Alternatively, the `include_script()` method can be used to automatically include the script in the page, without needing to manually add it to the template. This can be useful when a layout or component need to include their own scripts.
30
38
31
39
```rs
32
40
fn render(&self, ctx: &mut PageContext) -> impl Into<RenderResult> {
41
+
layout(&ctx, "Look ma, no explicit script tag!")
42
+
}
43
+
44
+
fn layout(ctx: &PageContext, content: &str) -> Markup {
33
45
ctx.assets.include_script("script.js");
34
46
35
-
layout("Look ma, no explicit script tag!")
47
+
html! {
48
+
head {
49
+
title { "My page" }
50
+
// No need to manually add the script here.
51
+
}
52
+
body {
53
+
(PreEscaped(content))
54
+
}
55
+
}
36
56
}
37
57
```
38
58
39
-
When using `include_script()`, the script will be included inside the `head` tag with the `type="module"` attribute. [Note that this attribute implicitely means that your script will be deferred](https://v8.dev/features/modules#defer) after the page has loaded. At this time, pages without a `head` tag won't have the script included.
59
+
When using `include_script()`, the script will be included inside the `head` tag with the `type="module"` attribute. [Note that this attribute implicitely means that your script will be deferred](https://v8.dev/features/modules#defer) after the page has loaded. Note that, at this time, pages without a `head` tag won't have the script included.
40
60
41
61
## Transformation & Bundling
42
62
+8
-9
website/content/docs/performance.md
+8
-9
website/content/docs/performance.md
···
1
1
---
2
2
title: "Performance"
3
-
description: "Learn how to improve the build times and performance of your Maudit site."
3
+
description: "Learn how to improve the build times of your Maudit site."
4
4
section: "guide"
5
5
---
6
6
7
-
Maudit can generally [build websites pretty quickly](https://github.com/bruits/maudit/tree/main/benchmarks), but there are a few strategies you can use to improve build times and the performance of your site.
7
+
Maudit can generally [build websites pretty quickly](https://github.com/bruits/maudit/tree/main/benchmarks), but there are a few strategies you can use to improve build times still.
8
8
9
-
A Maudit project is a normal Rust project, so [any performance optimizations that apply to Rust projects](https://nnethercote.github.io/perf-book/build-configuration.html#minimizing-compile-times) also apply to Maudit projects, but there are a few specific strategies that can help improve the performance of your Maudit site.
9
+
A Maudit project is a normal Rust project, so [any performance optimizations that apply to Rust projects](https://nnethercote.github.io/perf-book/build-configuration.html#minimizing-compile-times) also apply to Maudit projects, but some additional strategies are more specific to Maudit.
10
10
11
11
## In development
12
12
13
13
### Cargo settings
14
14
15
-
We recommend using the following settings in your `Cargo.toml` to improve build times during development. This will increase the optimization level of your dependencies without making the compile time of your own crate longer.
15
+
We recommend using the following settings in your `Cargo.toml` to improve subsequent build times during development. This will increase the optimization level of your dependencies without making the compile time of your own crate longer.
16
16
17
17
```toml
18
-
[profile.dev.package."*"]
19
-
opt-level = 3
18
+
20
19
```
21
20
22
21
This is particularly relevant if you are processing a lot of images, as there is a large difference in performance between debug and release builds of the crates Maudit uses for image processing.
···
33
32
}
34
33
```
35
34
36
-
Running `cargo run` will show which pages of your site are slow to build, allowing you to identify bottlenecks in your build process. Note that it is not generally worth it to disable things such as image processing as Maudit will cache processed images between builds, even in development mode.
35
+
Building your project will show which pages of your site are slow to build, allowing you to identify bottlenecks in your build process. Note that it is not generally worth it to disable things such as image processing as Maudit will cache processed images between builds, even in development mode.
37
36
38
37
### Preventing build directory block
39
38
···
51
50
52
51
### Release builds
53
52
54
-
If not using `maudit build`, ensure you are building your project in release mode using `cargo build --release` or `cargo run --release`. This will significantly improve the performance of your site and is a common pitfall for new users.
53
+
If not using `maudit build`, which always build using the release profile, ensure you are building your project in release mode using `cargo build --release` or `cargo run --release`. This will significantly improve the performance of your site and is a common pitfall for new users.
55
54
56
55
### Caching
57
56
58
-
Make sure to cache the `target` directory between builds in your CI/CD pipeline. This will very significantly improve build times, especially if you have a lot of dependencies or processed images. Platforms like Netlify or Vercel will automatically cache the `target` directory for you.
57
+
Make sure to cache the `target` directory between builds in your CI/CD pipeline. This will very significantly improve build times, especially if you have a lot of dependencies or processed images. Platforms like [Netlify](https://docs.netlify.com/build/configure-builds/manage-dependencies/#rust) or Vercel will automatically cache the `target` directory for you.
+6
-4
website/content/docs/routing.md
+6
-4
website/content/docs/routing.md
···
12
12
13
13
```rs
14
14
use routes::Index;
15
-
use maudit::{coronate, routes, BuildOptions, BuildOutput};
15
+
use maudit::{coronate, routes, content_sources, BuildOptions, BuildOutput};
16
16
17
17
fn main() -> Result<BuildOutput, Box<dyn std::error::Error>> {
18
18
coronate(
19
19
routes![Index],
20
-
vec![].into(),
20
+
content_sources![],
21
21
BuildOptions::default()
22
22
)
23
23
}
···
40
40
}
41
41
```
42
42
43
-
The `Route` trait requires the implementation of a `render` method that returns any types that can be converted into `RenderResult`. This method is called when the page is built and should return the content that will be displayed. In most cases, you'll be using a templating library to create HTML content.
43
+
The `Route` trait requires the implementation of a `render` method that returns any types that can be converted into `RenderResult`. This method is called when the page is built and should return the content that will be displayed. In most cases, you'll be [using a templating library](/docs/templating/) to create HTML content.
44
44
45
45
Maudit implements `Into<RenderResult>` for the following types:
46
46
···
117
117
118
118
### Optional parameters
119
119
120
-
Dynamic routes can also have optional parameters by using the `Option<T>` type in the parameters struct. These parameters will be completely removed from the URL and file path when they are `None`. For instance, in a route with the path `/posts/[category]/[slug]`, if the `category` parameter is `None`, the resulting URL will be `/posts/my-blog-post/`.
120
+
Dynamic routes can also have optional parameters by using the `Option<T>` type in the parameters struct. These parameters will be completely removed from the URL and file path when they are `None`.
121
+
122
+
For instance, in a route with the path `/posts/[category]/[slug]`, if the `category` parameter is `None`, the resulting URL will be `/posts/my-blog-post/`.
121
123
122
124
This feature is notably useful when creating paginated routes (ex: `/posts/[page]`), where the first page sometimes does not include a page number in the URL, but subsequent pages do (e.g., `/blog` for the first page and `/blog/1` for the second page).
123
125
+25
-5
website/content/docs/styling.md
+25
-5
website/content/docs/styling.md
···
6
6
7
7
Maudit supports styling your site with CSS.
8
8
9
-
To import a stylesheet, add it anywhere in your project's directory, and use the `ctx.assets.add_style()` method to add it to a page's assets.
10
-
11
-
In [supported templating languages](/docs/templating/), the return value of `ctx.assets.add_style()` can be used directly in the template.
9
+
To import a stylesheet, add it anywhere in your project's directory, and use the `ctx.assets.add_style()` method to add it to a page's assets. Paths are relative to the project's current working directory, not the file where the method is called.
12
10
13
11
```rs
14
12
use maudit::route::prelude::*;
···
21
19
fn render(&self, ctx: &mut PageContext) -> impl Into<RenderResult> {
22
20
let style = ctx.assets.add_style("style.css");
23
21
22
+
// Access the URL of the stylesheet using the `url()` method.
23
+
// This is useful when you want to manually add the stylesheet to your template.
24
+
format!(
25
+
r#"<link rel="stylesheet" href="{}" />"#,
26
+
style.url()
27
+
);
28
+
29
+
// In supported templating languages, the return value of `ctx.assets.add_style()` can be used directly in the template.
24
30
html! {
25
31
(style) // Generates <link rel="stylesheet" href="STYLE_URL" />
26
32
}
···
28
34
}
29
35
```
30
36
31
-
Alternatively, the `include_style()` method can be used to automatically include the stylesheet in the page, without needing to manually add it to the template. Note that, at this time, pages without a `head` tag won't have the stylesheet included.
37
+
Alternatively, the `include_style()` method can be used to automatically include the stylesheet in the page, without needing to manually add it to the template. This can be useful when a layout or component need to include its own styles.
32
38
33
39
```rs
34
40
fn render(&self, ctx: &mut PageContext) -> impl Into<RenderResult> {
41
+
layout(&ctx, "Look ma, no link tag!")
42
+
}
43
+
44
+
fn layout(ctx: &PageContext, content: &str) -> Markup {
35
45
ctx.assets.include_style("style.css");
36
46
37
-
layout("Look ma, no link tag!")
47
+
html! {
48
+
head {
49
+
title { "My page" }
50
+
// No need to manually add the stylesheet here.
51
+
}
52
+
body {
53
+
(PreEscaped(content))
54
+
}
55
+
}
38
56
}
39
57
```
58
+
59
+
Note that, at this time, pages without a `head` tag won't have the stylesheet included.
40
60
41
61
## Tailwind support
42
62
+13
-2
website/content/docs/templating.md
+13
-2
website/content/docs/templating.md
···
10
10
11
11
## Maud
12
12
13
-
Maudit implements `Into<RenderResult>` for the Maud `Markup` type, allowing one to directly return Maud's templates from a page's `render` method.
13
+
Maudit implements `Into<RenderResult>` for the Maud `Markup` type, allowing one to directly return Maud's templates from a route's `render` method.
14
14
15
15
```rs
16
16
use maud::{html, Markup};
···
48
48
}
49
49
```
50
50
51
-
This is made possible by the `maud` feature, which is enabled by default, but can be disabled using `default-features = false` in your `Cargo.toml` for `maudit`.
51
+
To use Maud with Maudit, install Maud into your project by adding it to your `Cargo.toml`, or running `cargo add maud`.
52
+
53
+
```toml
54
+
[dependencies]
55
+
maud = "0.27"
56
+
```
57
+
58
+
The `maud` feature is enabled by default. If you have disabled default features, enable it manually:
59
+
60
+
```toml
61
+
maudit = { version = "0.6", features = ["maud"] }
62
+
```
+5
-5
website/src/layout.rs
+5
-5
website/src/layout.rs
···
80
80
layout(
81
81
html! {
82
82
// Second header for docs navigation (mobile only)
83
-
header.bg-our-white.border-b.border-borders.sm:hidden.bg-linear-to-b."from-darker-white" {
83
+
header.bg-our-white.border-b.border-borders.md:hidden.bg-linear-to-b."from-darker-white" {
84
84
div.flex.items-center.justify-between {
85
85
button id="left-sidebar-toggle" .px-4.py-3.flex.items-center.gap-x-2.text-base.font-medium.text-our-black aria-label="Toggle navigation menu" {
86
86
(PreEscaped(include_str!("../assets/side-menu.svg")))
···
107
107
}
108
108
}
109
109
110
-
div.container.mx-auto."sm:grid-cols-(--docs-columns)".sm:grid."min-h-[calc(100%-64px)]".px-4.sm:px-0.pt-2.sm:pt-0 {
111
-
aside.bg-linear-to-l."from-darker-white"."py-8"."h-full".border-r.border-r-borders.hidden.sm:block {
110
+
div.container.mx-auto."md:grid-cols-(--docs-columns)".md:grid."min-h-[calc(100%-64px)]".px-4.md:px-0.pt-2.md:pt-0 {
111
+
aside.bg-linear-to-l."from-darker-white"."py-8"."h-full".border-r.border-r-borders.hidden.md:block {
112
112
(left_sidebar(ctx))
113
113
}
114
-
main.w-full.max-w-larger-prose.mx-auto.sm:pt-8.py-4.pb-8.sm:pb-16 {
114
+
main.w-full.max-w-larger-prose.mx-auto.md:pt-8.py-4.pb-8.md:pb-16 {
115
115
(main)
116
116
}
117
-
aside."py-8".hidden."sm:block" {
117
+
aside."py-8".hidden."md:block" {
118
118
(right_sidebar(headings))
119
119
}
120
120
}
+4
-4
website/src/layout/header.rs
+4
-4
website/src/layout/header.rs
···
27
27
];
28
28
29
29
html! {
30
-
header.px-4.sm:px-8.py-4.text-our-black.bg-our-white."border-borders".(border) {
30
+
header.px-4.md:px-8.py-4.text-our-black.bg-our-white."border-borders".(border) {
31
31
div.container.flex.items-center.mx-auto.justify-between {
32
32
div.flex.items-center.gap-x-8 {
33
33
a.flex.gap-x-2.items-center href="/" {
34
34
(PreEscaped(include_str!("../../assets/logo.svg")))
35
35
h1.text-2xl.tracking-wide { "Maudit" }
36
36
}
37
-
nav.text-lg.gap-x-12.relative."top-[2px]".hidden."sm:flex" {
37
+
nav.text-lg.gap-x-12.relative."top-[2px]".hidden."md:flex" {
38
38
@for (href, text) in &nav_links {
39
39
a href=(href) { (text) }
40
40
}
41
41
}
42
42
}
43
43
44
-
div.gap-x-6.hidden.sm:flex {
44
+
div.gap-x-6.hidden.md:flex {
45
45
@for (href, _text, icon_svg) in &social_links {
46
46
a href=(href) {
47
47
span.sr-only { (_text) }
···
50
50
}
51
51
}
52
52
53
-
div.sm:hidden.flex.align-middle.justify-center.items-center {
53
+
div.md:hidden.flex.align-middle.justify-center.items-center {
54
54
button id="mobile-menu-button" aria-label="Toggle main menu" {
55
55
span id="hamburger-icon" {
56
56
(PreEscaped(include_str!("../../assets/hamburger.svg")))