diff --git a/posts/meta.md b/posts/meta.md index e308ca0..cc39e1f 100644 --- a/posts/meta.md +++ b/posts/meta.md @@ -34,7 +34,7 @@ All the standard Markdown are supported (headers, bolds, italics, images, links, It also has a very cool warnings feature, which isn't used in this project, but can be seen in action if you use the [Makoto Web Editor](https://makoto.prussia.dev). ### Ryuji -Ryuji is a simple templating system that supports `if` statements, `for` loops, components, and inserting variables. It isn't quite as fully featured as Jinja/Nunjucks, but on the upside, Ryuji is around just 200 lines of code, and worked very well for my usecase. I think it's pretty cool. +Ryuji is a simple templating system that supports `if` statements, `for` loops, components, and inserting variables. It isn't quite as fully featured as Jinja/Nunjucks, but on the upside, Ryuji is less than 280 lines of code, and worked very well for my usecase. I think it's pretty cool. Here's a quick overview of the syntax: diff --git a/posts/ryuji_docs.md b/posts/ryuji_docs.md index d94355b..51585f8 100644 --- a/posts/ryuji_docs.md +++ b/posts/ryuji_docs.md @@ -1 +1,207 @@ -The Ryuji docs are under construction. Beep beep beep. +Ryuji is a templating language written in less than 280 lines of code. There are no dependencies besides the builtin Node.js module `fs`. If that is an issue (eg, running in a browser environment), it should be very straightforward to remove the dependency by deleting the `render_template` function and using the `render` function directory. + +# Syntax Docs + +Ryuji syntax is typically in the format `[[ something ]]` or `[[ some:thing ]]` (with more `:`s if necessary). The spaces matter! Specifically, Ryuji checks for syntax using the regex statement: `/\[\[ [a-zA-Z0-9.:\-_!]+ \]\]/g`. + +## Variables +```html +
Hi [[ employee.name ]],
+You may recently heard some distressing news about your colleague Dave.
+Please rest assured that these reports are false and exaggerated. Although he may be charged with [[ current_manslaughter_count ]] counts of manslaughter, we believe that these charges will be dismissed.
+[[ corporate_slogan ]]
+``` + +## Non-HTML Escaped Variables +```html +We don't think you should order the cheeseburger.
+[[ endif ]] +``` + +## If Not Comparison Statements +```html +[[ if:user.lactose_intolerant:user.vegan ]] +We don't think you should order the cheeseburger.
+[[ endif ]] +``` + +## Components +```html +[[ component:nav-bar ]] +Blah blah blah blah.
+``` + +*templates/components/navbar.html* + +```html + + +``` + +```html +[[ for trees:tree ]] + [[ component:tree-info ]] +[[ endfor ]] +``` + +*templates/components/tree-info.html* + +```html +Favourite song: [[ tree.favourite_song ]], Likes Dave: [[ tree.likes_dave ]]
+``` + +## Notes +- For loops can be nested. +- Components can have other components inside them (but there is a depth limit of 4 or 5 or 6 nested within each other, I forgot). + +# API/Library Docs + +## Class: Renderer + +### `constructor` +Creates an instance of the `Renderer` class. + +**Parameters:** +- `templates_dir` (`string`): Templates directory. +- `components_dir` (`string`): Components directory. +- `file_extension` (`\`.${string}\``, optional, default is `".html"`): File extension of templates. + +### `render` +Render a template given template contents and variables. + +**Parameters:** +- `template_contents` (`string`): Content of template. +- `vars` (`any`, optional but highly recommended): Dictionary/object of variables to render template with. +- `recursion_layer` (`number`, optional, defaults to `0`): Used internally to prevent infinite loops when templates circularly refer to each other. + +**Returns:** `string` (the rendered template) + +### `render_template` +Render a template given the template name. Basically, gets the contents of the template and then calls `render`. + +**Parameters:** +- `template_name` (`string`): The name of the template. +- `vars` (`any`, optional but highly recommended): Dictionary/object of variables to render template with. +- `recursion_layer` (`number`, optional, defaults to `0`): Used internally to prevent infinite loops when templates circularly refer to each other. + +**Returns:** `string` (the rendered template) + +### `remove_empty_lines` (static) +Removes empty lines from text. + +**Parameters:** +- `text` (`string`): Text to rid empty lines from. + +### `concat_path` (static) +Adds two paths together. Mostly intended for internal use only. + +**Parameters:** +- `path1` (`string`): First path. +- `path2` (`string`): Second path. + +**Returns:** `string` (`path1` added to `path2`) + +### `sanitize` (static) +Sanitizes text to make sure it cannot render as HTML. It replaces "<" with the HTML entity "&\lt;" and ">" with the HTML entity "&\gt;". Automatically done to + +**Parameters:** +- `non_html` (`string`): The text to sanitize. + +**Returns:** `string` (the sanitized text) + +### `check_var_name_legality` (static) +Checks to make sure a variable name is legal. Intended for internal use. + +**Parameters:** +- `var_name` (`string`): The variable name to check. +- `dot_allowed` (`boolean`, optional, default is `true`): Whether "." is allowed in the variable name. + +**Returns:** `boolean` (`true` is variable name is legal, `false` otherwise) + +### `get_var` (static) +Gets the value of a variable, errors if variable undefined. Intended for internal use. + +**Parameters:** +- `var_name` (`string`): Name of variable. +- `vars` (`any`, optional but highly recommended): Dictionary/object of variables to get value from. + +**Returns:** `any` (the value of the variable) + +### Properties +- `templates_dir`: `string` +- `components_dir`: `string` +- `file_extension`: `\`.${string}\`` (see in Types/Interfaces/Consts `file_extension`) + +## Types/Interfaces/Consts +These are exported, but there is no real use for them (outside of the module obviously), with the possible exception of writing an extension to Ryuji. Feel free to skip this section. + +- `const SYNTAX_REGEX`: Regex to search for Ryuji syntax. +- `type file_extension`: Typescript type `\`.${string}\``, that represents... file extensions. Shocker. +- `interface ForLoopInfo`: Used internally for Ryuji's for loops. + +# Usage Examples +Check Ryuji's [tests](https://github.com/jetstream0/hedgeblog/blob/master/tests.ts) for more examples. + +There is a real world example in [hedgeblog's code](https://github.com/jetstream0/hedgeblog). For a syntax example, look in the `templates` [directory](https://github.com/jetstream0/hedgeblog/tree/master/templates), or an API example in `saki.ts` and `index.ts`. diff --git a/posts/saki_docs.md b/posts/saki_docs.md index d47ed71..407867e 100644 --- a/posts/saki_docs.md +++ b/posts/saki_docs.md @@ -1 +1,112 @@ -The Ryuji docs are under construction. Vroom vroom. Oh no daves operating the bulldozer drunk again gimme a second +Saki is a very simple static build system, written in Typescript. There are no dependencies besides the builtin Node.js modules `fs` and `path`. + +# Class: Builder + +## `constructor` +Creates an instance of the `Builder` class. + +**Parameters:** +- `build_dir` (`string`, optional, default is `"/build"`): The directory to output the build to. + +## `copy_folder` (static) +Copies a directory to another directory. Used internally in `serve_static_folder`, there is probably no need to use this. + +**Parameters:** +- `folder_path` (`string`): Path to directory that should be copied. +- `dest_path` (`string`): Path to directory to copy to. + +## `serve_static_folder` +Adds a static folder to the build directory, meaning that it will be served. + +**Parameters:** +- `static_dir` (`string`): The path to the static directory to serve +- `dest_path` (`string`, optional, default is `"/"`): The path that the static directory should be served under. For example, if the static directory has a file "example.png", if the `dest_path` is `"/"`, the file will be written to `"/