From 45d8b6651d2c4fc9926159ec822e01bcc5cdcfa4 Mon Sep 17 00:00:00 2001 From: Kogia-sima Date: Sun, 3 Jan 2021 18:00:29 +0900 Subject: [PATCH] doc: improve the overall look of the document --- docs/en/docs/assets/css/custom.css | 30 ++++++++- docs/en/docs/getting-started.md | 8 +-- docs/en/docs/index.md | 7 +-- docs/en/docs/installation.md | 6 +- docs/en/docs/options.md | 6 +- docs/en/docs/syntax/filters.md | 22 ++++--- docs/en/docs/syntax/includes.md | 6 +- docs/en/docs/syntax/overview.md | 14 ++--- docs/en/docs/syntax/tags.md | 99 ++++++++++++++++++++---------- docs/en/mkdocs.yml | 14 +++-- 10 files changed, 139 insertions(+), 73 deletions(-) diff --git a/docs/en/docs/assets/css/custom.css b/docs/en/docs/assets/css/custom.css index 129dffc..f74aeeb 100644 --- a/docs/en/docs/assets/css/custom.css +++ b/docs/en/docs/assets/css/custom.css @@ -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; } diff --git a/docs/en/docs/getting-started.md b/docs/en/docs/getting-started.md index bfbebee..1337b22 100644 --- a/docs/en/docs/getting-started.md +++ b/docs/en/docs/getting-started.md @@ -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 <% for msg in &messages { %> @@ -26,13 +26,13 @@ templates/ ## Render the template -Import the sailfish crates: +
  1. Import the sailfish crates:
```rust use sailfish::TemplateOnce; ``` -Define the template struct to be rendered: +
  1. Define the template struct to be rendered:
```rust #[derive(TemplateOnce)] // automatically implement `TemplateOnce` trait @@ -43,7 +43,7 @@ struct HelloTemplate { } ``` -And render the data with `render_once()` method. +
  1. Render the data with render_once() method.
```rust fn main() { diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md index d5fa229..c6bc0b6 100644 --- a/docs/en/docs/index.md +++ b/docs/en/docs/index.md @@ -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. diff --git a/docs/en/docs/installation.md b/docs/en/docs/installation.md index 9980df7..11bd3fb 100644 --- a/docs/en/docs/installation.md +++ b/docs/en/docs/installation.md @@ -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| |--|--| diff --git a/docs/en/docs/options.md b/docs/en/docs/options.md index e8e58a1..ad8b3c6 100644 --- a/docs/en/docs/options.md +++ b/docs/en/docs/options.md @@ -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: "%" diff --git a/docs/en/docs/syntax/filters.md b/docs/en/docs/syntax/filters.md index e5bf32d..b2f47d1 100644 --- a/docs/en/docs/syntax/filters.md +++ b/docs/en/docs/syntax/filters.md @@ -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 '' 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 `` 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 %> ``` diff --git a/docs/en/docs/syntax/includes.md b/docs/en/docs/syntax/includes.md index 972a11a..1843d08 100644 --- a/docs/en/docs/syntax/includes.md +++ b/docs/en/docs/syntax/includes.md @@ -6,7 +6,7 @@ Consider the following example. - `templates/header.stpl` -```html +``` html @@ -15,7 +15,7 @@ Consider the following example. - `templates/index.stpl` -```html +``` rhtml <% 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 diff --git a/docs/en/docs/syntax/overview.md b/docs/en/docs/syntax/overview.md index 9402f32..1bfb01f 100644 --- a/docs/en/docs/syntax/overview.md +++ b/docs/en/docs/syntax/overview.md @@ -10,7 +10,7 @@ ## Condition -```ejs +``` rhtml <% if messages.is_empty() { %>
No messages
<% } %> @@ -18,7 +18,7 @@ ## loop -```ejs +``` rhtml <% for (i, msg) in messages.iter().enumerate() { %>
<%= i %>: <%= msg %>
<% } %> @@ -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 %> } ``` diff --git a/docs/en/docs/syntax/tags.md b/docs/en/docs/syntax/tags.md index d1997d4..c298228 100644 --- a/docs/en/docs/syntax/tags.md +++ b/docs/en/docs/syntax/tags.md @@ -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; + } + } + %> +
total = <%= total %>
+ ``` + +=== "Result" + + ``` html +
total = 105
+ ``` !!! 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 -
- <%- "

Hello, World!

" %> -
-``` +=== "Template" -This template results in the following output. + ``` rhtml +
+ <%- "

Hello, World!

" %> +
+ ``` -```ejs -
-

Hello, World!

-
-``` +=== "Result" + + ``` html +
+

Hello, World!

+
+ ``` !!! 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 %><% ; %> ``` diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml index 728ef2f..e9c527f 100644 --- a/docs/en/mkdocs.yml +++ b/docs/en/mkdocs.yml @@ -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'