# 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_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:
title: "ACME Inc" # Site title/name
baseUrl: "https://example.com/" # Prefix of all relative URL's
timeZone: "UTC" # Time zone name
# 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/index.html` and `/folder/file.html`;
* `$HOME_CONTENT_DIR/now/index.md`: `/now`, `/now/`, `/now/index.html` and `/now.html`;
* `$HOME_CONTENT_DIR/2023/11/09.md`: `/2023/11/09`, `/2023/11/09/`, `/2023/11/09/index.html` and `/2023/11/09.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!"
# 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.
```
Static files like images, videos, `robots.txt`, styles, scripts and anything else are placed in `$HOME_CONTENT_DIR` as they are: in the root if they should be available globally via `.Site.Files` and for home pages, as well as in the necessary directories with pages to access them via `.Page.Files`. The format and filenames are not restricted in any way.
Templates are required to render page content in browsers and must be placed in `$HOME_THEME_DIR`. At least one template with a `baseof` block that will be called for each page is required, for example:
```html
{{ define "baseof" }}
{{ .Site.Title }}
{{ block "body" . }}{{ .Page.Content }}{{ end }}
{{ end }}
```
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. 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.