Merge pull request #27 from lightning-js/yamlify-docs

Yamlify docs

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 be as simple as a template with fixed, hardcoded values. However, for dynamic behavior and logic, you'll often want to extend your components with an _internal state_.
 
@@ -12,11 +19,11 @@ Some key concepts to keep in mind regarding Component state:
 - 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](./template_syntax.md), you can refer to state variables in an 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.dimensions.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.
 

docs/components.md

@@ -1,6 +1,13 @@
-# 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.
 

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.

docs/displaying_images.md

@@ -1,4 +1,9 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev:
+  text: Styling and positioning Elements
+  link: element_attributes
+next: false
+---
 
 ## Displaying Images
 

docs/element_attributes.md

@@ -1,12 +1,19 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev:
+  text: Watching for changes
+  link: watchers
+next:
+  text: Displaying Images
+  link: displaying_images
+---
 
-## 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 +32,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 +44,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 +72,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 +85,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 +97,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_.
 
@@ -118,7 +125,7 @@ Similar to rotation, scale is also applied recursively to children down the tree
 <Element w="200" h="200" color="#000" scale="{x: 1, y: 3.14}" />
 ```
 
-### 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.
 
@@ -136,7 +143,7 @@ In the case where the `x` and `y` values are the same (i.e. centering with `{x:
 <Element w="200" h="200" x="800" y="700" color="#333" mount="0.5" />
 ```
 
-### 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.
 

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.

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">

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
 
 Blits components follow a defined flow of lifecycle events. You can integrate specific 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.
 

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.
 

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.
 

docs/user_input.md

@@ -1,6 +1,13 @@
-# Blits - Lightning 3 App Development Framework
+---
+prev:
+  text: Props
+  link: props
+next:
+  text: Computed properties
+  link: computed_properties
+---
 
-## Handling User Input
+# Handling User Input
 
 When building an App you probably want users to interact with it as well, for example to enable them to navigate through your App. In other words, you will want to handle _user input_. In the context of a Blits / Lightning App this often will be key input via a remote control.
 
@@ -12,7 +19,7 @@ Before diving into the specifics of key handling, it is important to understand
 
 The component that currently has focus, is the one that is responsible for handling the user input at that moment. For example, when a user clicks the _right_ or _left_ button while a _Poster Component_ has focus, it is that instance of the Poster Component that will initially _receive_ the key press event.
 
-### Configuring Input Handling
+## Configuring Input Handling
 
 Within the Component configuration object, the `input` key is used to define how the component should react to specific key presses when it has focus. The `input` key should be an `object literal` of `functions` for each input event that the component wants to handle.
 
@@ -35,7 +42,7 @@ export default Blits.Component('MyComponent', {
 }
 ```
 
-### Event Handling Chain
+## Event Handling Chain
 
 If the currently focused component does not handle a key press, Blits will traverse up the component hierarchy, checking for any _parent_ component that does have a function defined for that key press in the `input`-key. This input event handling chain continues until it reaches the root App component.
 

docs/watchers.md

@@ -1,22 +1,29 @@
-# 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.
 
 You might be tempted to handle this functionality inside a computed property, but this is not recommended. Computed properties should not have side effects, as side effects could potentially lead your app into an endless loop if not handled carefully.
 
 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_.
 
 The name of each function should correspond to the name of the internal state variable, prop, or computed property that you want to watch. Whenever the target value changes, the respective watcher function will be invoked.
 
 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
 {