|
@@ -0,0 +1,89 @@
|
|
1
|
+# Casaubon
|
|
2
|
+
|
|
3
|
+Casaubon is a static site generator written in Rust. I had very specific goals
|
|
4
|
+in mind when writing Casaubon and it is not meant to be all things for all
|
|
5
|
+people. Casaubon does what it is intended to do and no more.
|
|
6
|
+
|
|
7
|
+### Goals
|
|
8
|
+
|
|
9
|
+- Convention over configuration
|
|
10
|
+- Learn Rust
|
|
11
|
+- Fast compile times
|
|
12
|
+
|
|
13
|
+### Non-goals
|
|
14
|
+
|
|
15
|
+- Extensibility
|
|
16
|
+- Flexibility
|
|
17
|
+
|
|
18
|
+## Installation
|
|
19
|
+
|
|
20
|
+(requires [Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html))
|
|
21
|
+
|
|
22
|
+```
|
|
23
|
+$ cargo install casaubon
|
|
24
|
+```
|
|
25
|
+
|
|
26
|
+## Run tests
|
|
27
|
+
|
|
28
|
+```
|
|
29
|
+$ cargo test
|
|
30
|
+```
|
|
31
|
+
|
|
32
|
+## Usage
|
|
33
|
+
|
|
34
|
+Create a new project
|
|
35
|
+
|
|
36
|
+```
|
|
37
|
+$ casaubon new
|
|
38
|
+```
|
|
39
|
+
|
|
40
|
+Generate HTML files
|
|
41
|
+
|
|
42
|
+```
|
|
43
|
+$ casaubon build
|
|
44
|
+```
|
|
45
|
+
|
|
46
|
+Watch files for changes and rebuild. Note that there is no dev server built in.
|
|
47
|
+
|
|
48
|
+```
|
|
49
|
+$ casaubon watch
|
|
50
|
+```
|
|
51
|
+
|
|
52
|
+`build` and `watch` both accept a `--drafts` flag if you wish to include drafts
|
|
53
|
+in the generated HTML files.
|
|
54
|
+
|
|
55
|
+## Configuration
|
|
56
|
+
|
|
57
|
+Casuabon is not intended to be as flexible as most static site generators.
|
|
58
|
+Currently, the only configuration option is the name of the site, which can be
|
|
59
|
+set in `casaubon.toml`.
|
|
60
|
+
|
|
61
|
+## Writing
|
|
62
|
+
|
|
63
|
+Casuabon expects the first line of post files to consist of a `#` followed by a
|
|
64
|
+space and the name of the post, followed by two newlines. For example:
|
|
65
|
+
|
|
66
|
+_posts/first-post.md_
|
|
67
|
+
|
|
68
|
+```
|
|
69
|
+# First Post
|
|
70
|
+
|
|
71
|
+Lorem ipsum dolor sit amet....
|
|
72
|
+```
|
|
73
|
+
|
|
74
|
+In this example, the post's title would get parsed as "First Post", and the
|
|
75
|
+post's body would get parsed as "Lorem ipsum dolor sit amet...". The slug gets
|
|
76
|
+parsed from the filename, and in this case would be 'first-post'.
|
|
77
|
+
|
|
78
|
+## Templates
|
|
79
|
+
|
|
80
|
+Casaubon creates a number of templates for you in the `templates` directory.
|
|
81
|
+These include:
|
|
82
|
+
|
|
83
|
+|Title |Description|
|
|
84
|
+|------------------------|-----------|
|
|
85
|
+|`layout.html` |The main layout. All page content gets injected into the `{{ contents }}` variable. The title of the page is available in the `{{ page_title }}` variable.|
|
|
86
|
+|`post.html` |The template for rendering a single post. Variables available include `{{ title }}` and `{{ body }}`.|
|
|
87
|
+|`page.html` |The template for rendering a single page. Variables available include `{{ title }}` and `{{ body }}`.|
|
|
88
|
+|`post_listing.html` |This template is for the list of posts on the index page. The `{{ post_listing }}` variable contains the result of compiling the `post_listing_item.html` template against each post.|
|
|
89
|
+|`post_listing_item.html`|This template determines how each post will appear in the main listing. Variables available include `{{ title }}` and `{{ slug }}`.|
|