doc: improve the overall look of the document

2021-01-03 18:00:29 +09:00 · 2021-01-03 18:00:29 +09:00 · 45d8b6651d
parent 8584fa5ca7
commit 45d8b6651d
10 changed files with 139 additions and 73 deletions
--- 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;
 }
--- 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
 <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() {
--- 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.
--- a/docs/en/docs/installation.md
+++ b/docs/en/docs/installation.md
@ -7,7 +7,9 @@ In order to use sailfish templates, you have add two dependencies in your `Cargo
 sailfish = "0.3.0"
 ```

-### Feature Flags
+## Feature Flags
+
+Sailfish accepts the following feature flags

 |Feature|Description|
 |--|--|
--- a/docs/en/docs/options.md
+++ b/docs/en/docs/options.md
@ -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: "%"
--- 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
+=== "Template"
+
+    ``` rhtml
    message: <%= "foo\nbar" | dbg %>
    ```

-Output:
+=== "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 %>
 ```

--- a/docs/en/docs/syntax/includes.md
+++ b/docs/en/docs/syntax/includes.md
@ -15,7 +15,7 @@ Consider the following example.

 - `templates/index.stpl`

-```html
+``` rhtml
 <html>
  <head>
    <% include!("./header.stpl"); %>
--- 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() { %>
  <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 %>
 }
 ```
--- a/docs/en/docs/syntax/tags.md
+++ b/docs/en/docs/syntax/tags.md
@ -4,14 +4,25 @@

 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
@ -19,14 +30,29 @@ You can write Rust statement inside `<% %>` tag.

 Sailfish is smart enough to figure out where the code block ends, so you can even include `%>` inside Rust comments or string literals.

+=== "Template"
+
    ``` text
    <% /* Tag does not ends at %>! */ %>
    ```

-If you need to simply render `<%` character, you can escape it, or use evaluation block (described below).
+=== "Result"

    ``` text
-<%% is converted into <%= "<%" %> character.
+    ```
+
+If you need to simply render `<%` character, you can escape it, or use evaluation block (described below).
+
+=== "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,24 +67,33 @@ 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` %>
+=== "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
+=== "Template"
+
+    ``` rhtml
    <div>
      <%- "<h1>Hello, World!</h1>" %>
    </div>
    ```

-This template results in the following output.
+=== "Result"

-```ejs
+    ``` html
    <div>
      <h1>Hello, World!</h1>
    </div>
@ -67,6 +102,6 @@ This template results in the following output.
 !!! 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 %><% ; %>
    ```
--- 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'