# Documentation

Fes: A lightweight, static, and opinionated microframework.

## Introduction

Fes, or Free Easy Site, is a microframework used for small static sites. It is not designed for complex web applications and that is why it is good. Yes, I hate modern web and that is the reason this exists.

## Installation

    git clone https://git.vxserver.dev/fSD/fes

    cd fes

    go install fes

## Usage

Typical workflows and examples.

- Creating project
- Hosting websites
- Generating websites

## Quick Start

    fes new hello

This creates a new project under the name `hello`.

    fes run hello

This runs your project `hello`, by default at localhost:3000.

### Extensions

Let's add a paragraph to this simple site. Right now you have the following page:

    local fes = require("fes")
    local site = fes.fes()

    -- site.copyright = fes.util.copyright("https://fsd.vxserver.dev", "vx-clutch")

    site:h1("Hello, World!")

    return site

To add a simple paragraph modify like so:

    local fes = require("fes")
    local site = fes.fes()

    -- site.copyright = fes.util.copyright("https://fsd.vxserver.dev", "vx-clutch")

    site:h1("Hello, World!")
    site:p("This is a paragraph")

    return site

## Cli Reference

Name | Description
--- | ---
`new <project>` | Create a new projet called <project>
`doc` | Open this documention page
`run <project>` | Run the projet called <project>
`-help` | Display help information.
`-V1` | Print extended version information, this is very helpful when it comes to bug reporting.
`-no-color` | Disable color output.
`-p <port>` | Set the server port.
`-version` | Print the version.

## Reference

All `std` functions have binding for the site and can be used like so: `site:h1("Hello, World!")`, where site is the site object.

### Builtin

Name | Description
--- | ---
`fes()` | Generate a site object
`:g()` | Add a custom string to the site body
`markdown_to_html(str: string)` | Returns generated HTML from provided Markdown string.

### Std

Name | Description
--- | ---
`std.a(link: string, str: string)` | Returns an anchor tag.
`std.ha(link: string, str: string)` | Returns an anchor tag with sytiling to make it hidden.
`std.external(link: string, str: string)` | Returns an anchor tag that opens up in a new tab.
`std.note(str: string)` | Returns a note object.
`std.muted(str: string)` | Returns a muted object.
`std.callout(str: string)` | Returns a callout object.
`std.h1(str: string)` | Returns a header level 1 object.
`std.h2(str: string)` | Returns a header level 2 object.
`std.h3(str: string)` | Returns a header level 3 object.
`std.h4(str: string)` | Returns a header level 4 object.
`std.h5(str: string)` | Returns a header level 5 object.
`std.h6(str: string)` | Returns a header level 6 object.
`std.p(str: string)` | Returns a paragraph object.
`std.pre(str: string)` | Returns preformated text.
`std.code(str: string)` | Returns a codeblock.
`std.ul(items: {...strings})` | Generates an unordered list from a table of strings.
`std.ol(items: {...strings})` | Generates an ordered list from a table of strings.
`std.tl(items: {...strings})` | Generates a table from a table of strings.
`std.blockquote(str: string)` | Returns a blockquote.
`std.hr()` | Returns a horizonal rule.
`std.img(src: string, alt: string)` | Returns an image at location source with given alternative text.
`std.strong(str: string)` | Returns bolded text.
`std.em(str: string)` | Returns italicized text.
`std.br()` | Returns a break.
`std.div(content: string, class: string)` | Returns a div of class `class` with content of `content`.
`std.span(content: string, class: string)` | Returns a span of class `class` with content of `content`.
`std.escape(str: string)` | Returns an html escaped string.
`std.highlight(str: string)` | Returns highlighted text.
`std.banner(str: string)` | Returns a banner that is attached to the top of the site.
`std.center(str: string)` | Returns centered text.
`std.nav(link: string, str: string)` | Returns a speical navigation link, used for in-site traversal.
`std.rl(r: string, l: string)` | Right and light alight content.

### Symbol

Name | Symbol
--- | ---
`symbol.legal.copyright` | ©
`symbol.legal.registered_trademark` | ®
`symbol.legal.trademark` | ™
`symbol.currency.euro` | €
`symbol.currency.pound` | £
`symbol.currency.yen` | ¥
`symbol.currency.cent` | ¢
`symbol.currency.dollar` | $
`symbol.currency.plus_minus` | ±
`symbol.currency.multiply` | ×
`symbol.currency.divide` | ÷
`symbol.currency.not_equal` | ≠
`symbol.currency.less_equal` | ≤
`symbol.currency.greater_equal` | ≥
`symbol.currency.infinity` | ∞
`symbol.currency.approx` | ≈
`symbol.arrows.left` | ←
`symbol.arrows.right` | →
`symbol.arrows.up` | ↑
`symbol.arrows.down` | ↓
`symbol.arrows.left_right` | ↔
`symbol.punctuation.left_double_quote` | “
`symbol.punctuation.right_double_quote` | ”
`symbol.punctuation.left_single_quote` | ‘
`symbol.punctuation.right_single_quote` | ’
`symbol.punctuation.ellipsis` | …
`symbol.punctuation.em_dash` | —
`symbol.punctuation.en_dash` | –
`symbol.whitespace.non_breaking` |
`symbol.whitespace.thin` |
`symbol.symbols.degree` | °
`symbol.symbols.micro` | µ
`symbol.symbols.section` | §
`symbol.symbols.paragraph` | ¶
`symbol.symbols.check` | ✓
`symbol.symbols.cross` | ✗
`symbol.symbols.bullet` | •
`symbol.symbols.middle_dot` | ·
`symbol.symbols.broken_bar` | ¦
`symbol.html.less_than` | <
`symbol.html.greater_than` | >
`symbol.html.ampersand` | &
`symbol.html.double_quote` | "
`symbol.html.single_quote` | '

### Util

Name | Description
--- | ---
`util.cc(tbl: {...strings})` | Concatenate a table of strings into a single string.
`util.copyright(link: string, holder: string)` | Used when setting the website copyright holder.
`util.ls(dir)` | Returns a table of the files in the given directory
`util.run(cmd)` | Returns the output of the provided command. stdout only.

### Dkjson

This is a third party object and is best documented here

Name | Description
--- | ---
`dkjson.encode(obj: {...any})` | Serilize a Lua table into JSON.
`dkjson.decode(obj: {...any})` | Deserilize JSON into a Lua table.

### Bus

Name | Description
--- | ---
`bus.url` | The current url that was given.
`bus.params` | A table of url parameters if any. Ex: ?foo=bar*baz=foobar

### App

Fes's `app` module is a special table because it contains user defined functions. These functions are defined in the `include/` For example if you define a `include/hello.lua` file with given contents:

    local hello = {}

    hello.render(std) return std.h1("Hello, World!") end

    return hello

This can be called from another with, `fes.app.hello.render(fes.std)`. Do with this as you will.

### Speical Directories

Name | Description
--- | ---
`www/` | The main website is contained here, this is where www/index.lua lives.
`static/` | All static content should be placed here and can be accessed at `/static/path-to-file`.
`include/` | Contains lua files that are preloaded and globally accessible.
`archive/` | Files here can be viewed in a file browser like format at `/archive/path-to-dir`.