doc: improve the overall look of the document
This commit is contained in:
parent
8584fa5ca7
commit
45d8b6651d
|
@ -7,9 +7,35 @@
|
||||||
}
|
}
|
||||||
|
|
||||||
.md-typeset code {
|
.md-typeset code {
|
||||||
|
background-color: rgb(240, 240, 240);
|
||||||
font-size: .95em;
|
font-size: .95em;
|
||||||
}
|
}
|
||||||
|
|
||||||
.md-typeset .admonition {
|
.md-typeset pre > code {
|
||||||
font-size: .75rem;
|
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`.
|
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>
|
<html>
|
||||||
<body>
|
<body>
|
||||||
<% for msg in &messages { %>
|
<% for msg in &messages { %>
|
||||||
|
@ -26,13 +26,13 @@ templates/
|
||||||
|
|
||||||
## Render the template
|
## Render the template
|
||||||
|
|
||||||
Import the sailfish crates:
|
<ol><li>Import the sailfish crates:</li></ol>
|
||||||
|
|
||||||
```rust
|
```rust
|
||||||
use sailfish::TemplateOnce;
|
use sailfish::TemplateOnce;
|
||||||
```
|
```
|
||||||
|
|
||||||
Define the template struct to be rendered:
|
<ol start="2"><li>Define the template struct to be rendered:</li></ol>
|
||||||
|
|
||||||
```rust
|
```rust
|
||||||
#[derive(TemplateOnce)] // automatically implement `TemplateOnce` trait
|
#[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
|
```rust
|
||||||
fn main() {
|
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).
|
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 ?
|
## 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.
|
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.)
|
- Write a Rust code directly inside templates, supporting many Rust syntax (struct definition, closure, macro invocation, etc.)
|
||||||
- Built-in filters
|
- [Built-in filters](https://docs.rs/sailfish/latest/sailfish/runtime/filter/index.html)
|
||||||
- Relatively small number of dependencies (<15 crates in total)
|
- Minimal dependencies (<15 crates in total)
|
||||||
- Extremely fast (See [benchmarks](https://github.com/djc/template-benchmarks-rs))
|
- 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.
|
- 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))
|
- 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.
|
- 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`.
|
In order to use sailfish templates, you have add two dependencies in your `Cargo.toml`.
|
||||||
|
|
||||||
```toml
|
``` toml
|
||||||
[dependencies]
|
[dependencies]
|
||||||
sailfish = "0.3.0"
|
sailfish = "0.3.0"
|
||||||
```
|
```
|
||||||
|
|
||||||
### Feature Flags
|
## Feature Flags
|
||||||
|
|
||||||
|
Sailfish accepts the following feature flags
|
||||||
|
|
||||||
|Feature|Description|
|
|Feature|Description|
|
||||||
|--|--|
|
|--|--|
|
||||||
|
|
|
@ -4,7 +4,7 @@
|
||||||
|
|
||||||
You can control the rendering behaviour via `template` attribute.
|
You can control the rendering behaviour via `template` attribute.
|
||||||
|
|
||||||
```rust
|
``` rust
|
||||||
#[derive(TemplateOnce)]
|
#[derive(TemplateOnce)]
|
||||||
#[template(path = "template.stpl", escape = false)]
|
#[template(path = "template.stpl", escape = false)]
|
||||||
struct TemplateStruct {
|
struct TemplateStruct {
|
||||||
|
@ -21,7 +21,7 @@ struct TemplateStruct {
|
||||||
|
|
||||||
You can split the options into multiple `template` attributes.
|
You can split the options into multiple `template` attributes.
|
||||||
|
|
||||||
```rust
|
``` rust
|
||||||
#[derive(TemplateOnce)]
|
#[derive(TemplateOnce)]
|
||||||
#[template(path = "template.stpl")]
|
#[template(path = "template.stpl")]
|
||||||
#[template(delimiter = '?')]
|
#[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.
|
Configuration files are written in the YAML 1.2 format. Here is the default configuration.
|
||||||
|
|
||||||
```
|
``` yaml
|
||||||
template_dir: "templates"
|
template_dir: "templates"
|
||||||
escape: true
|
escape: true
|
||||||
delimiter: "%"
|
delimiter: "%"
|
||||||
|
|
|
@ -4,31 +4,33 @@ Filters are used to format the rendered contents.
|
||||||
|
|
||||||
Example:
|
Example:
|
||||||
|
|
||||||
```ejs
|
=== "Template"
|
||||||
message: <%= "foo\nbar" | dbg %>
|
|
||||||
```
|
|
||||||
|
|
||||||
Output:
|
``` rhtml
|
||||||
|
message: <%= "foo\nbar" | dbg %>
|
||||||
|
```
|
||||||
|
|
||||||
```html
|
=== "Result"
|
||||||
message: "foo\nbar"
|
|
||||||
```
|
``` html
|
||||||
|
message: "foo\nbar"
|
||||||
|
```
|
||||||
|
|
||||||
!!! Note
|
!!! 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
|
## Syntax
|
||||||
|
|
||||||
- Apply filter and HTML escaping
|
- Apply filter and HTML escaping
|
||||||
|
|
||||||
```ejs
|
``` rhtml
|
||||||
<%= expression | filter %>
|
<%= expression | filter %>
|
||||||
```
|
```
|
||||||
|
|
||||||
- Apply filter only
|
- Apply filter only
|
||||||
|
|
||||||
```ejs
|
``` rhtml
|
||||||
<%- expression | filter %>
|
<%- expression | filter %>
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
|
@ -6,7 +6,7 @@ Consider the following example.
|
||||||
|
|
||||||
- `templates/header.stpl`
|
- `templates/header.stpl`
|
||||||
|
|
||||||
```html
|
``` html
|
||||||
<meta charset="UTF-8">
|
<meta charset="UTF-8">
|
||||||
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
|
||||||
<meta name="format-detection" content="telephone=no">
|
<meta name="format-detection" content="telephone=no">
|
||||||
|
@ -15,7 +15,7 @@ Consider the following example.
|
||||||
|
|
||||||
- `templates/index.stpl`
|
- `templates/index.stpl`
|
||||||
|
|
||||||
```html
|
``` rhtml
|
||||||
<html>
|
<html>
|
||||||
<head>
|
<head>
|
||||||
<% include!("./header.stpl"); %>
|
<% include!("./header.stpl"); %>
|
||||||
|
@ -28,7 +28,7 @@ Consider the following example.
|
||||||
|
|
||||||
Then you can see the `header.stpl` is embedded in the output.
|
Then you can see the `header.stpl` is embedded in the output.
|
||||||
|
|
||||||
```html
|
``` html
|
||||||
<html>
|
<html>
|
||||||
<head>
|
<head>
|
||||||
<meta charset="UTF-8">
|
<meta charset="UTF-8">
|
||||||
|
|
|
@ -10,7 +10,7 @@
|
||||||
|
|
||||||
## Condition
|
## Condition
|
||||||
|
|
||||||
```ejs
|
``` rhtml
|
||||||
<% if messages.is_empty() { %>
|
<% if messages.is_empty() { %>
|
||||||
<div>No messages</div>
|
<div>No messages</div>
|
||||||
<% } %>
|
<% } %>
|
||||||
|
@ -18,7 +18,7 @@
|
||||||
|
|
||||||
## loop
|
## loop
|
||||||
|
|
||||||
```ejs
|
``` rhtml
|
||||||
<% for (i, msg) in messages.iter().enumerate() { %>
|
<% for (i, msg) in messages.iter().enumerate() { %>
|
||||||
<div><%= i %>: <%= msg %></div>
|
<div><%= i %>: <%= msg %></div>
|
||||||
<% } %>
|
<% } %>
|
||||||
|
@ -26,21 +26,19 @@
|
||||||
|
|
||||||
## Includes
|
## Includes
|
||||||
|
|
||||||
```ejs
|
``` rhtml
|
||||||
<% include!("path/to/template"); %>
|
<% include!("path/to/template"); %>
|
||||||
```
|
```
|
||||||
|
|
||||||
Unlike EJS, you cannot omit the file extension.
|
|
||||||
|
|
||||||
## Filters
|
## Filters
|
||||||
|
|
||||||
```ejs
|
``` rhtml
|
||||||
<%= message | upper %>
|
<%= message | upper %>
|
||||||
```
|
```
|
||||||
|
|
||||||
```ejs
|
``` rhtml
|
||||||
{
|
{
|
||||||
"id": <%= id %>
|
"id": <%= id %>
|
||||||
"comment": <%- comment | dbg %>
|
"comment": <%- comment | json %>
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
|
@ -4,30 +4,56 @@
|
||||||
|
|
||||||
You can write Rust statement inside `<% %>` tag.
|
You can write Rust statement inside `<% %>` tag.
|
||||||
|
|
||||||
```ejs
|
=== "Template"
|
||||||
<% let mut total = 0; %>
|
|
||||||
<% for elem in arr.iter().filter(|e| e.is_valid()) { %>
|
``` rhtml
|
||||||
<% total += elem.value() as u64; %>
|
<%
|
||||||
<% dbg!(total); %>
|
let mut total = 0;
|
||||||
<% if total > 100 { break; } %>
|
for i in 1.. {
|
||||||
Printed until the total value exceeds 100.
|
total += i;
|
||||||
<% } %>
|
if i > 100 {
|
||||||
```
|
break;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
%>
|
||||||
|
<div>total = <%= total %></div>
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Result"
|
||||||
|
|
||||||
|
``` html
|
||||||
|
<div>total = 105</div>
|
||||||
|
```
|
||||||
|
|
||||||
!!! Note
|
!!! Note
|
||||||
Make sure that you cannot omit braces, parenthesis, and semicolons.
|
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.
|
Sailfish is smart enough to figure out where the code block ends, so you can even include `%>` inside Rust comments or string literals.
|
||||||
|
|
||||||
```text
|
=== "Template"
|
||||||
<% /* Tag does not ends at %>! */ %>
|
|
||||||
```
|
``` 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).
|
If you need to simply render `<%` character, you can escape it, or use evaluation block (described below).
|
||||||
|
|
||||||
```text
|
=== "Template"
|
||||||
<%% is converted into <%= "<%" %> character.
|
|
||||||
```
|
``` 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.
|
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.
|
Rust expression inside `<%= %>` tag is evaluated and the result will be rendered.
|
||||||
|
|
||||||
```ejs
|
=== "Template"
|
||||||
<%# The following code simple renders `3` %>
|
|
||||||
<% let a = 1; %><%= a + 2 %>
|
``` rhtml
|
||||||
```
|
<% let a = 1; %><%= a + 2 %>
|
||||||
|
```
|
||||||
|
|
||||||
|
=== "Result"
|
||||||
|
|
||||||
|
``` text
|
||||||
|
3
|
||||||
|
```
|
||||||
|
|
||||||
If the result contains `&"'<>` characters, sailfish replaces these characters with the equivalent html.
|
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
|
=== "Template"
|
||||||
<div>
|
|
||||||
|
``` rhtml
|
||||||
|
<div>
|
||||||
<%- "<h1>Hello, World!</h1>" %>
|
<%- "<h1>Hello, World!</h1>" %>
|
||||||
</div>
|
</div>
|
||||||
```
|
```
|
||||||
|
|
||||||
This template results in the following output.
|
=== "Result"
|
||||||
|
|
||||||
```ejs
|
``` html
|
||||||
<div>
|
<div>
|
||||||
<h1>Hello, World!</h1>
|
<h1>Hello, World!</h1>
|
||||||
</div>
|
</div>
|
||||||
```
|
```
|
||||||
|
|
||||||
!!! Note
|
!!! 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.
|
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 %><% ; %>
|
<% let result = %><%= 1 %><% ; %>
|
||||||
```
|
```
|
||||||
|
|
|
@ -24,14 +24,20 @@ theme:
|
||||||
font:
|
font:
|
||||||
text: 'Ubuntu'
|
text: 'Ubuntu'
|
||||||
code: 'Ubuntu Mono'
|
code: 'Ubuntu Mono'
|
||||||
|
features:
|
||||||
|
- 'navigation.expand'
|
||||||
|
|
||||||
# Extensions
|
# Extensions
|
||||||
markdown_extensions:
|
markdown_extensions:
|
||||||
- admonition
|
- 'admonition'
|
||||||
- codehilite
|
- 'footnotes'
|
||||||
- footnotes
|
- 'pymdownx.highlight'
|
||||||
|
- 'pymdownx.tabbed'
|
||||||
|
- 'pymdownx.superfences':
|
||||||
|
custom_fences:
|
||||||
|
- name: mermaid
|
||||||
|
class: mermaid
|
||||||
|
|
||||||
# Customization
|
|
||||||
extra_css:
|
extra_css:
|
||||||
- 'assets/css/custom.css'
|
- 'assets/css/custom.css'
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue