installation and get started docs

beforesemicolon · Oct 3, 2024 · 78939ff · 78939ff
1 parent 537ecd3
commit 78939ff
Show file tree

Hide file tree

Showing 5 changed files with 198 additions and 0 deletions.
diff --git a/docs/documentation/capabilities/function-component.md b/docs/documentation/capabilities/function-component.md
@@ -7,3 +7,103 @@ layout: document
 ---
 
 ## Function Component
+
+Markup does not ship with a dedicated component API. Components are simply functions that return a `HTMLTemplate` instance.
+
+```javascript
+const MyButton = () => {
+  return html`
+    <button type="button">
+      click me
+    </button>
+  `;
+}
+```
+
+It is totally up to you what these functions can do or look like. From the example above, you can simply render your component using the `render` method.
+
+```javascript
+MyButton().render(document.body)
+```
+
+### Inputs (Props)
+
+Since its functions, you can take arguments and inject them directly into the template with proper defaults handling.
+
+```javascript
+const Button = ({
+  content = "", 
+  disabled = false, 
+  type = "button"
+}) => {
+  return html`
+    <button 
+      type="${type}"
+      disabled="${disabled}"
+      >
+      ${content}
+    </button>`;
+}
+```
+
+Templates can take raw values or functions that returns some value which can be a `state` or simply a `dynamic value`, in that case, you can have your input type definition use the `StateGetter` type.
+
+```typescript
+enum MyButtonType {
+    Button = 'button',
+    Reset = 'reset',
+    Submit = 'submit'
+}
+
+interface MyButtonProps {
+    content: unknown;
+    disabled: boolean | StateGetter<boolean>
+    type: MyButtonType | StateGetter<MyButtonType>
+}
+```
+
+The `StateGetter` allows you to communicate that your component takes function values as input which makes it easier to work with states.
+
+### Lifecycles
+
+You can take advantage of both [effect](../state/effect.md) and `html` [lifecycles](../templating/lifecycles.md) to react to things like component mounted, unmounted, and updates to do everything you need.
+
+```javascript
+const ChatMessages = () => {
+    const [messages, updateMessages] = state([])
+
+    onUpdate(() => {
+        // todo: scroll to the bottom to show latest msg
+    })
+
+    const onMount = () => {
+        const controller = new AbortController();
+        const signal = controller.signal;
+
+        fetch('...', { signal })
+            .then((res) => {
+                if(!res.ok) throw new Error(res.statusText)
+
+                return res.json()
+            })
+            .then((res) => updateMessages(res.messages))
+            .catch(console.error);
+
+        // return a function to be called on unmount
+        // where you can perform any clean ups
+        return () => {
+            controller.abort();
+        }
+    }
+
+    return html`
+        <ul>
+            ${repeat(messages, msg => html`<li>${msg}</li>
+        </ul>
+    `)}
+        .onMount(onMount)
+        .onUpdate(onUpdate)
+}
+```
+
+Markup template has powerful lifecycles and because a function is called once and with power of reactivity, you can encapsulate everything inside the function leaving everything to Markup to manage.
diff --git a/docs/documentation/get-started.md b/docs/documentation/get-started.md
@@ -7,3 +7,43 @@ layout: document
 ---
 
 ## Get Started
+
+Markup is a plug and play library, which means, you don't need to build or compile it into anything to be able to see what you build.
+
+Additionally, you can run it on the client and server to produce any type of application.
+
+### Try it in-Browser
+
+The simplest way to start is by trying it in-browser, and we have set up few project you can get started with:
+
+- [Client ToDo App with State Management](https://stackblitz.com/edit/web-platform-lvonxr) (StackBlitz)
+- [Client Counter App](https://stackblitz.com/edit/web-platform-ixypdh) (StackBlitz)
+- [Client Timer App](https://codepen.io/beforesemicolon/pen/yLQzQZV) (CodePen)
+- [Node SSR website](https://stackblitz.com/edit/stackblitz-starters-a6rvq7) (StackBlitz)
+
+### HTML File
+
+The simplest way to start is by creating an html file and adding the following content. You can then open it in the browser to see.
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <title>Hello World</title>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width" />
+    <script src="https://unpkg.com/@beforesemicolon/markup/dist/client.js"></script>
+  </head>
+  <body>
+    <div id="app"></div>
+
+    <script>
+      const { html, state } = BFS.MARKUP;
+
+      html`
+        <h1>Hello World</h1>
+      `.render(document.getElementById('app'));
+    </script>
+  </body>
+</html>
+```
diff --git a/docs/documentation/installation.md b/docs/documentation/installation.md
@@ -7,3 +7,54 @@ layout: document
 ---
 
 ## Installation
+
+Markup is a plug-and-play package that does not need to be built. There is no need to any additional setup or requirements to get started. Simply add it to your project and proceed.
+
+### Via CDN
+
+This method is the quickest loading option and can be placed in the head tag of the document.
+
+```html
+<script src="https://unpkg.com/@beforesemicolon/markup/dist/client.js" />
+```
+
+You may also specify a specific version you want.
+
+```html
+<script src="https://unpkg.com/@beforesemicolon/[email protected]/dist/client.js"/>
+```
+
+You can use various CDN providers like **unpkg**, **jsDelivr**.
+
+```html
+<script src="https://unpkg.com/@beforesemicolon/markup/dist/client.js"/>
+<script src="https://cdn.jsdelivr.net/npm/@beforesemicolon/markup/dist/client.js"/>
+```
+
+The client CDN link will create a global BFS.MARKUP variable you can access for all the internal functions.
+
+```javascript
+const {html, state, effect} = BFS.MARKUP;
+```
+
+### Via npm
+
+This package is also available via **npm** which will allow you to use it in server-side JavaScript environments.
+
+```
+npm install @beforesemicolon/markup
+```
+
+```javascript
+import {html, state, effect} from "@beforesemicolon/markup";
+```
+
+### Via yarn
+
+``` 
+yarn add @beforesemicolon/markup
+```
+
+### Typescript
+
+This package was built using typescript. You don't need to install a separate types package for it. All types are exported with it.
diff --git a/docs/stylesheets/common.css b/docs/stylesheets/common.css
@@ -287,6 +287,10 @@ footer .copyright img {
     background: #d2ae1e;
 }
 
+.code-snippet .label.typescript {
+    background: #496cff;
+}
+
 .code-snippet .label.css {
     background: #2680c7;
 }

diff --git a/docs/stylesheets/documentation.css b/docs/stylesheets/documentation.css
@@ -173,6 +173,7 @@
 
 #documentation article code:not(.hljs) {
     background: #161a1c;
+    color: #D2ECFF;
     display: inline-block;
     padding: 3px 8px;
     border-radius: 2px;
@@ -263,6 +264,8 @@
 
 #documentation #table-of-content li a {
     text-decoration: none;
+    text-underline-offset: 3px;
+    line-height: 130%;
 }
 
 #documentation #table-of-content li a:active,