.. | ||
README.en.md | ||
README.ru.md |
home
Brand new™️ 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.
Install and run
Clone this repository and run it with the Go compiler:
> 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 iscontent/
;HOME_HOST
-- IP address where the engine will run, default is0.0.0.0.0
;HOME_THEME_DIR
-- the name or path of the directory that contains the template files, default istheme/
;HOME_STATIC_DIR
-- name or path of the directory containing publicly accessible files from any part of the site "as is", default isstatic/
;HOME_PORT
-- the port on which the engine will work, by default is3000
;
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:
---
# 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:
---
# 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:
<!-- 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 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 package, they are used in the templates as is.