Rust library to generate static websites
docs: progress
+204
-11
+142
website/content/docs/assets.md
+142
website/content/docs/assets.md
···
1
+
---
2
+
title: "Assets"
3
+
description: "Welcome to the Maudit documentation!"
4
+
section: "core-concepts"
5
+
---
6
+
7
+
Maudit supports importing assets like images, stylesheets, and scripts into your project and pages.
8
+
9
+
### Images
10
+
11
+
To import an image, add it anywhere in your project's directory, and use the `ctx.assets.add_image()` method to add it to a page's assets.
12
+
13
+
Like other assets, images can be used directly in Maud templates.
14
+
15
+
```rust
16
+
use maudit::page::prelude::*;
17
+
use maud::html;
18
+
19
+
#[route("/blog")]
20
+
pub struct Blog;
21
+
22
+
impl Page for Blog {
23
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
24
+
let image = ctx.assets.add_image("logo.png");
25
+
26
+
html! {
27
+
(image) // Generates <img src="IMAGE_URL" loading="lazy" decoding="async" />
28
+
}
29
+
}
30
+
}
31
+
```
32
+
33
+
Alternatively, if not using Maud, the `url()` method on the image can be used to generate the HTML.
34
+
35
+
```rust
36
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
37
+
let image = ctx.assets.add_image("logo.png");
38
+
39
+
RenderResult::Html(format!("<img src=\"{}\" loading=\"lazy\" decoding=\"async\" />", image.url().unwrap()))
40
+
}
41
+
```
42
+
43
+
At this time, images are not automatically optimized or resized, but this will be added in the future.
44
+
45
+
### Stylesheets
46
+
47
+
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.
48
+
49
+
When using Maud, the return value of `ctx.assets.add_style()` can be used directly in the template.
50
+
51
+
```rust
52
+
use maudit::page::prelude::*;
53
+
use maud::html;
54
+
55
+
#[route("/blog")]
56
+
pub struct Blog;
57
+
58
+
impl Page for Blog {
59
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
60
+
let style = ctx.assets.add_style("style.css", false);
61
+
62
+
html! {
63
+
(style) // Generates <link rel="stylesheet" href="STYLE_URL" />
64
+
}
65
+
}
66
+
}
67
+
```
68
+
69
+
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.
70
+
71
+
```rust
72
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
73
+
ctx.assets.include_style("style.css", false);
74
+
75
+
html! {
76
+
div {
77
+
"Look ma, no explicit link tag!"
78
+
}
79
+
}
80
+
}
81
+
```
82
+
83
+
#### Tailwind support
84
+
85
+
Maudit includes built-in support for [Tailwind CSS](https://tailwindcss.com/). To use it, pass `true` as the second argument to `add_style()` or `include_style()`.
86
+
87
+
```rust
88
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
89
+
ctx.assets.add_style("style.css", true);
90
+
91
+
html! {
92
+
div.bg-red-500 {
93
+
"Wow, such red!"
94
+
}
95
+
}
96
+
}
97
+
```
98
+
99
+
To configure Tailwind, add a [`tailwind.config.js` file](https://tailwindcss.com/docs/configuration) to your project's root directory. This file will be automatically detected and used by Maudit.
100
+
101
+
### Scripts
102
+
103
+
JavaScript and TypeScript files can be added to pages using the `ctx.assets.add_script()` method.
104
+
105
+
```rust
106
+
use maudit::page::prelude::*;
107
+
108
+
#[route("/blog")]
109
+
pub struct Blog;
110
+
111
+
impl Page for Blog {
112
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
113
+
let script = ctx.assets.add_script("script.js");
114
+
115
+
html! {
116
+
(script) // Generates <script src="SCRIPT_URL" type="module"></script>
117
+
}
118
+
}
119
+
}
120
+
```
121
+
122
+
As with stylesheets, 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.
123
+
124
+
```rust
125
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
126
+
ctx.assets.include_script("script.js");
127
+
128
+
html! {
129
+
div {
130
+
"Look ma, no explicit script tag!"
131
+
}
132
+
}
133
+
}
134
+
```
135
+
136
+
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 after the page has loaded. At this time, pages without a `head` tag won't have the script included.
137
+
138
+
### Transformation & Bundling
139
+
140
+
Maudit uses [Rolldown](https://rolldown.rs) to process and bundle scripts and styles. Rolldown will automatically chunk, minify, transpile, etc. your scripts and stylesheets, optimizing them for production. Features like tree shaking, minification, TypeScript support and more are all included out of the box.
141
+
142
+
At this time, Maudit does not support customizing the transformation process, but this will be added in the future.
+35
-1
website/content/docs/entrypoint.md
+35
-1
website/content/docs/entrypoint.md
···
1
1
---
2
2
title: "Entrypoint"
3
3
description: "Welcome to the Maudit documentation!"
4
+
section: "core-concepts"
4
5
---
5
6
6
-
Something
7
+
At the core of a Maudit project is the `coronate` function. This function starts the build process and generates the output files. It is the entrypoint to your project and is where you define the pages, content and options that make up your website.
8
+
9
+
In a `main.rs` file, import the `coronate` function and call it to build your project. Here is an example of a simple Maudit project:
10
+
11
+
```rust
12
+
use maudit::{coronate, routes, BuildOptions, BuildOutput};
13
+
use pages::Index;
14
+
15
+
fn main() -> Result<BuildOutput, Box<dyn std::error::Error>> {
16
+
coronate(routes![Index], vec![].into(), BuildOptions::default())
17
+
}
18
+
```
19
+
20
+
### Registering Routes
21
+
22
+
All kinds of routes must be passed to the `coronate` function in order for them to be built.
23
+
24
+
The first argument to the `coronate` function is a `Vec` of all the routes that should be built. For the sake of ergonomics, the `routes!` macro can be used to create this list.
25
+
26
+
```rust
27
+
use pages::Index;
28
+
29
+
coronate(
30
+
routes![Index],
31
+
vec![].into(),
32
+
BuildOptions::default()
33
+
)
34
+
```
35
+
36
+
See the [Routing](/docs/routing) documentation for more information on how to define routes.
37
+
38
+
### Content
39
+
40
+
### Options
+6
-6
website/content/docs/routing.md
+6
-6
website/content/docs/routing.md
···
15
15
pub struct HelloWorld;
16
16
17
17
impl Page for HelloWorld {
18
-
fn render(&self, ctx: &PageContext) -> RenderResult {
18
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
19
19
RenderResult::Text("Hello, world!".to_string())
20
20
}
21
21
}
···
40
40
pub struct Post;
41
41
42
42
impl Page for Post {
43
-
fn render(&self, ctx: &PageContext) -> String {
43
+
fn render(&self, ctx: &mut RouteContext) -> String {
44
44
format!("Hello, {}!", ctx.params.get("slug").unwrap())
45
45
}
46
46
}
···
64
64
}
65
65
66
66
impl Page for Post {
67
-
fn render(&self, ctx: &PageContext) -> RenderResult {
67
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
68
68
RenderResult::Text(format!("Hello, {}!", ctx.params.get("slug").unwrap()))
69
69
}
70
70
}
···
100
100
}
101
101
102
102
impl Page for Post {
103
-
fn render(&self, ctx: &PageContext) -> RenderResult {
103
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
104
104
let params = ctx.params::<Params>();
105
105
106
106
RenderResult::Text(format!("Hello, {}!", params.slug))
···
121
121
pub struct HelloWorldJson;
122
122
123
123
impl Page for HelloWorldJson {
124
-
fn render(&self, ctx: &PageContext) -> RenderResult {
124
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
125
125
RenderResult::Text(r#"{"message": "Hello, world!"}"#.to_string())
126
126
}
127
127
}
···
149
149
}
150
150
151
151
impl Page for PostJson {
152
-
fn render(&self, ctx: &PageContext) -> RenderResult {
152
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
153
153
let params = ctx.params::<Params>();
154
154
155
155
RenderResult::Text(format!(r#"{{"message": "Hello, {}!"}}"#, params.slug))
+1
-1
website/src/layout.rs
+1
-1
website/src/layout.rs