|
||
---|---|---|
.. | ||
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_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:
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:
---
# 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:
<!-- theme/baseof.html -->
{{ define "baseof" }}
<!DOCTYPE html>
<html lang="{{ .Site.Language }}">
<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 }}{{ 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.