michael/sailfish
michael
/
sailfish
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

doc: improve the overall look of the document

This commit is contained in:
Kogia-sima 2021-01-03 18:00:29 +09:00
parent 8584fa5ca7
commit 45d8b6651d
10 changed files with 139 additions and 73 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/en/docs/assets/css/custom.css
View File

@ -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;
}

8
docs/en/docs/getting-started.md
View File

@ -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() {

7
docs/en/docs/index.md
View File

@ -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.

6
docs/en/docs/installation.md
View File

@ -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|
|--|--|

6
docs/en/docs/options.md
View File

@ -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: "%"

22
docs/en/docs/syntax/filters.md
View File

@ -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: &quot;foo\nbar&quot;
```
=== "Result"
``` html
message: &quot;foo\nbar&quot;
```
!!! 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
docs/en/docs/syntax/includes.md
View File

@ -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">

14
docs/en/docs/syntax/overview.md
View File

@ -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 %>
}
```

99
docs/en/docs/syntax/tags.md
View File

@ -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>
<%- "<h1>Hello, World!</h1>" %>
</div>
```
=== "Template"
This template results in the following output.
``` rhtml
<div>
<%- "<h1>Hello, World!</h1>" %>
</div>
```
```ejs
<div>
<h1>Hello, World!</h1>
</div>
```
=== "Result"
``` html
<div>
<h1>Hello, World!</h1>
</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 %><% ; %>
```

14
docs/en/mkdocs.yml
View File

@ -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'