-
-
-
diff --git a/src/.vuepress/private-components/utils.js b/src/.vuepress/private-components/utils.js
deleted file mode 100644
index 937992b3..00000000
--- a/src/.vuepress/private-components/utils.js
+++ /dev/null
@@ -1,4 +0,0 @@
-export function deindent(string, ...values) {
- const result = String.raw(string, ...values);
- return result.replace(/^\s*/gm, "");
-}
diff --git a/src/.vuepress/public/icons/android-chrome-192x192.png b/src/.vuepress/public/icons/android-chrome-192x192.png
deleted file mode 100644
index 11f4200c..00000000
Binary files a/src/.vuepress/public/icons/android-chrome-192x192.png and /dev/null differ
diff --git a/src/.vuepress/public/icons/android-chrome-512x512.png b/src/.vuepress/public/icons/android-chrome-512x512.png
deleted file mode 100644
index 6257c2ba..00000000
Binary files a/src/.vuepress/public/icons/android-chrome-512x512.png and /dev/null differ
diff --git a/src/.vuepress/public/icons/handlebarsjs-icon.svg b/src/.vuepress/public/icons/handlebarsjs-icon.svg
deleted file mode 100644
index 789bcd6d..00000000
--- a/src/.vuepress/public/icons/handlebarsjs-icon.svg
+++ /dev/null
@@ -1,143 +0,0 @@
-
-
diff --git a/src/.vuepress/public/images/handlebars-devswag.png b/src/.vuepress/public/images/handlebars-devswag.png
deleted file mode 100644
index 770fee5e..00000000
Binary files a/src/.vuepress/public/images/handlebars-devswag.png and /dev/null differ
diff --git a/src/.vuepress/public/manifest.json b/src/.vuepress/public/manifest.json
deleted file mode 100644
index 06e8ba3c..00000000
--- a/src/.vuepress/public/manifest.json
+++ /dev/null
@@ -1,20 +0,0 @@
-{
- "name": "Handlebars.js",
- "short_name": "Handlebars",
- "icons": [
- {
- "src": "/icons/android-chrome-192x192.png",
- "sizes": "192x192",
- "type": "image/png"
- },
- {
- "src": "/icons/android-chrome-512x512.png",
- "sizes": "512x512",
- "type": "image/png"
- }
- ],
- "start_url": "/docs/index.html",
- "display": "standalone",
- "background_color": "#f0772b",
- "theme_color": "#000000"
-}
diff --git a/src/.vuepress/styles/include/highlighting.styl b/src/.vuepress/styles/include/highlighting.styl
deleted file mode 100644
index 494be095..00000000
--- a/src/.vuepress/styles/include/highlighting.styl
+++ /dev/null
@@ -1,9 +0,0 @@
-@import "~highlight.js/styles/darcula.css";
-
-div[class~="language-handlebars"]:before {
- content: "handlebars";
-}
-
-div[class~="language-hbs"]:before {
- content: "handlebars";
-}
diff --git a/src/.vuepress/styles/index.styl b/src/.vuepress/styles/index.styl
deleted file mode 100644
index 016d8d95..00000000
--- a/src/.vuepress/styles/index.styl
+++ /dev/null
@@ -1,154 +0,0 @@
-// see https://github.com/vuejs/vuepress/tree/master/packages/%40vuepress/theme-default/styles for default styles
-// abd https://github.com/vuejs/vuepress/blob/master/packages/@vuepress/core/lib/client/style/config.styl for default
-// variable definitions
-
-@import './include/highlighting.styl'
-
-html, body {
- background-color: $bodyBgColor !important;
-}
-
-.navbar, .navbar .links {
- background-color: $navbarBgColor !important
-}
-
-.sidebar {
- background-color $sidebarBgColor !important
-}
-
-.page-edit .edit-link a {
- color: $accentColor !important
-}
-
-.icon.outbound {
- color: $iconOutboundColor !important
-}
-
-.page-edit .last-updated .prefix {
- color: $textColor !important
-}
-
-.page-edit .last-updated .time {
- color: $textColor !important
-}
-
-$contentBoxPadding = 1.2rem
-$contentBorderRadius = 0.5rem
-
-
-
-.home {
- #main-title {
- display: none
- }
-
- .features {
- background-color: $featuresBgColor
- padding: $contentBoxPadding !important
- border-radius: $contentBorderRadius
- margin-bottom: 2rem
- }
-
- .hero img {
- max-height: 200px !important;
- }
-
- .hero .description {
- color: $accentColor !important
- }
-
- .feature p {
- color: $accentColor !important
- }
-
- .theme-default-content {
-
- background-color: transparent !important;
- text-align: center;
-
- .devswag {
- @media (min-width: $MQMobile + 1px) {
- position: absolute;
- left: 0;
- top: $navbarHeight;
- margin: 1rem;
- }
- }
-
- .playground a {
- display: inline-block;
- width: 100%;
- max-width: 400px;
- background-color: $featuresBgColor;
- border: 1px solid $borderColor;
- border-radius: 4px;
- padding: .8rem 0;
- }
- }
-
- .footer {
- border: none !important
- }
-}
-
-.theme-default-content {
- background-color: $contentBgColor;
- padding: $contentBoxPadding;
- border-radius: $contentBorderRadius;
-
- .theme-container.interactive-playground & {
- display: none;
- }
-}
-
-
-.table-of-contents {
- border: 1px solid $textColor;
- float: right;
- padding: 0.5em;
- margin-left: 1rem;
- max-width: 50%;
-
- @media (max-width: $MQMobile) {
- float: none;
- margin-left: 0;
- max-width: 100%;
- }
-
- &:before {
- content: "Table of contents";
- font-weight: bold;
- }
-
- > ul {
- list-style-type: decimal;
- margin: 0.5rem 0 0 0;
- }
-}
-
-h1, h2, h3, h4, h5, h6 {
- // Makes the header end before a float-right div
- display: flex;
-}
-
-$buttonLinkBgColor = darken($baseColor, 10%);
-$buttonLinkColor = white;
-
-.button-link,.custom-block.warning a.button-link {
- display: inline;
- border: $borderColor;
- background-color: $buttonLinkBgColor;
- padding: 0.5rem;
- color: $buttonLinkColor;
- border-radius: 3px;
- text-shadow: 1px 1px 2px black;
-
- &:hover {
- box-shadow: 1px 1px 2px black;
- }
-
- &:active:hover {
- box-shadow: none;
- }
-}
-
diff --git a/src/.vuepress/styles/palette.styl b/src/.vuepress/styles/palette.styl
deleted file mode 100644
index 403b4b6b..00000000
--- a/src/.vuepress/styles/palette.styl
+++ /dev/null
@@ -1,28 +0,0 @@
-$baseColor = #f0772b
-
-$accentColor = darken($baseColor, 50%)
-$textColor = darken($baseColor, 80%)
-$borderColor = darken($baseColor, 10%)
-
-$codeBgColor = #000
-
-$iconOutboundColor = #222
-
-$navbarBgColor = #fda
-$sidebarBgColor = $navbarBgColor
-
-$bodyBgColor = $baseColor
-$featuresBgColor = #eee
-$contentBgColor = #efefef
-
-$exampleWorkspaceDefaultMargin = 0.5rem;
-$exampleWorkspaceDefaultPadding = 0.5rem;
-
-
-$weHeaderMargin = 0.4rem;
-$weHeaderHeight = 0.8rem;
-$weHeaderColor = $baseColor;
-
-$weContentPadding = 0.5rem;
-$weContentPaddingTop = (2 * $weHeaderMargin + $weHeaderHeight + 0.5rem)
-$weContentBgColor = #111;
diff --git a/src/api-reference/compilation.md b/src/api-reference/compilation.md
index 6c2f6e35..46be4b61 100644
--- a/src/api-reference/compilation.md
+++ b/src/api-reference/compilation.md
@@ -13,13 +13,13 @@ Supports a variety of options that alter how the template executes.
::: v-pre
-- `data`: Set to false to disable `@data` tracking.
-- `compat`: Set to true to enable recursive field lookup.
+- `data`: Set to `false` to disable `@data` tracking.
+- `compat`: Set to `true` to enable recursive field lookup.
- `knownHelpers`: Hash containing list of helpers that are known to exist (truthy) at template execution time. Passing
this allows the compiler to optimize a number of cases. Builtin helpers are automatically included in this list and
may be omitted by setting that value to `false`.
-- `knownHelpersOnly`: Set to true to allow further optimizations based on the known helpers list.
-- `noEscape`: Set to true to not HTML escape any content.
+- `knownHelpersOnly`: Set to `true` to allow further optimizations based on the known helpers list.
+- `noEscape`: Set to `true` to not HTML escape any content.
- `strict`: Run in strict mode. In this mode, templates will throw rather than silently ignore missing fields. This has
the side effect of disabling inverse operations such as `{{^foo}}{{/foo}}` unless fields are explicitly included in
the source object.
diff --git a/src/api-reference/helpers.md b/src/api-reference/helpers.md
index ec3f498c..26021218 100644
--- a/src/api-reference/helpers.md
+++ b/src/api-reference/helpers.md
@@ -8,6 +8,6 @@ parameter.
- `lookupProperty(object, propertyName)`: a function that returns an "own property" of an object. Whitelists specified
in `allowedProtoProperties` and `allowedProtoMethods` are respected by this function. Example:
-
+
- TODO: Describe all options that are passed to helpers
diff --git a/src/api-reference/index.md b/src/api-reference/index.md
index 2093f9a2..7fb2619e 100644
--- a/src/api-reference/index.md
+++ b/src/api-reference/index.md
@@ -1,8 +1,10 @@
# Index
+
- [(Pre-)Compilation](compilation.md)
- [Runtime](runtime.md)
diff --git a/src/api-reference/runtime-options.md b/src/api-reference/runtime-options.md
index 4348633e..5b697771 100644
--- a/src/api-reference/runtime-options.md
+++ b/src/api-reference/runtime-options.md
@@ -16,7 +16,8 @@ The function 'Handlebars.compile' and 'Handlebars.precompile' create a function.
execution.
- `allowCallsToHelperMissing` (since 4.3.0, insecure): If set to `true`, calls like `{{helperMissing}}` and
`{{blockHelperMissing}}` will be allowed. Please note that this allows template authors to fabricate templates for
- Remote Code Execution on the environment running Handlebars (see https://github.com/handlebars-lang/handlebars.js/issues/1558)
+ Remote Code Execution on the environment running Handlebars (see
+ https://github.com/handlebars-lang/handlebars.js/issues/1558)
:::
@@ -75,9 +76,9 @@ of [Mahmoud Gamal](http://mahmoudsec.blogspot.com/2019/04/handlebars-template-in
{ aString: " abc " },
{
allowedProtoMethods: {
- trim: true
- }
- }
+ trim: true,
+ },
+ },
);
// result = 'abc'
```
diff --git a/src/api-reference/runtime.md b/src/api-reference/runtime.md
index 13092846..0bcd9f23 100644
--- a/src/api-reference/runtime.md
+++ b/src/api-reference/runtime.md
@@ -31,13 +31,13 @@ Handlebars.unregisterPartial("foo");
Registers helpers accessible by any template in the environment.
```js
-Handlebars.registerHelper("foo", function() {});
+Handlebars.registerHelper("foo", function () {});
```
Also supports registering multiple helpers at once.
```js
-Handlebars.registerHelper({ foo: function() {}, bar: function() {} });
+Handlebars.registerHelper({ foo: function () {}, bar: function () {} });
```
## `Handlebars.unregisterHelper(name)`
@@ -60,13 +60,13 @@ the internal API which is difficult to port to other languages and makes to code
Registers a decorator accessible by any template in the environment.
```js
-Handlebars.registerDecorator("foo", function() {});
+Handlebars.registerDecorator("foo", function () {});
```
Also supports registering multiple decorators at once.
```js
-Handlebars.registerDecorator({ foo: function() {}, bar: function() {} });
+Handlebars.registerDecorator({ foo: function () {}, bar: function () {} });
```
## `Handlebars.unregisterDecorator(name)`
diff --git a/src/api-reference/utilities.md b/src/api-reference/utilities.md
index 3127add9..17c39ad0 100644
--- a/src/api-reference/utilities.md
+++ b/src/api-reference/utilities.md
@@ -1,7 +1,3 @@
----
-sidebarDepth: 2
----
-
# Utility functions
## Helper utilities
diff --git a/src/contributing/button-links.md b/src/contributing/button-links.md
deleted file mode 100644
index d1a351f8..00000000
--- a/src/contributing/button-links.md
+++ /dev/null
@@ -1,11 +0,0 @@
-# Button links
-
-In order to make a link look like a button, use the syntax
-
-```markdown
-!button[Link Text](./link-target.html)
-```
-
-This will render the following HTML:
-
-!button[Link Text](./link-target.html)
diff --git a/src/contributing/index.md b/src/contributing/index.md
index 78191a61..b606de3b 100644
--- a/src/contributing/index.md
+++ b/src/contributing/index.md
@@ -1,25 +1,28 @@
# Improving the documentation
-[[toc]]
+
Handlebars is an open-source project. There is no _"documentation department"_ that keeps the docs up-to-date. This
documentation site requires your help to be a good and helpful site.
-[Release notes](https://github.com/handlebars-lang/handlebars.js/blob/master/release-notes.md)
-[Issues with label 'docs-needed'](https://github.com/handlebars-lang/handlebars.js/issues?q=is%3Aopen+is%3Aissue+label%3Adocs-needed)
-[The old Handlebars website](https://handlebars-archive.knappi.org)
+- [Release notes](https://github.com/handlebars-lang/handlebars.js/blob/master/release-notes.md)
+- [Issues with label 'docs-needed'](https://github.com/handlebars-lang/handlebars.js/issues?q=is%3Aopen+is%3Aissue+label%3Adocs-needed)
+- [The old Handlebars website](https://handlebars-archive.knappi.org)
The following sections should help you help us improve the documentation.
## How do I submit contributions?
This site is hosted on [Github](https://github.com/handlebars-lang/docs) and rendered with
-[VuePress](https://v1.vuepress.vuejs.org/)
+[VitePress](https://vitepress.dev/)
- Please create a [pull requests](https://help.github.com/en/articles/about-pull-requests) for any change that you would
like to see on the page.
-- If your change only affects the contents of a single page, you can simply click the link
- `{{$themeLocaleConfig.editLinkText}}` at the bottom of this page (see
+- If your change only affects the contents of a single page, you can simply click the link `{{theme.editLink.text}}` at
+ the bottom of this page (see
[Editing files in another user's repository](https://help.github.com/en/articles/editing-files-in-another-users-repository))
for details.
- For more complex changes (styling, multiple pages, new pages, fixing build problems), you should
@@ -29,19 +32,18 @@ This site is hosted on [Github](https://github.com/handlebars-lang/docs) and ren
## How do I write content?
-The documentation is written in Markdown and rendered with [VuePress](https://v1.vuepress.vuejs.org/). VuePress uses the
+The documentation is written in Markdown and rendered with [VitePress](https://vitepress.dev/). VitePress uses the
`markdown-it` package to render markdown. `markdown-it` implements the CommonMark dialect.
This means that you can use syntax described in these sources:
- [CommonMark help](https://commonmark.org/help/)
- [syntax extensions added by markdown-it](https://github.com/markdown-it/markdown-it#syntax-extensions)
-- [syntax extensions added by VuePress](https://v1.vuepress.vuejs.org/guide/markdown.html)
+- [syntax extensions added by VitePress](https://vitepress.dev/)
In addition to all those extensions, this site adds some custom Vue-components that can be embedded in source files.
- [Interactive Examples](interactive-examples.md)
-- [Button Links](button-links.md)
## How should I behave?
@@ -59,9 +61,9 @@ In addition to all those extensions, this site adds some custom Vue-components t
## What can I contribute?
- **Look for issues labeled as
- [docs-needed](https://github.com/handlebars-lang/handlebars.js/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Adocs-needed+) in the
- [handlebars.js](https://github.com/handlebars-lang/handlebars.js)-repository.** Those are issues that describe something that
- should be documented.
+ [docs-needed](https://github.com/handlebars-lang/handlebars.js/issues?utf8=%E2%9C%93&q=is%3Aissue+label%3Adocs-needed+)
+ in the [handlebars.js](https://github.com/handlebars-lang/handlebars.js)-repository.** Those are issues that describe
+ something that should be documented.
- **Propose and submit new content.** If you are unsure about your proposal, you can create an issue before submitting a
pull-request. This might save you from wasting time.
- **Improve existing content.** You can propose changes to the navigation, fix typos, improve language and correct wrong
diff --git a/src/contributing/interactive-examples.md b/src/contributing/interactive-examples.md
index 0df68e18..c15dd4a3 100644
--- a/src/contributing/interactive-examples.md
+++ b/src/contributing/interactive-examples.md
@@ -1,7 +1,5 @@
# Creating interactive examples
-[[toc]]
-
It is possible to define interactive examples. Examples or parts of an example can be **embedded in any page**. A
auto-generated link enables the visitor to open the example in a **playground** where she can change the template,
partials, input, and so on and can see the resulting output.
@@ -31,7 +29,7 @@ The output of the example is automatically computed using the latest release ver
## Example data
If possible, examples should use variations of a common data set. Therefore, the file
-[src/examples/\_example-base-data.yaml](https://github.com/handlebars-lang/docs/blob/master/src/examples/_example-base-data.yaml)
+[src/\_examples/\_example-base-data.yaml](https://github.com/handlebars-lang/docs/blob/master/src/_examples/_example-base-data.yaml)
contains data that can be reused and adapted to each example. If the data in that file is insufficient, please add new
data, but please make sure it is somehow related.
@@ -40,12 +38,12 @@ data, but please make sure it is somehow related.
The ``-component allows you to show a part of the example in the current part.
```md
-
+
```
will result in
-
+
The props for this component are:
@@ -56,22 +54,22 @@ The props for this component are:
inserted into the example.
The component is very useful if you want to embed the parts of an example into flowing text, You can insert the input
-JSON by using `` and the following code snippet will
-appear in the page:
+JSON by using `` and the following code snippet will appear
+in the page:
-
+
Then, in order to show the reader the template you can use `show="template"` with the same `examplePage`.
-
+
You can render a partial using for example `show=partial` and `name=person`
-
+
If you have an example with helpers, you might also want to include the preparation script:
-
+
## Horizontal layout
@@ -79,14 +77,14 @@ If you want to layout two example-parts horizontally, you can use the ``-c
```md
-
-
+
+
```
becomes
-
-
+
+
diff --git a/src/examples.data.js b/src/examples.data.js
new file mode 100644
index 00000000..17ecd899
--- /dev/null
+++ b/src/examples.data.js
@@ -0,0 +1,3 @@
+import { createContentLoader } from "vitepress";
+
+export default createContentLoader("examples/**/*.md" /* options */);
diff --git a/src/examples/all-features.md b/src/examples/all-features.md
index 3cf00164..b551a9fe 100644
--- a/src/examples/all-features.md
+++ b/src/examples/all-features.md
@@ -1,5 +1,5 @@
---
-layout: InteractivePlaygroundLayout
+layout: playground
example:
template: |
{{>header}}
diff --git a/src/examples/builtin-helper-each-block.md b/src/examples/builtin-helper-each-block.md
index db3b8760..10f97fe5 100644
--- a/src/examples/builtin-helper-each-block.md
+++ b/src/examples/builtin-helper-each-block.md
@@ -1,5 +1,5 @@
---
-layout: InteractivePlaygroundLayout
+layout: playground
example:
template: |-
diff --git a/src/guide/block-helpers.md b/src/guide/block-helpers.md
index f075caa0..0fa6f00b 100644
--- a/src/guide/block-helpers.md
+++ b/src/guide/block-helpers.md
@@ -21,7 +21,7 @@ The `noop` helper (short for "no operation") will receive an options hash. This
and return a String.
```js
-Handlebars.registerHelper("noop", function(options) {
+Handlebars.registerHelper("noop", function (options) {
return options.fn(this);
});
```
@@ -54,7 +54,7 @@ The bold helper will add markup to make its text bold. As before, the function w
String.
```js
-Handlebars.registerHelper("bold", function(options) {
+Handlebars.registerHelper("bold", function (options) {
return new Handlebars.SafeString('
' + options.fn(this) + "
");
});
```
@@ -96,7 +96,7 @@ parameters are evaluated just like expressions used directly inside `{{mustache}
:::
```js
-Handlebars.registerHelper("with", function(context, options) {
+Handlebars.registerHelper("with", function (context, options) {
return options.fn(context);
});
```
@@ -129,7 +129,7 @@ are defined as regular Handlebars block helpers. Let's take a look at how the bu
In this case, we want to invoke the block passed to `each` once for each element in the comments Array.
```js
-Handlebars.registerHelper("each", function(context, options) {
+Handlebars.registerHelper("each", function (context, options) {
var ret = "";
for (var i = 0, j = context.length; i < j; i++) {
@@ -158,7 +158,7 @@ You would evaluate this template using something like this as the context:
{
nav: [
{ url: "http://www.yehudakatz.com", title: "Katz Got Your Tongue" },
- { url: "http://www.sproutcore.com/block", title: "SproutCore Blog" }
+ { url: "http://www.sproutcore.com/block", title: "SproutCore Blog" },
];
}
```
@@ -166,7 +166,7 @@ You would evaluate this template using something like this as the context:
The helper is similar to the original `each` helper.
```js
-Handlebars.registerHelper("list", function(context, options) {
+Handlebars.registerHelper("list", function (context, options) {
var ret = "
";
for (var i = 0, j = context.length; i < j; i++) {
@@ -181,11 +181,11 @@ Using a library like underscore.js or SproutCore's runtime library could make th
what it might look like using SproutCore's runtime library:
```js
-Handlebars.registerHelper("list", function(context, options) {
+Handlebars.registerHelper("list", function (context, options) {
return (
"
";
})
.join("\n") +
@@ -201,7 +201,7 @@ built-in `if` and `unless` control structures are implemented as regular Handleb
```handlebars
{{#if isActive}}
-
+
{{/if}}
```
@@ -209,7 +209,7 @@ Control structures typically do not change the current context, instead they dec
based upon some variable.
```js
-Handlebars.registerHelper("if", function(conditional, options) {
+Handlebars.registerHelper("if", function (conditional, options) {
if (conditional) {
return options.fn(this);
}
@@ -222,9 +222,9 @@ functionality to block helpers.
```handlebars
{{#if isActive}}
-
+
{{else}}
-
+
{{/if}}
```
@@ -232,7 +232,7 @@ Handlebars provides the block for the `else` fragment as `options.inverse`. You
of the else fragment: Handlebars will detect it automatically and register a "noop" function.
```js
-Handlebars.registerHelper("if", function(conditional, options) {
+Handlebars.registerHelper("if", function (conditional, options) {
if (conditional) {
return options.fn(this);
} else {
@@ -248,11 +248,10 @@ Conditionals may also be chained by including the subsequent helper call within
```handlebars
{{#if isActive}}
-
+
{{else if isInactive}}
-
+
{{/if}}
-
```
It is not necessary to use the same helper in subsequent calls, the unless helper could be used in the else portion as
@@ -274,9 +273,9 @@ while also accepting an optional Hash. If the template provides no hash argument
empty object (`{}`), so you don't need to check for the existence of hash arguments.
```js
-Handlebars.registerHelper("list", function(context, options) {
+Handlebars.registerHelper("list", function (context, options) {
var attrs = Object.keys(options.hash)
- .map(function(key) {
+ .map(function (key) {
return key + '="' + options.hash[key] + '"';
})
.join(" ");
@@ -286,7 +285,7 @@ Handlebars.registerHelper("list", function(context, options) {
attrs +
">" +
context
- .map(function(item) {
+ .map(function (item) {
return "
" + options.fn(item) + "
";
})
.join("\n") +
@@ -305,12 +304,13 @@ For example, when iterating over a list, you may provide the current index as a
```handlebars
{{#list array}}
- {{@index}}. {{title}}
+ {{@index}}.
+ {{title}}
{{/list}}
```
```js
-Handlebars.registerHelper("list", function(context, options) {
+Handlebars.registerHelper("list", function (context, options) {
var out = "
",
data;
@@ -348,7 +348,10 @@ New in Handlebars 3.0, it's possible to receive named parameters from supporting
```handlebars
{{#each users as |user userId|}}
- Id: {{userId}} Name: {{user.name}}
+ Id:
+ {{userId}}
+ Name:
+ {{user.name}}
{{/each}}
```
@@ -360,7 +363,10 @@ This allows for nested helpers to avoid name conflicts that can occur with priva
```handlebars
{{#each users as |user userId|}}
{{#each user.book as |book bookId|}}
- User Id: {{userId}} Book Id: {{bookId}}
+ User Id:
+ {{userId}}
+ Book Id:
+ {{bookId}}
{{/each}}
{{/each}}
```
@@ -377,18 +383,18 @@ is optional and any additional parameters passed to the template will be silentl
Raw blocks are available for templates needing to handle unprocessed mustache blocks.
-
+
```handlebars
-{{{{raw-helper}}}}
- {{bar}}
-{{{{/raw-helper}}}}
+{{#raw-helper}}
+ \{{bar}}
+{{/raw-helper}}
```
will execute the helper raw-helper without interpreting the content.
```js
-Handlebars.registerHelper("raw-helper", function(options) {
+Handlebars.registerHelper("raw-helper", function (options) {
return options.fn();
});
```
diff --git a/src/guide/builtin-helpers.md b/src/guide/builtin-helpers.md
index 13cd9fb3..4d2a00a0 100644
--- a/src/guide/builtin-helpers.md
+++ b/src/guide/builtin-helpers.md
@@ -5,15 +5,15 @@
You can use the `if` helper to conditionally render a block. If its argument returns `false`, `undefined`, `null`, `""`,
`0`, or `[]`, Handlebars will not render the block.
-
+
When you pass the following input to the above template
-
+
This will produce the result as below:
-
+
If the input is an empty JSONObject `{}`, then `author` will become `undefined` and `if` condition fails, resulting in
the output as follow:
@@ -25,16 +25,16 @@ the output as follow:
When using a block expression, you can specify a template section to run if the expression returns a falsy value. The
section, marked by `else` is called an "else section".
-
+
### includeZero
-The `includeZero=true` option may be set to treat the conditional as not empty.
-This effectively determines if `0` is handled by the positive or negative path.
+The `includeZero=true` option may be set to treat the conditional as not empty. This effectively determines if `0` is
+handled by the positive or negative path.
```handlebars
{{#if 0 includeZero=true}}
-
Does render
+
Does render
{{/if}}
```
@@ -47,18 +47,18 @@ returns false for empty collections (see [Utils.isEmpty](/api-reference/utilitie
You could write a helper that checks for "undefined" such as:
-
+
Then use your helper as a sub-expression:
-
+
## #unless
You can use the `unless` helper as the inverse of the `if` helper. Its block will be rendered if the expression returns
a falsy value.
-
+
If looking up `license` under the current context returns a falsy value, Handlebars will render the warning. Otherwise,
it will render nothing.
@@ -68,21 +68,21 @@ it will render nothing.
You can iterate over a list using the built-in `each` helper. Inside the block, you can use `this` to reference the
element being iterated over.
-
+
when used with this context:
-
+
will result in:
-
+
You can use the `this` expression in any context to reference the current context.
You can optionally provide an `else` section which will display only when the list is empty.
-
+
::: v-pre
@@ -114,20 +114,20 @@ Nested `each` blocks may access the iteration variables via depth based paths. T
The `with`-helper allows you to change the evaluation context of template-part.
-
+
when used with this context:
-
+
will result in:
-
+
`with` can also be used with block parameters to define known references in the current block. The example above can be
converted to
-
+
Which allows for complex templates to potentially provide clearer code than `../` depthed references allow for.
@@ -138,8 +138,8 @@ You can optionally provide an `{{else}}` section which will display only when th
:::
-
-
+
+
## lookup
@@ -148,24 +148,24 @@ The `lookup` helper allows for dynamic parameter resolution using Handlebars var
This is useful for resolving values for array indexes.
-
+
It can also be used to lookup properties of object based on data from the input. The following is a more complex example
that uses `lookup` in a sub-expression to change the evaluation context to another object based on a property-value.
-
+
## log
The `log` helper allows for logging of context state while executing a template.
-
+
It delegates to `Handlebars.logger.log` which may be overridden to perform custom logging.
Any number of arguments may be passed to this method and all will be forwarded to the logger.
-
+
The log level may be set using the level hash parameter. Supported values are debug, info, warn, and error. When
omitted, info is the default value,
@@ -173,4 +173,4 @@ omitted, info is the default value,
Logging is conditional based on the level and to value set in `Handlebars.logger.level`, which defaults to `info`. All
log statements at or above the current level will be output.
-
+
diff --git a/src/guide/expressions.md b/src/guide/expressions.md
index d827575a..eab2d32c 100644
--- a/src/guide/expressions.md
+++ b/src/guide/expressions.md
@@ -12,39 +12,39 @@ them to a Handlebars helper, or use them as values in hash arguments.
Handlebars expressions are some contents enclosed by double curly braces `{{}}`. In the below template, `firstname` is a
variable that is enclosed by double curly braces, which is said to be an expression.
-
+
If the below input object is applied to the template
-
+
Expressions are compiled to produce the output as follows:
-
+
## Path expressions
Handlebars expressions can also be dot-separated paths.
-
+
This expression looks up the `person` property in the input object and in turn looks up the `firstname` and `lastname`
property within the `person` object.
-Pass the below input object to the template
+Pass the below input object to the template
-Output will be generated as below
+Output will be generated as below
Handlebars also supports a deprecated `/` syntax, so you could write the above template as:
-
+
## Changing the context
Some helpers like `#with` and `#each` allow you to dive into nested objects. When you include `../` segments in your
path, Handlebars will change back into the parent context.
-
+
Even though the name is printed while in the context of a comment, it can still go back to the main context (the
root-object) to retrieve the prefix.
@@ -70,9 +70,9 @@ helpers such as `{{#if}}` do not.
In this example all of the above reference the same prefix value even though they are located within different blocks.
This behavior is new as of Handlebars 4; the
-[release notes](https://github.com/handlebars-lang/handlebars.js/blob/master/release-notes.md) discuss the prior behavior as well
-as the migration plan. Handlebars also allows for name conflict resolution between helpers and data fields via a this
-reference:
+[release notes](https://github.com/handlebars-lang/handlebars.js/blob/master/release-notes.md) discuss the prior
+behavior as well as the migration plan. Handlebars also allows for name conflict resolution between helpers and data
+fields via a `this` reference:
:::
@@ -90,7 +90,7 @@ closing `]` in a path-literal, but all other characters are allowed.
JavaScript-style strings, `"` and `'`, may also be used instead of `[` pairs.
-
+
## HTML-escaping
@@ -104,11 +104,11 @@ the returned HTML-escaped output is generated as `&`. If you don't want Hand
In the below template, you can learn how to produce the HTML escaped and raw output.
-
+
Pass the special characters to the template
-
+
::: v-pre
@@ -117,7 +117,7 @@ below.
:::
-
+
## Helpers
@@ -126,53 +126,57 @@ Helpers can be used to implement functionality that is not part of the Handlebar
A helper can be registered at runtime via `Handlebars.registerHelper`, for example in order to uppercase all characters
of a string.
-
+
A Handlebars helper call is a simple identifier, followed by zero or more parameters (separated by a space). Each
parameter is a Handlebars expression that is evaluated exactly the same way as described above in "Basic Usage":
-
+
In this case, `loud` is the name of a helper, and `lastname` is a parameter to the helper. The template will uppercase
the `lastname` property of the input:
-
-
+
+
### Prevent HTML-escaping of helper return values
+::: v-pre
+
When your helper returns an instance of `Handlebars.Safestring` the return-value is not escaped, even if the helper is
-called with `{{` instead of `{{{`. You have to take care that all parameters are escaped properly using
-`Handlebars.escapeExpression`.
+called with `{{` instead of `{{{`. You have to take care that all parameters are escaped properly
+using `Handlebars.escapeExpression`.
+
+:::
-
+
### Helpers with Multiple Parameters
Let us see another example of helpers with two parameters
-
+
In this case, Handlebars will pass the link helper two parameters: the String `See Website` and the value of
`people.url` from the below provided input `people` object.
-
+
The helper function `link` is used to generate a hyperlink as described in the script.
-
+
We will obtain the output using the input parameters
-
+
In the above example, You could use the exact same helper with dynamic text based on the value of `people.text`:
-
-
+
+
### Literal arguments
@@ -181,14 +185,14 @@ Helper calls may also have literal values passed to them either as parameter arg
literals include numbers, strings, `true`, `false`, `null` and `undefined`:
-
+
### Helpers with Hash arguments
Handlebars provides additional metadata, such as Hash arguments, to helpers as a final parameter.
-
+
In that template,the final parameter `href=people.url class="people"` are hash arguments sent to the helper.
@@ -197,21 +201,21 @@ values can be simple identifiers, paths, or Strings.
If we pass the below input to the template, the value of `person.url` can be obtained from the `person` object.
-
+
As described in the helper script below, the hash arguments can be obtained from the last parameter `options` for
further processing within the helper.
-
+
The output of above helper is generated as below
-
+
Handlebars also offers a mechanism for invoking a helper with a block of the template. Block helpers can then invoke
that block zero or more times with any context it chooses.
-!button[Learn More: Block Helpers](block-helpers.html)
+[Learn More: Block Helpers](block-helpers.html)
### Disambiguating helpers calls and property lookup
@@ -220,9 +224,9 @@ property. If you want to resolve the input property instead, you can prefix its
deprecated `this/`)
-
-
-
+
+
+
## Subexpressions
@@ -232,7 +236,7 @@ pass in the results of inner helper invocations as arguments to outer helpers. S
parentheses.
```handlebars
-{{outer-helper (inner-helper 'abc') 'def'}}
+{{outer-helper (inner-helper "abc") "def"}}
```
In this case, `inner-helper` will get invoked with the string argument `'abc'`, and whatever the `inner-helper` function
@@ -246,11 +250,11 @@ When applied all whitespace on that side will be removed up to the first handleb
character on that side.
```handlebars
-{{#each nav ~}}
+{{#each nav~}}
{{~#if test}}
{{~title}}
- {{~^~}}
+ {{~else~}}
Empty
{{~/if~}}
@@ -279,7 +283,7 @@ partial and whitespace).
{{#if test}}
{{title}}
- {{^}}
+ {{else}}
Empty
{{/if}}
@@ -289,12 +293,7 @@ partial and whitespace).
will render
```html
-
- bar
-
-
- Empty
-
+ bar Empty
```
## Escaping Handlebars expressions
@@ -308,9 +307,9 @@ prefixing a mustache block with `\`. Raw blocks are created using `{{{{` mustach
```handlebars
\{{escaped}}
-{{{{raw}}}}
- {{escaped}}
-{{{{/raw}}}}
+{{#raw}}
+ \{{escaped}}
+{{/raw}}
```
Raw blocks operate in the same manner as other [block helpers](block-helpers.html) with the distinction of the child
diff --git a/src/guide/hooks.md b/src/guide/hooks.md
index d9960cf8..7e0d9656 100644
--- a/src/guide/hooks.md
+++ b/src/guide/hooks.md
@@ -11,9 +11,9 @@ This hook is called when a mustache or a block-statement
you can add custom handling for those situations by registering the helper `helperMissing`:
-
-
-
+
+
+
The helper receives the same arguments and options (`hash`, `name` etc) as any custom helper or block-helper. The
`options.name` is the name of the helper being called.
@@ -24,15 +24,15 @@ If no parameters are passed to the mustache, the default behavior is to do nothi
expression or the whole block:
-
-
+
+
If parameter is passed to the mustache, Handlebars with throw an exception:
-
-
+
+
## blockHelperMissing
@@ -44,9 +44,9 @@ This hook is called, when a
You can handle this situation by registering a helper named `blockHelperMissing`.
-
-
-
+
+
+
### Default behavior
@@ -56,5 +56,5 @@ name of the property.
If the hook is not overridden, then the default implementation will mimic the behavior of Mustache and just call the
block.
-
-
+
+
diff --git a/src/guide/index.md b/src/guide/index.md
index d5244ccf..e504edbe 100644
--- a/src/guide/index.md
+++ b/src/guide/index.md
@@ -7,120 +7,120 @@ Handlebars is a simple **templating language**.
It uses a template and an input object to generate HTML or other text formats. Handlebars templates look like regular
text with embedded Handlebars expressions.
-
+
-A handlebars expression is a `{{`, some contents, followed by a `}}`. When the template is executed, these expressions
-are replaced with values from an input object.
+A handlebars expression is a `{{`, some contents, followed by a `}}`. When the template is executed,
+these expressions are replaced with values from an input object.
-!button[Learn More: Expressions](expressions.html)
+[Learn More: Expressions](expressions.md)
## Installation
The fastest way to test Handlebars is to load it from a _CDN_ and embed it in an HTML file.
-<<< @/src/usage-examples/compiler-and-runtime/simple-console-out.html
+<<< @/snippets/compiler-and-runtime/simple-console-out.html
::: warning
This method can be used for small pages and for testing. There are several other ways to use Handlebars, when you target
real production systems.
-!button[Learn more: Installation](../installation/index.md)
+[Learn more: Installation](installation/index.md)
:::
-# Language features
+## Language features
-## Simple expressions
+### Simple expressions
As shown before, the following template defines two Handlebars expressions
-
+
If applied to the input object
-
+
the expressions will be replaced by the corresponding properties. The result is then
-
+
-## Nested input objects
+### Nested input objects
Sometimes, the input objects contains other objects or arrays. For example:
-
+
In such a case, you can use a dot-notation to gain access to the nested properties
-
+
-!button[Learn more: Expressions](./expressions.md)
+[Learn more: Expressions](./expressions.md)
Some built-in helpers allow you to change the current context to a nested object. You can then access this object as if
it were the root object
-## Evaluation context
+### Evaluation context
The built-in block-helpers `each` and `with` allow you to change the current evaluation context.
The `with`-helper dives into an object-property, giving you access to its properties
-
-
+
+
The `each`-helper iterates an array, allowing you to access the properties of each object via simple handlebars
expressions.
-
-
+
+
-!button[Learn more: Built-in helpers](./builtin-helpers.md)
+[Learn more: Built-in helpers](./builtin-helpers.md)
-## Template comments
+### Template comments
::: v-pre
You can use comments in your handlebars code just as you would in your code. Since there is generally some level of
logic, this is a good practice.
-The comments will not be in the resulting output. If you'd like the comments to show up just use HTML comments, and
-they will be output.
+The comments will not be in the resulting output. If you'd like the comments to show up just use HTML comments, and they
+will be output.
Any comments that must contain `}}` or other handlebars tokens should use the `{{!-- --}}` syntax.
:::
-
+
-## Custom Helpers
+### Custom Helpers
Handlebars helpers can be accessed from any context in a template. You can register a helper with the
Handlebars.registerHelper method.
-
-
+
+
Helpers receive the current context as the `this`-context of the function.
-
-
+
+
-## Block Helpers
+### Block Helpers
Block expressions allow you to define helpers that will invoke a section of your template with a different context than
the current. These block helpers are identified by a `#` preceeding the helper name and require a matching closing
mustache, `/`, of the same name. Let's consider a helper that will generate an HTML list:
-
+
The example creates a helper named `list` to generate our HTML list. The helper receives the `people` as its first
parameter, and an `options` hash as its second parameter. The options hash contains a property named `fn`, which you can
@@ -128,7 +128,7 @@ invoke with a context just as you would invoke a normal Handlebars template.
When executed, the template will render:
-
+
Block helpers have more features, such as the ability to create an `else` section (used, for instance, by the built-in
`if` helper).
@@ -136,9 +136,9 @@ Block helpers have more features, such as the ability to create an `else` sectio
Since the contents of a block helper are escaped when you call `options.fn(context)`, Handlebars does not escape the
results of a block helper. If it did, inner content would be double-escaped!
-!button[Learn More: Block Helpers](block-helpers.html)
+[Learn More: Block Helpers](block-helpers.md)
-## HTML Escaping
+### HTML Escaping
::: v-pre
@@ -147,17 +147,17 @@ don't want Handlebars to escape a value, use the "triple-stash", `{{{`.
:::
-
+
The special characters in the second line will be escaped:
-
+
Handlebars will not escape a `Handlebars.SafeString`. If you write a helper that generates its own HTML, you will
usually want to return a `new Handlebars.SafeString(result)`. In such a circumstance, you will want to manually escape
parameters.
-
+
This will escape the passed in parameters, but mark the response as safe, so Handlebars will not try to escape it even
if the "triple-stash" is not used.
@@ -169,34 +169,34 @@ could potentially lead to cross-site scripting vulnerabilities.
:::
-## Partials
+### Partials
Handlebars partials allow for code reuse by creating shared templates. You can register a partial using the
`registerPartial`-method:
-
+
The following template and input:
-
-
+
+
will then provide the following result:
-
+
-!button[Learn More: Partials](partials.html)
+[Learn More: Partials](partials.md)
-## Built-In Helpers
+### Built-In Helpers
Handlebars offers a variety of built-in helpers such as the if conditional and each iterator.
-!button[Learn More: Built-In Helpers](builtin-helpers.html)
+[Learn More: Built-In Helpers](builtin-helpers.md)
-## API Reference
+### API Reference
Handlebars offers a variety of APIs and utility methods for applications and helpers.
-!button[Learn More: API Reference](/api-reference/)
+[Learn More: API Reference](./../api-reference/index.md)
diff --git a/src/installation/index.md b/src/guide/installation/index.md
similarity index 93%
rename from src/installation/index.md
rename to src/guide/installation/index.md
index 2c17d2a8..98df96e9 100644
--- a/src/installation/index.md
+++ b/src/guide/installation/index.md
@@ -1,5 +1,10 @@
# Installation
+
+
There are a variety of ways to install Handlebars, depending on the programming language and environment you are using.
## npm or yarn (recommended)
@@ -10,7 +15,9 @@ The reference implementation of Handlebars is written in JavaScript. It is most
```bash
npm install handlebars
```
+
or
+
```bash
yarn add handlebars
```
@@ -39,7 +46,7 @@ web-browser, we recommend that you use a build-engine such as Webpack, Browserif
The [integrations](integrations.md) page contains a list of plugins for those loaders that allow you to automatically
precompile templates or use Handlebars otherwise.
-!button[Learn more: Integrations](integrations.md)
+[Learn more: Integrations](integrations.md)
:::
@@ -56,7 +63,7 @@ always run against the same version of the runtime.
The following downloads are provided as a convenience to the community. They are not meant for production use, but they
can give you a quick-start without having to set up a build-engine.
-### Latest release (version {{$handlebarsVersions.latest}})
+### Latest release (version {{ handlebars.versions.latest }})
@@ -148,9 +155,7 @@ results in
```html
My New Post
-
- This is my first post!
-
+
This is my first post!
```
@@ -160,7 +165,7 @@ In the previous example, we have loaded the compiler-and-runtime version of Hand
compile your templates beforehand and include the precompiled version in your website. You can include the smaller
runtime and the browser does not have to compile the templates before running them.
-!button[Learn More: Precompilation](precompilation.html)
+[Learn More: Precompilation](precompilation.html)
## Bower (deprecated)
diff --git a/src/installation/integrations.md b/src/guide/installation/integrations.md
similarity index 100%
rename from src/installation/integrations.md
rename to src/guide/installation/integrations.md
diff --git a/src/installation/precompilation.md b/src/guide/installation/precompilation.md
similarity index 61%
rename from src/installation/precompilation.md
rename to src/guide/installation/precompilation.md
index f94770b3..3135be77 100644
--- a/src/installation/precompilation.md
+++ b/src/guide/installation/precompilation.md
@@ -1,5 +1,9 @@
# Precompiling templates
+
+
Using the Handlebars precompiler, you can precompile your Handlebars templates to save time on the client and reduce the
required runtime size of the handlebars library.
@@ -16,7 +20,7 @@ npm install -g handlebars
Create a file name `example.handlebars` containing your template:
-<<< @/src/usage-examples/precompilation/example.handlebars
+<<< @/snippets/precompilation/example.handlebars
Run the precompiler.
@@ -26,14 +30,14 @@ handlebars example.handlebars -f example.precompiled.js
Include the Handlebars runtime and the precompile javascript.
-<<< @/src/usage-examples/precompilation/index.html
+<<< @/snippets/precompilation/index.html
The runtime is also available for download on the [installation page](index.md#downloading-handlebars).
## Optimizations
-Because you are precompiling templates, you can also apply several optimization to the compiler. The first allows you to
-specify a list of the known helpers to the compiler
+Because you are precompiling templates, you can also apply several optimizations to the compiler. The first allows you
+to specify a list of the known helpers to the compiler
```bash
handlebars -f
+ 
+