From 24cfcbae9ba907e7601542cfdf795b3ed6ceb639 Mon Sep 17 00:00:00 2001 From: Oscar Otero Date: Mon, 13 Jan 2025 13:57:38 +0100 Subject: [PATCH] updated docs theme --- ...etting-started.md => 1.getting-started.md} | 8 ++--- docs/{configuration.md => 2.configuration.md} | 17 +++++----- ...tegrations.md => 3.editor-integrations.md} | 29 +++++++++-------- docs/{syntax/print.md => 4.syntax/1.print.md} | 20 +++++------- .../10.import-export.md} | 4 --- .../11.javascript.md} | 4 --- docs/{syntax/pipes.md => 4.syntax/2.pipes.md} | 4 --- docs/{syntax/set.md => 4.syntax/3.set.md} | 4 --- docs/{syntax/for.md => 4.syntax/4.for.md} | 4 --- docs/{syntax/if.md => 4.syntax/5.if.md} | 4 --- .../include.md => 4.syntax/6.include.md} | 4 --- .../layout.md => 4.syntax/7.layout.md} | 6 +--- .../comments.md => 4.syntax/8.comments.md} | 7 ++--- .../function.md => 4.syntax/9.function.md} | 3 -- docs/{syntax => 4.syntax}/index.md | 3 -- docs/{plugins => 5.plugins}/auto-trim.md | 31 ++++++++++--------- docs/{plugins => 5.plugins}/fragments.md | 4 +-- docs/5.plugins/index.md | 7 +++++ ...rations.md => 6.framework-integrations.md} | 10 +++--- docs/{formatter.md => 7.formatter.md} | 13 ++++---- docs/_data.yml | 2 +- docs/deno.json | 5 ++- docs/plugins/index.md | 11 ------- 23 files changed, 74 insertions(+), 130 deletions(-) rename docs/{getting-started.md => 1.getting-started.md} (91%) rename docs/{configuration.md => 2.configuration.md} (80%) rename docs/{editor-integrations.md => 3.editor-integrations.md} (64%) rename docs/{syntax/print.md => 4.syntax/1.print.md} (87%) rename docs/{syntax/import-export.md => 4.syntax/10.import-export.md} (99%) rename docs/{syntax/javascript.md => 4.syntax/11.javascript.md} (91%) rename docs/{syntax/pipes.md => 4.syntax/2.pipes.md} (99%) rename docs/{syntax/set.md => 4.syntax/3.set.md} (98%) rename docs/{syntax/for.md => 4.syntax/4.for.md} (99%) rename docs/{syntax/if.md => 4.syntax/5.if.md} (97%) rename docs/{syntax/include.md => 4.syntax/6.include.md} (97%) rename docs/{syntax/layout.md => 4.syntax/7.layout.md} (96%) rename docs/{syntax/comments.md => 4.syntax/8.comments.md} (85%) rename docs/{syntax/function.md => 4.syntax/9.function.md} (98%) rename docs/{syntax => 4.syntax}/index.md (96%) rename docs/{plugins => 5.plugins}/auto-trim.md (60%) rename docs/{plugins => 5.plugins}/fragments.md (90%) create mode 100644 docs/5.plugins/index.md rename docs/{framework-integrations.md => 6.framework-integrations.md} (52%) rename docs/{formatter.md => 7.formatter.md} (60%) delete mode 100644 docs/plugins/index.md diff --git a/docs/getting-started.md b/docs/1.getting-started.md similarity index 91% rename from docs/getting-started.md rename to docs/1.getting-started.md index f3a7740..6a186fb 100644 --- a/docs/getting-started.md +++ b/docs/1.getting-started.md @@ -1,7 +1,3 @@ ---- -order: 1 ---- - # Getting Started ## Install @@ -69,8 +65,8 @@ console.log(result.content); ### Clearing cache -Vento implements a cache to prevent excessive compilation. If you need to -reload your templates at runtime (ie. for development), you can clear the cache. +Vento implements a cache to prevent excessive compilation. If you need to reload +your templates at runtime (ie. for development), you can clear the cache. ```js env.cache.clear(); diff --git a/docs/configuration.md b/docs/2.configuration.md similarity index 80% rename from docs/configuration.md rename to docs/2.configuration.md index 7dbf8dd..1881222 100644 --- a/docs/configuration.md +++ b/docs/2.configuration.md @@ -1,7 +1,3 @@ ---- -order: 2 ---- - # Configuration ## Options @@ -43,10 +39,13 @@ Now you can use the `global` variable: ### autoDataVarname -Vento can append automatically the `dataVarname` prefix (which by default is `.it`) to any variable that need it. For example, instead of -`{{ it.title }}` you can simply write `{{ title }}` and vento automatically convert it to `{{ it.title }}`. +Vento can append automatically the `dataVarname` prefix (which by default is +`.it`) to any variable that need it. For example, instead of `{{ it.title }}` +you can simply write `{{ title }}` and vento automatically convert it to +`{{ it.title }}`. -You can disable this behavior by setting the `autoDataVarname` option to `false`: +You can disable this behavior by setting the `autoDataVarname` option to +`false`: ```js const env = vento({ @@ -56,7 +55,9 @@ const env = vento({ > [!warning] > -> The `useWith` option is an alias for backward compatibility ([when `with` was used](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with)) but it will be removed in the future. +> The `useWith` option is an alias for backward compatibility +> ([when `with` was used](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/with)) +> but it will be removed in the future. ### autoescape diff --git a/docs/editor-integrations.md b/docs/3.editor-integrations.md similarity index 64% rename from docs/editor-integrations.md rename to docs/3.editor-integrations.md index ec5525d..e0d2d15 100644 --- a/docs/editor-integrations.md +++ b/docs/3.editor-integrations.md @@ -1,7 +1,3 @@ ---- -order: 3 ---- - # Editor Integrations ## Visual Studio Code @@ -10,7 +6,8 @@ The [Vento for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=oscarotero.vento-syntax) extension enables syntax highlighting and provides some useful snippets. -[**Quick Install**](vscode:extension/oscarotero.vento-syntax){.button .is-secondary} +[**Quick Install**](vscode:extension/oscarotero.vento-syntax){.button +.is-secondary} ### Open VSX Registry @@ -18,21 +15,24 @@ extension enables syntax highlighting and provides some useful snippets. ## Neovim -Vento syntax highlighting is available for Neovim through [nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter). +Vento syntax highlighting is available for Neovim through +[nvim-treesitter](https://github.com/nvim-treesitter/nvim-treesitter). To use it, add the "vento" filetype ```js vim.filetype.add({ - extension = { - vto = "vento", - } -}) + extension: { + vto: "vento", + }, +}); ``` -And install the "vento" parser with `TSInstall`, or add it to the `ensure_installed` list in the `setup` function. +And install the "vento" parser with `TSInstall`, or add it to the +`ensure_installed` list in the `setup` function. -It's also recommended to install "javascript" and "html" parsers to get better syntax highlighting inside vento files. +It's also recommended to install "javascript" and "html" parsers to get better +syntax highlighting inside vento files. ```js require("nvim-treesitter.configs").setup({ @@ -42,7 +42,6 @@ require("nvim-treesitter.configs").setup({ ## Zed -The -[Vento extension for Zed](https://github.com/dz4k/zed-vento) -provides syntax highlighting. It can be installed from the Zed +The [Vento extension for Zed](https://github.com/dz4k/zed-vento) provides syntax +highlighting. It can be installed from the Zed [extensions gallery](https://zed.dev/docs/extensions/installing-extensions). diff --git a/docs/syntax/print.md b/docs/4.syntax/1.print.md similarity index 87% rename from docs/syntax/print.md rename to docs/4.syntax/1.print.md index 85fb16b..e52dad2 100644 --- a/docs/syntax/print.md +++ b/docs/4.syntax/1.print.md @@ -1,7 +1,3 @@ ---- -order: 1 ---- - # Printing variables Put a variable or expression between `{{ }}` to output the result. @@ -33,11 +29,11 @@ Or an async operation (using `await`): ## Autoescaping -> [!important] -> Autoescaping is **disabled by default**. [See configuration](../configuration.md#autoescape) to learn how to enable it. +> [!important] Autoescaping is **disabled by default**. +> [See configuration](../configuration.md#autoescape) to learn how to enable it. -If autoescaping is enabled any HTML -content will be escaped automatically. For example: +If autoescaping is enabled any HTML content will be escaped automatically. For +example: ```vento {{ "

Hello, world!

" }} @@ -55,7 +51,6 @@ To mark this variable as trust, use the `safe` filter: {{ "

Hello, world!

" |> safe }} ``` - ## Trimming the previous/next content Use the `-` character next to the opening tag or previous to the closing tag to @@ -73,7 +68,8 @@ the white space before the printing tag: The result is: ```html -

Hello, world! +

+ Hello, world!

``` @@ -92,8 +88,8 @@ The result is:

Hello, world!

``` -> [!tip] -> The [plugin autoTrim](../plugins/auto-trim.md) can trim automatically some tags. +> [!tip] The [plugin autoTrim](../plugins/auto-trim.md) can trim automatically +> some tags. ## Pipes diff --git a/docs/syntax/import-export.md b/docs/4.syntax/10.import-export.md similarity index 99% rename from docs/syntax/import-export.md rename to docs/4.syntax/10.import-export.md index 997b22a..8ab896e 100644 --- a/docs/syntax/import-export.md +++ b/docs/4.syntax/10.import-export.md @@ -1,7 +1,3 @@ ---- -order: 9 ---- - # Imports and exports Vento templates not only render content but also can export other things like diff --git a/docs/syntax/javascript.md b/docs/4.syntax/11.javascript.md similarity index 91% rename from docs/syntax/javascript.md rename to docs/4.syntax/11.javascript.md index 6e1b4e6..438004e 100644 --- a/docs/syntax/javascript.md +++ b/docs/4.syntax/11.javascript.md @@ -1,7 +1,3 @@ ---- -order: 10 ---- - # JavaScript code You can insert any JavaScript code in the templates between the tags diff --git a/docs/syntax/pipes.md b/docs/4.syntax/2.pipes.md similarity index 99% rename from docs/syntax/pipes.md rename to docs/4.syntax/2.pipes.md index ceac064..009796d 100644 --- a/docs/syntax/pipes.md +++ b/docs/4.syntax/2.pipes.md @@ -1,7 +1,3 @@ ---- -order: 1.4 ---- - # Pipes Pipes are the way to chain functions to transform a value. Vento uses the diff --git a/docs/syntax/set.md b/docs/4.syntax/3.set.md similarity index 98% rename from docs/syntax/set.md rename to docs/4.syntax/3.set.md index e3235f8..b67a7b4 100644 --- a/docs/syntax/set.md +++ b/docs/4.syntax/3.set.md @@ -1,7 +1,3 @@ ---- -order: 1.5 ---- - # Set The `{{ set [name] = [value] }}` tag allows to create or modify a global diff --git a/docs/syntax/for.md b/docs/4.syntax/4.for.md similarity index 99% rename from docs/syntax/for.md rename to docs/4.syntax/4.for.md index 6480e5c..a08b50f 100644 --- a/docs/syntax/for.md +++ b/docs/4.syntax/4.for.md @@ -1,7 +1,3 @@ ---- -order: 3 ---- - # For Use `{{ for [value] of [collection] }}` tag to iterate over arrays, diff --git a/docs/syntax/if.md b/docs/4.syntax/5.if.md similarity index 97% rename from docs/syntax/if.md rename to docs/4.syntax/5.if.md index 20c4591..5cb29c7 100644 --- a/docs/syntax/if.md +++ b/docs/4.syntax/5.if.md @@ -1,7 +1,3 @@ ---- -order: 2 ---- - # If Use `{{ if [expression] }}` to test a condition. Any code you want to test will diff --git a/docs/syntax/include.md b/docs/4.syntax/6.include.md similarity index 97% rename from docs/syntax/include.md rename to docs/4.syntax/6.include.md index 153051b..e26a21a 100644 --- a/docs/syntax/include.md +++ b/docs/4.syntax/6.include.md @@ -1,7 +1,3 @@ ---- -order: 4 ---- - # Include Use `{{ include [filename] }}` to insert other templates in place. Vento will diff --git a/docs/syntax/layout.md b/docs/4.syntax/7.layout.md similarity index 96% rename from docs/syntax/layout.md rename to docs/4.syntax/7.layout.md index f22de9d..cf83b4f 100644 --- a/docs/syntax/layout.md +++ b/docs/4.syntax/7.layout.md @@ -1,7 +1,3 @@ ---- -order: 5 ---- - # Layout The `{{ layout }}` tag allows to capture some content in a template and render @@ -68,6 +64,6 @@ This code outputs: ```html
-

HELLO, WORLD!

+

HELLO, WORLD!

``` diff --git a/docs/syntax/comments.md b/docs/4.syntax/8.comments.md similarity index 85% rename from docs/syntax/comments.md rename to docs/4.syntax/8.comments.md index c638e09..1b18eea 100644 --- a/docs/syntax/comments.md +++ b/docs/4.syntax/8.comments.md @@ -1,7 +1,3 @@ ---- -order: 8 ---- - # Comments Use `{{#` to start a comment and `#}}` to end it. The commented code will be @@ -13,7 +9,8 @@ ignored by Vento. ## Trimming spaces -Like other tags, it's possible to trim the space after and/or before a comment using the `-` character. +Like other tags, it's possible to trim the space after and/or before a comment +using the `-` character. ```vento

diff --git a/docs/syntax/function.md b/docs/4.syntax/9.function.md similarity index 98% rename from docs/syntax/function.md rename to docs/4.syntax/9.function.md index 911b633..7dd9247 100644 --- a/docs/syntax/function.md +++ b/docs/4.syntax/9.function.md @@ -1,6 +1,3 @@ ---- -order: 8 ---- # Function Functions are similar to JavaScript functions and allow you to define reusable diff --git a/docs/syntax/index.md b/docs/4.syntax/index.md similarity index 96% rename from docs/syntax/index.md rename to docs/4.syntax/index.md index 5fe60c9..f589541 100644 --- a/docs/syntax/index.md +++ b/docs/4.syntax/index.md @@ -1,6 +1,3 @@ ---- -order: 10 ---- # Syntax The API of Vento is designed to be very simple but flexible. diff --git a/docs/plugins/auto-trim.md b/docs/5.plugins/auto-trim.md similarity index 60% rename from docs/plugins/auto-trim.md rename to docs/5.plugins/auto-trim.md index 62b4fc8..4590dcf 100644 --- a/docs/plugins/auto-trim.md +++ b/docs/5.plugins/auto-trim.md @@ -1,12 +1,12 @@ # Auto Trim -By default, Vento doesn't automatically try to trim the whitespace from around tags. Using the -`autoTrim` plugin, you can enable this behavior. +By default, Vento doesn't automatically try to trim the whitespace from around +tags. Using the `autoTrim` plugin, you can enable this behavior. ## Usage -`autoTrim` comes included with Vento, so you don't need to install any additional packages. -Simply import it and use it in your instance. +`autoTrim` comes included with Vento, so you don't need to install any +additional packages. Simply import it and use it in your instance. ```js import autoTrim from "vento/plugins/auto_trim.ts"; @@ -15,22 +15,24 @@ import autoTrim from "vento/plugins/auto_trim.ts"; env.use(autoTrim()); ``` -By default, the tags that are trimmed are: -`set`, `if`, `else`, `for`, `function`, `async`, `export`, `import`, comments and JavaScript. +By default, the tags that are trimmed are: `set`, `if`, `else`, `for`, +`function`, `async`, `export`, `import`, comments and JavaScript. -If you want to add or remove tags from the list, you can pass an array of tags to the plugin. +If you want to add or remove tags from the list, you can pass an array of tags +to the plugin. ```js import autoTrim, { defaultTags } from "vento/plugins/auto_trim.ts"; // import autoTrim, { defaultTags } from "ventojs/plugins/auto_trim.js"; env.use(autoTrim({ - tags: ["tag", ...defaultTags] + tags: ["tag", ...defaultTags], })); ``` -If enabled, any of the listed tags will be trimmed away, as if it didn't exist in the markup. -It respects newlines, so it only snips out the tag, while preserving your markup. +If enabled, any of the listed tags will be trimmed away, as if it didn't exist +in the markup. It respects newlines, so it only snips out the tag, while +preserving your markup. For example, @@ -42,14 +44,13 @@ For example, ``` Will be rendered as: + ``` - Hello, Name! +Hello, Name! ``` Instead of the following: -``` - - Hello, Name! - ``` +Hello, Name! +``` diff --git a/docs/plugins/fragments.md b/docs/5.plugins/fragments.md similarity index 90% rename from docs/plugins/fragments.md rename to docs/5.plugins/fragments.md index 278ee9d..3af57b5 100644 --- a/docs/plugins/fragments.md +++ b/docs/5.plugins/fragments.md @@ -1,7 +1,7 @@ # Fragments -> [!warning] -> This is a third-party plugin. [Source code](https://github.com/wrapperup/vento-plugin-fragments). +> [!warning] This is a third-party plugin. +> [Source code](https://github.com/wrapperup/vento-plugin-fragments). Adds support for [template fragments](https://htmx.org/essays/template-fragments), which allows diff --git a/docs/5.plugins/index.md b/docs/5.plugins/index.md new file mode 100644 index 0000000..7b653bd --- /dev/null +++ b/docs/5.plugins/index.md @@ -0,0 +1,7 @@ +# Plugins + +Vento features a powerful plugin system that allows you to extend the engine +with new features. + +Nearly all of Vento's core features are implemented as plugins, so you can +easily add, remove or modify them to fit your needs. diff --git a/docs/framework-integrations.md b/docs/6.framework-integrations.md similarity index 52% rename from docs/framework-integrations.md rename to docs/6.framework-integrations.md index 32ab79a..8db56bd 100644 --- a/docs/framework-integrations.md +++ b/docs/6.framework-integrations.md @@ -1,15 +1,13 @@ ---- -order: 3 ---- - # Framework integrations Vento can be used with the following frameworks: - Lume: [supported by default](https://lume.land/plugins/vento/) -- Eleventy: [eleventy-plugin-vento](https://www.npmjs.com/package/eleventy-plugin-vento). +- Eleventy: + [eleventy-plugin-vento](https://www.npmjs.com/package/eleventy-plugin-vento). - Express: [express-vento](https://www.npmjs.com/package/express-vento) --- -Did you create an integration? [Open a PR](https://github.com/ventojs/vento/issues/new). \ No newline at end of file +Did you create an integration? +[Open a PR](https://github.com/ventojs/vento/issues/new). diff --git a/docs/formatter.md b/docs/7.formatter.md similarity index 60% rename from docs/formatter.md rename to docs/7.formatter.md index b2cb16c..eeda8c1 100644 --- a/docs/formatter.md +++ b/docs/7.formatter.md @@ -1,14 +1,13 @@ ---- -order: 4 ---- - # Formatter ## markup_fmt with dprint -[markup_fmt](https://github.com/g-plane/markup_fmt) can format Vento templates. This can be used in dprint as a plugin. -You can also install other dprint plugins that can format JavaScript code, so the expressions in templates can get formatted. -It can also format the code inside `