📝 Created README.md
/ docker (push) Has been cancelled
Details
/ docker (push) Has been cancelled
Details
This commit is contained in:
parent
ed217f118c
commit
e60cd785c2
GPG Key ID:
1F14E25B7C119FC5
|
|
@ -0,0 +1,95 @@
|
|||
# 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`;
|
||||
* `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 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.
|
||||
|
|
@ -0,0 +1,95 @@
|
|||
# home
|
||||
> Совершенно новый:tm: Golang-движок для моего персонального сайта. Без баз данных, работа полностью основана на взаимодействии с простыми файлами "как есть". Потенциально стремится к совместимости с протоколами [IndieWeb](https://indieweb.org/).
|
||||
|
||||
## Установка и запуск
|
||||
Склонируйте этот репозиторий и запустите его компилятором Go:
|
||||
```bash
|
||||
> git clone https://source.toby3d.me/toby3d/home -b develop
|
||||
> cd home && go run .
|
||||
```
|
||||
|
||||
Базовая конфигурация движка осуществляется через переменные окружения ОС.
|
||||
|
||||
Доступны четыре опции:
|
||||
* `HOME_CONTENT_DIR` -- имя или путь директории в которой содержатся страницы и статика, по-умолчанию `content/`;
|
||||
* `HOME_HOST` -- IP-адрес на котором будет работать движок, по-умолчанию `0.0.0.0`;
|
||||
* `HOME_THEME_DIR` -- имя или путь директории в которой содержатся файлы шаблонов, по-умолчанию `theme/`;
|
||||
* `HOME_PORT` -- порт на котором будет работать движок, по-умолчанию `3000`;
|
||||
|
||||
Конфигурация сайта и его страниц полностью обеспечивается через FrontMatter в Markdown-файлах находящиеся в `$HOME_CONTENT_DIR`.
|
||||
|
||||
Чтобы назначить глобальные настройки сайту нужно создать `index.md` в `$HOME_CONTENT_DIR` и указать в нём следующее:
|
||||
```markdown
|
||||
---
|
||||
# Известные параметры:
|
||||
title: "ACME Inc" # Название сайта
|
||||
baseUrl: "https://example.com/" # Префикс всех относительных URL
|
||||
timeZone: "UTC" # Имя часового пояса
|
||||
|
||||
# Любые другие наборы ключей-значений будут восприниматься как второстепенные параметры и доступные через `.Site.Params`:
|
||||
tokens:
|
||||
mastodonApi: "asdbjhqwe..."
|
||||
telegram: "bot1234..."
|
||||
announcement: >
|
||||
You got mail!
|
||||
backlink: "https://mstdn.io/@toby3d"
|
||||
...
|
||||
---
|
||||
```
|
||||
|
||||
## Использование
|
||||
Страницы публикуются мгновенно через создание Markdown-файлов. Индексные файлы главной страницы и директорий называются `index.md` или `index.lang.md` где `lang` это двубуквенное обозначение языка локализации. Движок поддерживает работу с любым числом локализаций одних и тех же страниц: `index.ru.md`, `index.en.md`, `index.jp.md` и так далее.
|
||||
|
||||
Именованные страницы могут называться как угодно, имя будет использоваться в качестве slug из URL, например:
|
||||
* `$HOME_CONTENT_DIR/folder/file.md`: `/folder/file`, `/folder/file/`, `/folder/file/index.html` и `/folder/file.html`;
|
||||
* `$HOME_CONTENT_DIR/now/index.md`: `/now`, `/now/`, `/now/index.html` и `/now.html`;
|
||||
* `2023/11/09.md`: `/2023/11/09`, `/2023/11/09/`, `/2023/11/09/index.html` и `/2023/11/09.html`;
|
||||
* и так далее;
|
||||
|
||||
Правила по локализациям здесь также применимы: `folder/file.ru.md` b `folder/file.en.md`, `now.jp.md`, `2023/11/09.de.md` и так далее.
|
||||
|
||||
Содержимое публикуемых страниц также соответствует формату FrontMatter:
|
||||
```markdown
|
||||
---
|
||||
# Известные параметры:
|
||||
title: "Hello, World!"
|
||||
|
||||
# Любые другие наборы ключей-значений будут восприниматься как второстепенные параметры и доступные через `.Page.Params`:
|
||||
style:
|
||||
accent: "#0a0a23"
|
||||
icon: "👋🏻"
|
||||
tags:
|
||||
- example
|
||||
- demo
|
||||
- blog
|
||||
contact: "hey@toby3d.me"
|
||||
---
|
||||
This is a sample page content for demo.
|
||||
```
|
||||
|
||||
Статические файлы вроде изображений, видео, `robots.txt`, стилей, скриптов и чего-угодно ещё размещаются в `$HOME_CONTENT_DIR` как есть: в корень если они должны быть доступны глобально через `.Site.Files` и для домашних страниц, а также в нужных директориях со страницами для доступа к ним через `.Page.Files`. Формат и имена файлов ничем не ограничены.
|
||||
|
||||
Для рендера содержимого страниц в браузерах необходимы шаблоны, которые должны размещаться в `$HOME_THEME_DIR`. Для работы необходим хотя бы один шаблон с блоком `baseof` который будет вызываться для каждой страницы, например:
|
||||
```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 }}
|
||||
```
|
||||
|
||||
Шаблонизация работает по [инструкциям стандартного шаблонизатора Go](https://pkg.go.dev/html/template) с небольшими дополнениями в виде дополнительных утилит. В `$HOME_THEME_DIR` разрешена любая комбинация и иеархия шаблонов и их взаимосвязей до тех пор, пока существует `baseof` в качестве единого родительского блока.
|
||||
|
||||
В качестве контекста в каждый шаблон пробрасываются две структуры: `.Site` с глобальными опциям из `$HOME_CONTENT_DIR/index.md` и текущая просматриваемая страница с её опциями найденная в `$HOME_CONTENT_DIR`. Структуры данных в этих контекстах можно посмотреть в пакете [domains](internal/domain), они используются в шаблонах как есть.
|
||||
Loading…
Reference in New Issue