96 lines
4.4 KiB
Markdown
96 lines
4.4 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_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
|
|
<!-- 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](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.
|