# home
> Brand new:tm: Golang-engine for my personal website. No databases, operation is entirely based on interacting with simple "as is" files. Potentially aims to be compatible with protocols [IndieWeb](https://indieweb.org/).

## Install and run
Clone this repository and run it with the Go compiler:
```bash
> git clone https://source.toby3d.me/toby3d/home -b develop
> cd home && go run .
```

The basic configuration of the engine is done via OS environment variables.

Four options are available:
* `HOME_CONTENT_DIR` -- the name or path of the directory that contains pages and static files, the default is `content/`;
* `HOME_HOST` -- IP address where the engine will run, default is `0.0.0.0.0`;
* `HOME_THEME_DIR` -- the name or path of the directory that contains the template files, default is `theme/`;
* `HOME_STATIC_DIR` -- name or path of the directory containing publicly accessible files from any part of the site "as is", default is `static/`;
* `HOME_PORT` -- the port on which the engine will work, by default is `3000`;

Configuration of the site and its pages is fully provided through FrontMatter in Markdown files located in `$HOME_CONTENT_DIR`.

To assign global settings to a site you need to create an `index.md` in `$HOME_CONTENT_DIR` and specify the following in it:
```markdown
---
# Known properties:
# Site name for multilingual site, homepage title for monolingual
title: "ACME Inc"
baseUrl: "https://example.com/" # Prefix of all absolute URL's
timeZone: "UTC" # Time zone name
# Fallback for unsupported language request to / path for multilang site, base
# language for monolingual
defaultLanguage: "en"

# Any other key-value sets will be treated as secondary parameters and accessed through the `.Site.Params`:
tokens:
  mastodonApi: "asdbjhqwe..."
  telegram: "bot1234..."
announcement: >
  You got mail!
backlink: "https://mstdn.io/@toby3d"
...
---
```

## Usage
Pages are published instantly through the creation of Markdown files. Index files of the home page and sections are called `index.md` or `index.lang.md` where `lang` is a two-letter designation of the localization language. The engine supports working with any number of localizations of the same pages: `index.ru.md`, `index.en.md`, `index.jp.md` and so on.

Individual pages can be named anything, the name will be used as a slug from the URL, e.g.:
* `$HOME_CONTENT_DIR/folder/file.md`:
  * `/folder/file`
  * `/folder/file/`
  * `/folder/file.html`
* `$HOME_CONTENT_DIR/now/index.md`:
  * `/now`
  * `/now/`
  * `/now/index.html`
* and so on;

The rules on localizations also apply here: `folder/file.ru.md` b `folder/file.en.md`, `now.jp.md`, `2023/11/09.de.md` and so on.

The content of the published pages also conforms to the FrontMatter format:
```markdown
---
# Known properties:
title: "Hello, World!"
description: "Demo page for demo"

# Any other key-value sets will be treated as secondary parameters and accessed through the `.Page.Params`:
style:
  accent: "#0a0a23"
  icon: "👋🏻"
tags:
  - example
  - demo
  - blog
contact: "hey@toby3d.me"
---
This is a sample page content for demo.
```

Any static files can be hosted and published in two ways:
* In `$HOME_STATIC_DIR` as publicly available static, "as is" without any restrictions, in the same path in which the file is located in the directory;
* In `$HOME_CONTENT_DIR` next to the specific page: the file will be available in the `.Site.Resources` and `.Page.Resources` collections and restricted by the access settings of the parent page;

Templates are required to render page content in browsers and must be placed in `$HOME_THEME_DIR`. At least one template `baseof.html` that will be called for each page is required, for example:
```html
<!-- theme/baseof.html -->

<!DOCTYPE html>
<html lang="{{ or .Page.Language.Lang .Site.Language.Lang }}"
  dir="{{ or .Page.Language.Dir .Site.Language.Dir }}">

  <head>
    <meta charset="UTF-8">
    <meta name="viewport"
          content="width=device-width, initial-scale=1.0">

    <title>{{ .Site.Title }}</title>
  </head>
  <body>
    {{ block "body" . }}{{ .Page.Content | transform.Markdownify }}{{ end }}
  </body>
</html>
```

Templating works according to [the instructions of the standard Go templating engine](https://pkg.go.dev/html/template) with minor additions in the form of [additional utilities](../internal/templateutil/templateutil.go). In `$HOME_THEME_DIR`, any combination and hierarchy of templates and their relationships is allowed as long as there is a `baseof` as a single parent block.

Two structures are thrown into each template as contexts: `.Site` with global options from `$HOME_CONTENT_DIR/index.md` and the currently viewed page `.Page` with its options found in `$HOME_CONTENT_DIR`. The data structures in these contexts can be found in the [domains](../internal/domain) package, they are used in the templates as is.
