# 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.
`-static` | Render and save all pages. (this feature is yet to be implemented)
`-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
`:custom()` | Add a custom string to the site body
`markdown_to_html(str: string)` | Returns generated HTML from provided Markdown string.

### Std

Name | Description
--- | ---
`std.fes_version()` | Get the current version of fes.
`std.site_version()` | Get the current version of the site, defined in `Fes.toml`.
`std.site_name()` | Get the current name of the site, defined in `Fes.toml`.
`std.site_title()` | Get the current name of the site, defined in `Fes.toml`.
`std.site_authors()` | Get a table of the authors of the site, defined in `Fes.toml`.
`std.join` | Get a table of the authors of the site, defined in `Fes.toml`.
`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.spa(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.copyright` | ©
`Registered Trademark` | ®
`Trademark` | ™

### 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.

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

### Site

Name | Description
--- | ---
`site.version` | The version of the website found in the Fes.toml
`site.name` | The name of the website found in the Fes.toml
`site.authors` | A table of all authors defined in Fes.toml

### 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`.