Rust library to generate static websites
feat: small docs progress
+82
+6
website/content/docs/philosophy.md
+6
website/content/docs/philosophy.md
···
13
13
Supporting certain features in your less used output mode might add technical constraints affecting your main use case, and your attention is forever split between the two universes you intend to support.
14
14
15
15
**Maudit is about making static websites**. It has no higher goals than that. It won't try to become a server-side rendering framework, a hybrid framework, or anything else. This focus allows us to make the best static website generator we can.
16
+
17
+
## Your website changes less often than its content
18
+
19
+
Many parts of Maudit projects are written in Rust, a compiled language, thus requiring recompilation for changes. This overhead is justified by the assumption that structural changes are less frequent than content updates. For example, in a blog, new articles are more common than layout changes.
20
+
21
+
Without delving into the complexities of incremental builds, this architecture allows Maudit projects to build very quickly, even for large websites, thanks to the raw performance of a compiled language.
+76
website/content/docs/quick-start.md
+76
website/content/docs/quick-start.md
···
2
2
title: "Quick Start"
3
3
section: "getting-started"
4
4
---
5
+
6
+
In this guide, you'll learn how to create a Maudit website and the general basis of Maudit in a few minutes of reading.
7
+
8
+
If you prefer to read more detailed explanations, including exploration of various Maudit concepts, please read the [the tutorial]().
9
+
10
+
> This guide assumes that you have Rust installed and are familiar with the terminal.
11
+
12
+
## Installation
13
+
14
+
First install the Maudit CLI.
15
+
16
+
```shell
17
+
cargo install maudit-cli
18
+
```
19
+
20
+
## Generating a Maudit project
21
+
22
+
Run the following command to generate a Maudit project.
23
+
24
+
The command will suggest many templates to begin from. Some of which are usable as-is (such as the Blog example)
25
+
26
+
```shell
27
+
maudit init
28
+
```
29
+
30
+
Once done, `cd` into the directory you have chosen to create your project in.
31
+
32
+
## Running your project
33
+
34
+
Use the Maudit CLI to build, run in development mode or preview your project.
35
+
36
+
The `maudit build` command will build your project to the `dist` directory, ready to be deployed.
37
+
38
+
`maudit dev` will serve your website on a local server, automatically rebuilding and refreshing the page on changes.
39
+
40
+
`maudit preview` will serve your website on a local server with various optimization enabled to imitate what a real production server would do, and is intended to preview your built website before deploying.
41
+
42
+
## Creating pages
43
+
44
+
Pages in Maudit are created directly in Rust, using `.rs` files.
45
+
46
+
To create a page, create a `.rs` file with a public struct using the `route` attribute, which take the path of the route as sole parameter.
47
+
48
+
All of Maudit's useful imports for pages can be imported using the prelude from `maudit::page`.
49
+
50
+
```rust
51
+
use maudit::page::prelude::*;
52
+
53
+
#[route("/hello-world")]
54
+
pub struct HelloWorld;
55
+
```
56
+
57
+
Every page must `impl` the `Page` trait, with the required method `render`.
58
+
59
+
```rust
60
+
impl Page for HelloWorld {
61
+
fn render(&self, ctx: &mut RouteContext) -> RenderResult {
62
+
RenderResult::Text("Hello, world!".to_string())
63
+
}
64
+
}
65
+
```
66
+
67
+
Finally, pages' struct must be passed to the `coronate` function in the project's `main.rs`
68
+
69
+
```rust
70
+
use pages::HelloWorld;
71
+
use maudit::{coronate, routes, content_sources, BuildOptions, BuildOutput};
72
+
73
+
fn main() -> Result<BuildOutput, Box<dyn std::error::Error>> {
74
+
coronate(
75
+
routes![Index],
76
+
content_sources![],
77
+
BuildOptions::default()
78
+
)
79
+
}
80
+
```