diff --git a/docs/en/docs/getting-started.md b/docs/en/docs/getting-started.md new file mode 100644 index 0000000..fb8d387 --- /dev/null +++ b/docs/en/docs/getting-started.md @@ -0,0 +1,64 @@ +# Getting Started + +## Prepare the template file + +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 + + + <% for msg in &messages { %> +
<%= msg %>
+ <% } %> + + +``` + +Now your project structure should be like this: + +```text +Cargo.toml +src/ + (Source files) +templates/ + hello.stpl +``` + +## Render the template + +Import the sailfish crates: + +```rust +#[macro_use] +extern crate sailfish_macros; // enable derive macros + +use sailfish::TemplateOnce; // import `TemplateOnce` trait +``` + +Define the template struct to be rendered: + +```rust +#[derive(TemplateOnce)] // automatically implement `TemplateOnce` trait +#[template(path = "hello.stpl")] // specify the path to template +struct HelloTemplate<'a> { + // data to be passed to the template + messages: &'a [String], +} +``` + +And render the data with `render_once()` method. + +```rust +fn main() { + let ctx = HelloTemplate { + messages: &[String::from("foo"), String::from("bar")]; + } + + // Now render templates with given data + println!("{}", ctx.render_once().unwrap()); +} +``` + +That's it! + +You can find more examples in the [example](https://github.com/Kogia-sima/sailfish/tree/master/examples) directory in the sailfish repository. diff --git a/docs/en/docs/images/favicon.ico b/docs/en/docs/images/favicon.ico new file mode 100644 index 0000000..1113624 Binary files /dev/null and b/docs/en/docs/images/favicon.ico differ diff --git a/docs/en/docs/images/logo.svg b/docs/en/docs/images/logo.svg new file mode 100644 index 0000000..1b74f45 --- /dev/null +++ b/docs/en/docs/images/logo.svg @@ -0,0 +1,39 @@ + + + + + + + image/svg+xml + + + + + + + + + + + diff --git a/docs/en/docs/index.md b/docs/en/docs/index.md new file mode 100644 index 0000000..f6df61f --- /dev/null +++ b/docs/en/docs/index.md @@ -0,0 +1,35 @@ +# Welcome to Sailfish Documentation! + +Sailfish is a simple, small, and extremely fast template engine for Rust. This documentation guides you how to get started with 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 ? + +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 definision, closure, macro invocation, etc.) +- Relatively small number of dependencies (<15 crates in total) +- Extremely fast (See [benchmarks](http://github.com/Kogia-sima/sailfish/blob/master/benches)) +- 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. + +## Upcoming features + +Since sailfish is on early stage of development, there are many upcoming features that is not supported yet. You can find many [RFC](https://github.com/Kogia-sima/sailfish/issues?q=is%3Aissue+is%3Aopen+label%3A%22Type%3A+RFC%22)s in my repository. These RFCs include: + +- Dynamic Template Loading +- Filter +- `Template` trait (which does not consume itself) + +If you have any idea about them or want to implement that feature, please send a comment on the issue! + +## License + +Copyright © 2020 Ryohei Machida + +This project is [MIT](https://github.com/Kogia-sima/sailfish/blob/master/LICENSE) licensed diff --git a/docs/en/docs/installation.md b/docs/en/docs/installation.md new file mode 100644 index 0000000..ed926c1 --- /dev/null +++ b/docs/en/docs/installation.md @@ -0,0 +1,13 @@ +# Installation + +In order to use sailfish templates, you have add two dependencies in your `Cargo.toml`. + +```toml +[dependencies] +sailfish = "0.0.3" +sailfish-macros = "0.0.3" +``` + +`sailfish` crate contains runtime for rendering contents, and `sailfish-macros` serves you derive macros to compile and import the template files. + +These crates are separated so that Rust compiler can compile them independently. This separation makes your compilation faster! diff --git a/docs/en/docs/options.md b/docs/en/docs/options.md new file mode 100644 index 0000000..72a3160 --- /dev/null +++ b/docs/en/docs/options.md @@ -0,0 +1,30 @@ +# Derive Options + +You can control the rendering behaviour via `template` attribute. + +```rust +#[derive(TemplateOnce)] +#[template(path = "template.stpl", escape = false)] +struct TemplateStruct { + ... +} +``` + +`template` attribute accepts the following options. + +- `path`: path to template file. This options is always required. +- `escape`: Enable HTML escaping (default: `false`) +- `delimiter`: Replace the '%' character used for the tag delimiter (default: '%') +- `rm_whitespace`: try to strip whitespaces as much as possible without collapsing HTML structure (default: `false`). This option might not work correctly if your templates have inline `script` tag. + +You can split the options into multiple `template` attributes. + +```rust +#[derive(TemplateOnce)] +#[template(path = "template.stpl")] +#[template(delimiter = '?')] +#[template(rm_whitespace = true)] +struct TemplateStruct { + ... +} +``` diff --git a/docs/en/docs/syntax/overview.md b/docs/en/docs/syntax/overview.md new file mode 100644 index 0000000..fde9f58 --- /dev/null +++ b/docs/en/docs/syntax/overview.md @@ -0,0 +1,37 @@ +# Template Syntax Overview + +## Tags + +- `<% %>`: Inline tag, you can write Rust code inside this tag +- `<%= %>`: Evaluate the Rust expression and outputs the value into the template (HTML escaped) +- `<%- %>`: Evaluate the Rust expression and outputs the unescaped value into the template +- `<%# %>`: Comment tag +- `<%%`: Outputs a literal '<%' + +## Condition + +```ejs +<% if messages.is_empty() { %> +
No messages
+<% } %> +``` + +## loop + +```ejs +<% for (i, msg) in messages.iter().enumerate() { %> +
<%= i %>: <%= msg %>
+<% } %> +``` + +## Includes + +```ejs +<% include!("path/to/template"); %> +``` + +Unlike EJS, you cannot omit the file extension. + +## Helpers + +(Work in progress) diff --git a/docs/en/mkdocs.yml b/docs/en/mkdocs.yml new file mode 100644 index 0000000..f556c47 --- /dev/null +++ b/docs/en/mkdocs.yml @@ -0,0 +1,49 @@ +# Project information +site_name: 'Sailfish Documentation' +# site_description: 'Sailfish Documentation' +site_author: 'Ryohei Machida' +# site_url: 'https://***.com' + +# Copyright +copyright: '© 2020 Ryohei Machida' + +# Repository +repo_name: 'Kogia-sima/sailfish' +repo_url: 'https://github.com/Kogia-sima/sailfish' + +# Configuration +theme: + name: 'material' + language: 'en' + logo: 'images/logo.svg' + palette: + scheme: 'default' + primary: 'deep purple' + accent: 'deep purple' + favicon: 'images/favicon.ico' + font: + text: 'Ubuntu' + code: 'Ubuntu Mono' + +# Extensions +markdown_extensions: + - codehilite + - footnotes + +# Customization +# extra_css: +# - 'assets/css/custom.css' + +extra: + social: + - icon: 'fontawesome/brands/github-alt' + link: 'https://github.com/Kogia-sima' + +# Page tree +nav: + - 'Welcome': 'index.md' + - 'Installation': 'installation.md' + - 'Getting Started': 'getting-started.md' + - 'Options': 'options.md' + - 'Syntax': + - 'Overview': 'syntax/overview.md' diff --git a/netlify.toml b/netlify.toml new file mode 100644 index 0000000..9eafdf1 --- /dev/null +++ b/netlify.toml @@ -0,0 +1,7 @@ +[build] +command = "python3 scripts/build-docs.py" +publish = "site" + +[[redirects]] + from = "/*" + to = "/en/:splat" diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..3ef9d7d --- /dev/null +++ b/requirements.txt @@ -0,0 +1,2 @@ +mkdocs-material==5.2.3 +mkdocs==1.1.2 diff --git a/runtime.txt b/runtime.txt new file mode 100644 index 0000000..d70c8f8 --- /dev/null +++ b/runtime.txt @@ -0,0 +1 @@ +3.6