111 lines
4.8 KiB
Markdown
111 lines
4.8 KiB
Markdown
# 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 with a `baseof` block that will be called for each page is required, for example:
|
|
```html
|
|
<!-- theme/baseof.html -->
|
|
|
|
{{ define "baseof" }}
|
|
<!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>
|
|
{{ 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](../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.
|