doc: improve the overall look of the document
This commit is contained in:
parent
8584fa5ca7
commit
45d8b6651d
|
@ -7,9 +7,35 @@
|
|||
}
|
||||
|
||||
.md-typeset code {
|
||||
background-color: rgb(240, 240, 240);
|
||||
font-size: .95em;
|
||||
}
|
||||
|
||||
.md-typeset .admonition {
|
||||
font-size: .75rem;
|
||||
.md-typeset pre > code {
|
||||
background-color: rgb(245, 245, 245);
|
||||
font-size: .90em;
|
||||
}
|
||||
|
||||
.md-typeset .admonition {
|
||||
font-size: .70rem;
|
||||
}
|
||||
|
||||
body {
|
||||
-webkit-font-smoothing: antialiased !important;
|
||||
-moz-font-smoothing: antialiased !important;
|
||||
}
|
||||
|
||||
.md-content h2 {
|
||||
border-bottom-color: rgb(234, 236, 239);
|
||||
border-bottom-style: solid;
|
||||
border-bottom-width: 1px;
|
||||
padding-bottom: .3rem;
|
||||
}
|
||||
|
||||
.md-content a:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
.highlight code .cp {
|
||||
color: #a83;
|
||||
}
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
Create a new directory named `templates` in the same directory as `Cargo.toml`. Copy the following contents and paste it to a new file named `templates/hello.stpl`.
|
||||
|
||||
```ejs
|
||||
``` rhtml
|
||||
<html>
|
||||
<body>
|
||||
<% for msg in &messages { %>
|
||||
|
@ -26,13 +26,13 @@ templates/
|
|||
|
||||
## Render the template
|
||||
|
||||
Import the sailfish crates:
|
||||
<ol><li>Import the sailfish crates:</li></ol>
|
||||
|
||||
```rust
|
||||
use sailfish::TemplateOnce;
|
||||
```
|
||||
|
||||
Define the template struct to be rendered:
|
||||
<ol start="2"><li>Define the template struct to be rendered:</li></ol>
|
||||
|
||||
```rust
|
||||
#[derive(TemplateOnce)] // automatically implement `TemplateOnce` trait
|
||||
|
@ -43,7 +43,7 @@ struct HelloTemplate {
|
|||
}
|
||||
```
|
||||
|
||||
And render the data with `render_once()` method.
|
||||
<ol start="3"><li>Render the data with <code>render_once()</code> method.</li></ol>
|
||||
|
||||
```rust
|
||||
fn main() {
|
||||
|
|
|
@ -4,17 +4,14 @@ Sailfish is a simple, small, and extremely fast template engine for Rust. This d
|
|||
|
||||
This documentation mainly focuses on concepts of the library, general usage, and template syntax. If you've read this documentation and need more specific information, you might want to read the [sailfish API docs](https://docs.rs/sailfish).
|
||||
|
||||
Currently the documentation is uncompleted. If you want to improve our documentation, feel free to create a [Pull Request](https://github.com/Kogia-sima/sailfish/pulls) on the repository. I'll be happy if someone contributes to writing documents (English is not my first language and creating a documentation is a hard task for me).
|
||||
|
||||
## Why Sailfish ?
|
||||
|
||||
There are many libraries for template rendering in Rust. Among those libraries, sailfish aims at **rapid development** and **rapid rendering**. Sailfish has many features that other libraries might not support.
|
||||
|
||||
- Write a Rust code directly inside templates, supporting many Rust syntax (struct definition, closure, macro invocation, etc.)
|
||||
- Built-in filters
|
||||
- Relatively small number of dependencies (<15 crates in total)
|
||||
- [Built-in filters](https://docs.rs/sailfish/latest/sailfish/runtime/filter/index.html)
|
||||
- Minimal dependencies (<15 crates in total)
|
||||
- Extremely fast (See [benchmarks](https://github.com/djc/template-benchmarks-rs))
|
||||
- Better error message
|
||||
- Template rendering is always type-safe because templates are statically compiled.
|
||||
- Syntax highlighting ([vscode](http://github.com/Kogia-sima/sailfish/blob/master/syntax/vscode), [vim](http://github.com/Kogia-sima/sailfish/blob/master/syntax/vim))
|
||||
- Automatically re-compile sources when template file is updated.
|
||||
|
|
|
@ -2,12 +2,14 @@
|
|||
|
||||
In order to use sailfish templates, you have add two dependencies in your `Cargo.toml`.
|
||||
|
||||
```toml
|
||||
``` toml
|
||||
[dependencies]
|
||||
sailfish = "0.3.0"
|
||||
```
|
||||
|
||||
### Feature Flags
|
||||
## Feature Flags
|
||||
|
||||
Sailfish accepts the following feature flags
|
||||
|
||||
|Feature|Description|
|
||||
|--|--|
|
||||
|
|
|
@ -4,7 +4,7 @@
|
|||
|
||||
You can control the rendering behaviour via `template` attribute.
|
||||
|
||||
```rust
|
||||
``` rust
|
||||
#[derive(TemplateOnce)]
|
||||
#[template(path = "template.stpl", escape = false)]
|
||||
struct TemplateStruct {
|
||||
|
@ -21,7 +21,7 @@ struct TemplateStruct {
|
|||
|
||||
You can split the options into multiple `template` attributes.
|
||||
|
||||
```rust
|
||||
``` rust
|
||||
#[derive(TemplateOnce)]
|
||||
#[template(path = "template.stpl")]
|
||||
#[template(delimiter = '?')]
|
||||
|
@ -49,7 +49,7 @@ If a key is specified in both configuration file and derive options, then the va
|
|||
|
||||
Configuration files are written in the YAML 1.2 format. Here is the default configuration.
|
||||
|
||||
```
|
||||
``` yaml
|
||||
template_dir: "templates"
|
||||
escape: true
|
||||
delimiter: "%"
|
||||
|
|
|
@ -4,31 +4,33 @@ Filters are used to format the rendered contents.
|
|||
|
||||
Example:
|
||||
|
||||
```ejs
|
||||
message: <%= "foo\nbar" | dbg %>
|
||||
```
|
||||
=== "Template"
|
||||
|
||||
Output:
|
||||
``` rhtml
|
||||
message: <%= "foo\nbar" | dbg %>
|
||||
```
|
||||
|
||||
```html
|
||||
message: "foo\nbar"
|
||||
```
|
||||
=== "Result"
|
||||
|
||||
``` html
|
||||
message: "foo\nbar"
|
||||
```
|
||||
|
||||
!!! Note
|
||||
Since `dbg` filter accepts '<T: std::fmt::Debug>' types, that type isn't required to implement [`Render`](https://docs.rs/sailfish/latest/sailfish/runtime/trait.Render.html) trait. That means you can pass the type which doesn't implement `Render` trait.
|
||||
Since `dbg` filter accepts `<T: std::fmt::Debug>` types, that type isn't required to implement [`Render`](https://docs.rs/sailfish/latest/sailfish/runtime/trait.Render.html) trait. That means you can pass the type which doesn't implement `Render` trait.
|
||||
|
||||
|
||||
## Syntax
|
||||
|
||||
- Apply filter and HTML escaping
|
||||
|
||||
```ejs
|
||||
``` rhtml
|
||||
<%= expression | filter %>
|
||||
```
|
||||
|
||||
- Apply filter only
|
||||
|
||||
```ejs
|
||||
``` rhtml
|
||||
<%- expression | filter %>
|
||||
```
|
||||
|
||||
|
|
|
@ -6,7 +6,7 @@ Consider the following example.
|
|||
|
||||
- `templates/header.stpl`
|
||||
|
||||
```html
|
||||
``` html
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||
<meta name="format-detection" content="telephone=no">
|
||||
|
@ -15,7 +15,7 @@ Consider the following example.
|
|||
|
||||
- `templates/index.stpl`
|
||||
|
||||
```html
|
||||
``` rhtml
|
||||
<html>
|
||||
<head>
|
||||
<% include!("./header.stpl"); %>
|
||||
|
@ -28,7 +28,7 @@ Consider the following example.
|
|||
|
||||
Then you can see the `header.stpl` is embedded in the output.
|
||||
|
||||
```html
|
||||
``` html
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
|
|
|
@ -10,7 +10,7 @@
|
|||
|
||||
## Condition
|
||||
|
||||
```ejs
|
||||
``` rhtml
|
||||
<% if messages.is_empty() { %>
|
||||
<div>No messages</div>
|
||||
<% } %>
|
||||
|
@ -18,7 +18,7 @@
|
|||
|
||||
## loop
|
||||
|
||||
```ejs
|
||||
``` rhtml
|
||||
<% for (i, msg) in messages.iter().enumerate() { %>
|
||||
<div><%= i %>: <%= msg %></div>
|
||||
<% } %>
|
||||
|
@ -26,21 +26,19 @@
|
|||
|
||||
## Includes
|
||||
|
||||
```ejs
|
||||
``` rhtml
|
||||
<% include!("path/to/template"); %>
|
||||
```
|
||||
|
||||
Unlike EJS, you cannot omit the file extension.
|
||||
|
||||
## Filters
|
||||
|
||||
```ejs
|
||||
``` rhtml
|
||||
<%= message | upper %>
|
||||
```
|
||||
|
||||
```ejs
|
||||
``` rhtml
|
||||
{
|
||||
"id": <%= id %>
|
||||
"comment": <%- comment | dbg %>
|
||||
"comment": <%- comment | json %>
|
||||
}
|
||||
```
|
||||
|
|
|
@ -4,30 +4,56 @@
|
|||
|
||||
You can write Rust statement inside `<% %>` tag.
|
||||
|
||||
```ejs
|
||||
<% let mut total = 0; %>
|
||||
<% for elem in arr.iter().filter(|e| e.is_valid()) { %>
|
||||
<% total += elem.value() as u64; %>
|
||||
<% dbg!(total); %>
|
||||
<% if total > 100 { break; } %>
|
||||
Printed until the total value exceeds 100.
|
||||
<% } %>
|
||||
```
|
||||
=== "Template"
|
||||
|
||||
``` rhtml
|
||||
<%
|
||||
let mut total = 0;
|
||||
for i in 1.. {
|
||||
total += i;
|
||||
if i > 100 {
|
||||
break;
|
||||
}
|
||||
}
|
||||
%>
|
||||
<div>total = <%= total %></div>
|
||||
```
|
||||
|
||||
=== "Result"
|
||||
|
||||
``` html
|
||||
<div>total = 105</div>
|
||||
```
|
||||
|
||||
!!! Note
|
||||
Make sure that you cannot omit braces, parenthesis, and semicolons.
|
||||
|
||||
Sailfish is smart enough to figure out where the code block ends, so you can even include `%>` inside Rust comments or string literals.
|
||||
|
||||
```text
|
||||
<% /* Tag does not ends at %>! */ %>
|
||||
```
|
||||
=== "Template"
|
||||
|
||||
``` text
|
||||
<% /* Tag does not ends at %>! */ %>
|
||||
```
|
||||
|
||||
=== "Result"
|
||||
|
||||
``` text
|
||||
```
|
||||
|
||||
If you need to simply render `<%` character, you can escape it, or use evaluation block (described below).
|
||||
|
||||
```text
|
||||
<%% is converted into <%= "<%" %> character.
|
||||
```
|
||||
=== "Template"
|
||||
|
||||
``` text
|
||||
<%% is converted into <%- "<%" %> character.
|
||||
```
|
||||
|
||||
=== "Result"
|
||||
|
||||
``` text
|
||||
<% is converted into <% character
|
||||
```
|
||||
|
||||
Although almost all Rust statement is supported, the following statements inside templates may cause a strange compilation error.
|
||||
|
||||
|
@ -41,32 +67,41 @@ Although almost all Rust statement is supported, the following statements inside
|
|||
|
||||
Rust expression inside `<%= %>` tag is evaluated and the result will be rendered.
|
||||
|
||||
```ejs
|
||||
<%# The following code simple renders `3` %>
|
||||
<% let a = 1; %><%= a + 2 %>
|
||||
```
|
||||
=== "Template"
|
||||
|
||||
``` rhtml
|
||||
<% let a = 1; %><%= a + 2 %>
|
||||
```
|
||||
|
||||
=== "Result"
|
||||
|
||||
``` text
|
||||
3
|
||||
```
|
||||
|
||||
If the result contains `&"'<>` characters, sailfish replaces these characters with the equivalent html.
|
||||
|
||||
If you want to render the results without escaping, you can use `<%- %>` tag or [configure sailfish to not escape by default](../options.md). For example,
|
||||
If you want to render the results without escaping, you can use `<%- %>` tag or [configure sailfish to not escape by default](../options.md).
|
||||
|
||||
```ejs
|
||||
<div>
|
||||
=== "Template"
|
||||
|
||||
``` rhtml
|
||||
<div>
|
||||
<%- "<h1>Hello, World!</h1>" %>
|
||||
</div>
|
||||
```
|
||||
</div>
|
||||
```
|
||||
|
||||
This template results in the following output.
|
||||
=== "Result"
|
||||
|
||||
```ejs
|
||||
<div>
|
||||
``` html
|
||||
<div>
|
||||
<h1>Hello, World!</h1>
|
||||
</div>
|
||||
```
|
||||
</div>
|
||||
```
|
||||
|
||||
!!! Note
|
||||
Evaluation block does not return any value, so you cannot use the block to pass the render result to another code block. The following code is invalid.
|
||||
|
||||
```
|
||||
``` rhtml
|
||||
<% let result = %><%= 1 %><% ; %>
|
||||
```
|
||||
|
|
|
@ -24,14 +24,20 @@ theme:
|
|||
font:
|
||||
text: 'Ubuntu'
|
||||
code: 'Ubuntu Mono'
|
||||
features:
|
||||
- 'navigation.expand'
|
||||
|
||||
# Extensions
|
||||
markdown_extensions:
|
||||
- admonition
|
||||
- codehilite
|
||||
- footnotes
|
||||
- 'admonition'
|
||||
- 'footnotes'
|
||||
- 'pymdownx.highlight'
|
||||
- 'pymdownx.tabbed'
|
||||
- 'pymdownx.superfences':
|
||||
custom_fences:
|
||||
- name: mermaid
|
||||
class: mermaid
|
||||
|
||||
# Customization
|
||||
extra_css:
|
||||
- 'assets/css/custom.css'
|
||||
|
||||
|
|
Loading…
Reference in New Issue