From 77a851dd50b5015940de9918d6af9b054b361d37 Mon Sep 17 00:00:00 2001
From: jfboeve <jeffrey_boeve@comcast.com>
Date: Fri, 24 Nov 2023 10:14:29 +0100
Subject: [PATCH] add yaml to start of .md files

---
 docs/component_state.md     | 15 +++++++++++----
 docs/components.md          | 13 ++++++++++---
 docs/computed_properties.md | 10 ++++++++--
 docs/element_attributes.md  | 25 +++++++++++++++----------
 docs/getting_started.md     | 15 ++++++++++-----
 docs/index.html             |  1 +
 docs/lifecycle_events.md    | 15 +++++++++++----
 docs/props.md               | 13 ++++++++++---
 docs/template_syntax.md     | 13 ++++++++++---
 docs/user_input.md          | 15 +++++++++++----
 docs/watchers.md            | 15 +++++++++++----
 11 files changed, 108 insertions(+), 42 deletions(-)

diff --git a/docs/component_state.md b/docs/component_state.md
index 76acac4c..778541dd 100644
--- a/docs/component_state.md
+++ b/docs/component_state.md
@@ -1,6 +1,13 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev:
+  text: Template syntax
+  link: template_syntax
+next:
+  text: Hooking into lifecycle events
+  link: lifecycle_events
+---
 
-## Component State
+# Component State
 
 In Blits, a component can start as simple as a template with fixed, hardcoded values. However, for dynamic behavior and logic, you'll often want to incorporate an internal state within your components.
 
@@ -12,10 +19,10 @@ Some key concepts to keep in mind:
 - The structure of the `state` object is flexible, allowing you to define state values according to your component's requirements. These values can range from `strings`, `booleans`, `arrays`, to even nested `objects`.
 - While flexibility in structuring your state is advantageous, be cautious about excessive nesting, as it could have a negative effect on performance.
 
-### Accessing State in Templates
+## Accessing State in Templates
 
 As explained in the template section, you can refer to state variables in your Element's arguments by prefixing the state variable name with a dollar sign (e.g., `$alpha`). For nested objects, you can use dot notation (e.g., `$style.w`).
 
-### Accessing State in Component Code
+## Accessing State in Component Code
 
 In your component's code, you can reference state variables within the `this` scope. For instance, a state variable named `color` can be accessed and modified by referencing `this.color`. It's important to note that unlike in the template, you should not use the dollar sign when accessing state variables within the component's code.
diff --git a/docs/components.md b/docs/components.md
index 0d7ce811..cbdd9f8e 100644
--- a/docs/components.md
+++ b/docs/components.md
@@ -1,13 +1,20 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev:
+  text: Getting Started
+  link: getting_started
+next:
+  text: Template syntax
+  link: template_syntax
+---
 
-## Building Your First Component
+# Building Your First Component
 
 Components in Blits follow a clearly defined structure, which helps keep your code clean and guides you to quickly build your components.
 
 This universal structure is also valuable for the interoperability of components.
 
 
-### Creating a new Component
+## Creating a new Component
 
 Let's see how to create a new component and explore the basic anatomy of a component.
 
diff --git a/docs/computed_properties.md b/docs/computed_properties.md
index f4ffc88b..db728a66 100644
--- a/docs/computed_properties.md
+++ b/docs/computed_properties.md
@@ -1,5 +1,11 @@
-# Blits - Lightning 3 App Development Framework
-
+---
+prev:
+  text: Handling user input
+  link: user_input
+next:
+  text: Watching for changes
+  link: watchers
+---
 ## Computed properties
 
 So far we've learned how to utilize internal state variables and props passed by a parent in (the template of) our component.
diff --git a/docs/element_attributes.md b/docs/element_attributes.md
index b37b441d..4c57043e 100644
--- a/docs/element_attributes.md
+++ b/docs/element_attributes.md
@@ -1,12 +1,17 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev:
+  text: Watching for changes
+  link: watchers
+next: false
+---
 
-## Styling and positioning Elements
+# Styling and positioning Elements
 
 The core building block of a Blits template is the Element tag. The Element tag corresponds directly to a node in the Lightning 3 Renderer. You can style and position Elements via _attributes_, much like you would do in HTML.
 
 Blits Elements have a specific set of attributes that can be set, loosely modeled after the properties of a Lightning 3 renderer node. In certain cases Blits provides more developer friendly names or accepts a wider range of values, and transparently takes care of the translation into L3 renderer instructions.
 
-### Positioning and Dimensions
+## Positioning and Dimensions
 
 In order to position and set the dimensions of an Element, the following attributes can be used.
 
@@ -25,7 +30,7 @@ All positioning and dimension related attributes, when not specified, default to
 </Element>
 ```
 
-#### Using percentages
+### Using percentages
 
 Besides using values in pixels (i.e. `w="100" h="300"`), you can also specify _percentages_ for the positioning and dimensions attributes.
 
@@ -37,7 +42,7 @@ Besides using values in pixels (i.e. `w="100" h="300"`), you can also specify _p
 The percentage specified in `w` and `x` will be calculated as the percentage of the _width_ (`w`) of the parent element.
 And the percentage specified in `h` and `y` will use the _height_ (`h`) of the parent element as the base of the percentage calculation.
 
-### Colors
+## Colors
 
 By default Elements have a transparent background color. The `color` attribute can be used to give an Element a color.
 
@@ -65,7 +70,7 @@ HSL and HSLA formats are planned to be added in the future.
 <Element w="200" h="200" color="skyblue" />
 ```
 
-#### Basic linear gradients
+### Basic linear gradients
 
 The color attribute can also be used to specify basic linear gradients.
 
@@ -78,7 +83,7 @@ A linear gradient can be defined by specifying an _object literal_ as the `color
 <Element w="200" h="200" color="{bottom: 'black'}" />
 ```
 
-### Alpha and visibility
+## Alpha and visibility
 
 The opacity of an Element, can be controlled by setting the `alpha` attribute. This attribute accepts a value between `0` (fully transparent) and `1` (completely visible).
 
@@ -90,7 +95,7 @@ The value of alpha is also being applied recursively to the children of the Elem
   </Element>
 ```
 
-### Rotation and scaling
+## Rotation and scaling
 
 If you want to rotate an Element, you can use the `rotation` attribute. The rotation attribute in Blits accepts values in degrees. The rotation of an Element is also automatically applied to any children down the tree.
 
@@ -109,7 +114,7 @@ Similar to rotation, scale is also applied recursively to children down the tree
 <Element w="200" h="200" color="#000" scale="2.3" />
 ```
 
-### Mounting point
+## Mounting point
 
 For advanced positioning the `mount` attribute can come in handy. By default when you set the `x` and `y` position of an Element, the _top-left_ corner will be set to that position. But in some cases you may want to align the position starting at a different corner, or even any arbitrary point in between.
 
@@ -124,7 +129,7 @@ If you omit either the `x` or the `y` key from the _object literal_, it's value
 <Element w="200" h="200" x="800" y="400" color="#333" mount="{y: 1}" />
 ```
 
-### Pivot point
+## Pivot point
 
 The pivot point of an Element comes into play when it's rotated or scaled. The pivot point defaults to the center of the Element, which means that when setting `rotation` it rotates around the middle. And when the Element is scaled it scales from the center out.
 
diff --git a/docs/getting_started.md b/docs/getting_started.md
index ad66c1a0..9d6774cf 100644
--- a/docs/getting_started.md
+++ b/docs/getting_started.md
@@ -1,10 +1,15 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev: false
+next:
+  text: Components
+  link: components
+---
 
-## Getting Started
+# Getting Started
 
 To begin with Blits, follow these simple steps to set up your development environment and create your first Lightning 3 App.
 
-### Installation
+## Installation
 
 1. Open your terminal or command prompt.
 
@@ -23,7 +28,7 @@ cd my_lightning3_app
 npm install
 ```
 
-### Running Your App
+## Running Your App
 
 1. After installing the dependencies, you can start your development server by running:
 
@@ -35,6 +40,6 @@ This command will create an application bundle and launch a development server u
 
 2. Once the server is up and running, open your web browser and navigate to the URL displayed in the console. Congratulations! You now have your brand new Lightning 3 App up and running.
 
-### Next steps
+## Next steps
 
 You are now ready to dive into the world of TV app development using Blits. In the following sections, we will explore the core concepts and guide you through building your TV applications step by step.
diff --git a/docs/index.html b/docs/index.html
index 1a13041e..bb3d98e8 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -38,6 +38,7 @@
   </script>
   <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/docsify-themeable@0"></script>
+  <script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/front-matter.min.js"></script>
   <script
     src="//cdn.jsdelivr.net/npm/docsify-darklight-theme@latest/dist/index.min.js"
     type="text/javascript">
diff --git a/docs/lifecycle_events.md b/docs/lifecycle_events.md
index ca64a0bc..a38476f6 100644
--- a/docs/lifecycle_events.md
+++ b/docs/lifecycle_events.md
@@ -1,12 +1,19 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev:
+  text: Component state
+  link: component_state
+next:
+  text: Props
+  link: props
+---
 
-## Hooking into Lifecycle Events
+# Hooking into Lifecycle Events
 
 In Blits, components follow a defined flow of lifecycle events. Developers can integrate their logic into these events by specifying them in the `hooks` key of the Component configuration object.
 
 For each available lifecycle event, you can define a function with the same name as the event itself. This function will execute each time the event is triggered for your component's instance. It's essential to use a regular function instead of an arrow function if you intend to access the `this` scope of your component instance.
 
-### Lifecycle Events
+## Lifecycle Events
 
 - **init()**: This event fires when the component is instantiated, just before it sends its render instructions to the Lightning renderer. At this point, the elements of your template won't be available yet.
 
@@ -18,7 +25,7 @@ For each available lifecycle event, you can define a function with the same name
 
 - **destroy()**: The `destroy` event fires when the component is being destroyed and removed. This event provides an opportunity to perform any custom cleanup operations before the component is removed.
 
-### Example
+## Example
 
 ```javascript
 {
diff --git a/docs/props.md b/docs/props.md
index f3630942..a9eb55f7 100644
--- a/docs/props.md
+++ b/docs/props.md
@@ -1,6 +1,13 @@
-# Blits - Lightning 3 App Development Framework
-
-## Props
+---
+prev:
+  text: Hooking into lifecycle events
+  link: lifecycle_events
+next:
+  text: Handling user input
+  link: user_input
+---
+
+# Props
 
 Components in Blits have their own internal state and logic. However, as each component is part of the larger app's scope, they may need to display different behaviors or appearances based on the rest of the app. To achieve this, components can receive `props` from their parent component.
 
diff --git a/docs/template_syntax.md b/docs/template_syntax.md
index db9e25fa..3c09ba1e 100644
--- a/docs/template_syntax.md
+++ b/docs/template_syntax.md
@@ -1,6 +1,13 @@
-# Blits - Lightning 3 App Development Framework
-
-## Template structure
+---
+prev:
+  text: Components
+  link: components
+next:
+  text: Component State
+  link: component_state
+---
+
+# Template structure
 
 Blits uses an easy-to-read XML-style template syntax. The syntax is inspired by frameworks like VueJS, so developers familiar with Vue will recognize certain concepts.
 
diff --git a/docs/user_input.md b/docs/user_input.md
index 2e443e46..20942554 100644
--- a/docs/user_input.md
+++ b/docs/user_input.md
@@ -1,12 +1,19 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev:
+  text: Props
+  link: props
+next:
+  text: Computed properties
+  link: computed_properties
+---
 
-## Handling User Input
+# Handling User Input
 
 You don't want your Lightning 3 App to be completely static, instead users should be able to navigate and interact with the app, often using devices like a remote control.
 
 Blits offers a straightforward interface to handle user input for each component.
 
-### Configuring Input Handling
+## Configuring Input Handling
 
 Within the Component configuration object, the `input` key is utilized to define how the component should react to specific key presses when it has focus. It should contain an object of functions that specify the actions to take based on key presses.
 
@@ -28,7 +35,7 @@ Each function should correspond to a key name, such as `up`, `down`, `enter`, `s
 }
 ```
 
-### Event Handling Chain
+## Event Handling Chain
 
 If the currently focused component does not handle a key press, the framework will traverse up the component hierarchy, checking if any parent components have defined functions for that key press in their `input`-object. This event handling chain continues until it reaches the root Application.
 
diff --git a/docs/watchers.md b/docs/watchers.md
index b667095c..6f8b76d0 100644
--- a/docs/watchers.md
+++ b/docs/watchers.md
@@ -1,6 +1,13 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev:
+  text: Computed properties
+  link: computed_properties
+next:
+  text: Styling and positioning Elements
+  link: element_attributes
+---
 
-## Watching for Changes
+# Watching for Changes
 
 In some cases, you may want to execute specific actions whenever the value of a state variable, a prop, or a computed property changes. These actions could involve dispatching an event or updating another state variable.
 
@@ -8,7 +15,7 @@ You might be tempted to handle this functionality inside a computed property, bu
 
 Instead, Blits allows you to specify **watchers**.
 
-### Using Watchers
+## Using Watchers
 
 Within the `watch` key of the Component configuration object, you can define an object of _watcher functions_.
 
@@ -16,7 +23,7 @@ The name of each function should correspond to the name of the internal state va
 
 The watcher function receives two arguments: the new value and the old value of the observed property. This allows you to perform specific actions based on the changes.
 
-### Example:
+## Example:
 
 ```javascript
 {