docs: add start of book

0b10011 · Dec 23, 2024 · 6c62528 · 6c62528
1 parent 05cf996
commit 6c62528
Show file tree

Hide file tree

Showing 9 changed files with 165 additions and 0 deletions.
diff --git a/.github/workflows/book.yml b/.github/workflows/book.yml
@@ -0,0 +1,39 @@
+name: Book Deploy
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write  # To push a branch 
+      pages: write  # To push to a GitHub Pages site
+      id-token: write # To update the deployment status
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - name: Install latest mdbook
+        run: |
+          tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
+          url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
+          mkdir mdbook
+          curl -sSL $url | tar -xz --directory=./mdbook
+          echo `pwd`/mdbook >> $GITHUB_PATH
+      - name: Build Book
+        run: |
+          # This assumes your book is in the root of your repository.
+          # Just add a `cd` here if you need to change to another directory.
+          mdbook build
+      - name: Setup Pages
+        uses: actions/configure-pages@v4
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          # Upload entire repository
+          path: 'book-output'
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,3 @@
 /target
 Cargo.lock
+/book-output
diff --git a/book.toml b/book.toml
@@ -0,0 +1,20 @@
+[book]
+authors = ["Brandon Frohs"]
+language = "en"
+multilingual = false
+src = "book"
+title = "Oxiplate Documentation"
+
+[rust]
+edition = "2021"
+
+[build]
+build-dir = "book-output"
+
+[output.html]
+git-repository-url = "https://github.com/0b10011/oxiplate"
+edit-url-template = "https://github.com/0b10011/oxiplate/edit/main/{path}"
+site-url = "/oxiplate/"
+
+[output.html.playground]
+runnable = false
diff --git a/book/README.md b/book/README.md
@@ -0,0 +1,17 @@
+# Oxiplate: Template engine for Rust
+
+**Oxiplate is experimental and features described here may not yet be implemented, or may be implemented in a different way.**
+
+## Template syntax
+
+The syntax for templates is similar to many other systems, but the terminology may be slightly different.
+
+A **writ** is an [**expression**](#expressions) wrapped with `{{` and `}}` that will be evaluated and output into the template. For example, `Hello {{ name }}!` may become `Hello Luna!`.
+
+A [**statement**](#statements) is wrapped with `{%` and `%}` and includes variable assignments and control structures. See the [**statement**](#statements) section for a list of possible statements.
+
+A **comment** is text wrapped with `{#` and `#}` that will be removed from the final template, but can be useful to the template designer(s). For example, `{# None of this text would show up in the final template. #}`.
+
+Whitespace before and after **tags** can be removed or collapsed. See the [whitespace control](#whitespace-control) section for more information.
+
+Anything else in the template is considered **static** and will be left as-is.
diff --git a/book/SUMMARY.md b/book/SUMMARY.md
@@ -0,0 +1,18 @@
+# Summary
+
+[Introduction](README.md)
+
+# User guide
+
+- [Getting started]()
+
+# Syntax
+
+- [Writs]()
+- [Statements]()
+    - [extends/block](statements/extends.md)
+    - [if/else](statements/if-else.md)
+    - [for](statements/for.md)
+- [Comments]()
+- [Whitespace control](whitespace-control.md)
+- [Expressions]()
diff --git a/book/statements/extends.md b/book/statements/extends.md
@@ -0,0 +1,27 @@
+# Extending templates
+
+```oxip
+{# layout.html.oxip -#}
+
+<!DOCTYPE html>
+<main>{% block content %}{% endblock %}</main>
+```
+
+```oxip
+{# your-content.html.oxip -#}
+
+{% extends "layout.html.oxip" %}
+
+{% block content %}
+  <h1>Your content</h1>
+  <p>Goes here...</p>
+{% endblock %}
+```
+
+```html
+<!DOCTYPE html>
+<main>
+  <h1>Your content</h1>
+  <p>Goes here...</p>
+</main>
+```
diff --git a/book/statements/for.md b/book/statements/for.md
@@ -0,0 +1,9 @@
+# for
+
+```oxip
+<ul>
+  {% for name in names %}
+    <li>{{ name }}
+  {% endfor %}
+</ul>
+```
diff --git a/book/statements/if-else.md b/book/statements/if-else.md
@@ -0,0 +1,31 @@
+# if/else
+
+```rust
+#[derive(Oxiplate)]
+#[oxiplate = "template.html.oxip"]
+struct YourStruct {
+    count: i64,
+}
+```
+
+```rust
+print!("{}", YourStruct {
+    count: 19,
+});
+```
+
+```oxip
+<p>
+    {%- if count < 0 -%}
+        {{ count }} is negative
+    {%- elseif count > 0 -%}
+        {{ count }} is positive
+    {%- else -%}
+        {{ count }} is zero
+    {%- endif -%}
+</p>
+```
+
+```html
+<p>19 is positive</p>
+```
diff --git a/book/whitespace-control.md b/book/whitespace-control.md
@@ -0,0 +1,3 @@
+# Whitespace control
+
+Whitespace (spaces, tabs, newlines, etc) that comes before a **tag** can be removed by appending `-` to the open sequence (`{{-`, `{%-`, or `{#-`), or collapsed to a single space (` `) by appending `_` to the open tag (`{{_`, `{%_`, or `{#_`). The same is true for whitespace that comes after, but by prefixing the close sequence with the whitespace control characters (`-}}`, `-%}`, or `-#}` to remove; `_}}`, `_%}`, `_#}` to collapse).
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# Whitespace control

		Whitespace (spaces, tabs, newlines, etc) that comes before a tag can be removed by appending `-` to the open sequence (`{{-`, `{%-`, or `{#-`), or collapsed to a single space (` `) by appending `_` to the open tag (`{{_`, `{%_`, or `{#_`). The same is true for whitespace that comes after, but by prefixing the close sequence with the whitespace control characters (`-}}`, `-%}`, or `-#}` to remove; `_}}`, `_%}`, `_#}` to collapse).