toby3d/home
toby3d
/
home
1
0
Fork 0
Code Actions Packages Releases Activity
home/docs/README.ru.md

112 lines
7.4 KiB
Markdown
Raw Normal View History

:memo: Created README.md
2023-11-09 16:00:15 +00:00
# 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/`;
:memo: Updated README
2023-11-13 01:41:40 +00:00
* `HOME_STATIC_DIR` -- имя или путь директории в которой содержатся публично доступные файлы из любой части сайта "как есть", по-умолчанию `static/`;
:memo: Created README.md
2023-11-09 16:00:15 +00:00
* `HOME_PORT` -- порт на котором будет работать движок, по-умолчанию `3000`;
Конфигурация сайта и его страниц полностью обеспечивается через FrontMatter в Markdown-файлах находящиеся в `$HOME_CONTENT_DIR`.
Чтобы назначить глобальные настройки сайту нужно создать `index.md` в `$HOME_CONTENT_DIR` и указать в нём следующее:
```markdown
---
# Известные параметры:
:memo: Updated README due mono and multilang sites support
2023-11-13 02:52:23 +00:00
# Имя сайта для мультиязычных сайтов, название домашней страницы для
# моноязычного
title: "ACME Inc"
baseUrl: "https://example.com/" # Префикс для всех абсолютных URL
:memo: Created README.md
2023-11-09 16:00:15 +00:00
timeZone: "UTC" # Имя часового пояса
:memo: Updated README due mono and multilang sites support
2023-11-13 02:52:23 +00:00
# Язык для перенаправления запросов с неподдерживаемой локализацией к пути /
# для мультиязычных сайтов, базовый язык для моноязычных
defaultLanguage: "en"
:memo: Created README.md
2023-11-09 16:00:15 +00:00
# Любые другие наборы ключей-значений будут восприниматься как второстепенные параметры и доступные через `.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, например:
:memo: Updated README
2023-11-13 01:41:40 +00:00
* `$HOME_CONTENT_DIR/folder/file.md`:
* `/folder/file`
* `/folder/file/`
* `/folder/file.html`
* `$HOME_CONTENT_DIR/now/index.md`:
* `/now`
* `/now/`
* `/now/index.html`
:memo: Created README.md
2023-11-09 16:00:15 +00:00
* и так далее;
Правила по локализациям здесь также применимы: `folder/file.ru.md` b `folder/file.en.md`, `now.jp.md`, `2023/11/09.de.md` и так далее.
Содержимое публикуемых страниц также соответствует формату FrontMatter:
```markdown
---
# Известные параметры:
title: "Hello, World!"
:memo: Updated README
2023-11-13 01:41:40 +00:00
description: "Demo page for demo"
:memo: Created README.md
2023-11-09 16:00:15 +00:00
# Любые другие наборы ключей-значений будут восприниматься как второстепенные параметры и доступные через `.Page.Params`:
style:
accent: "#0a0a23"
icon: "👋🏻"
tags:
- example
- demo
- blog
contact: "hey@toby3d.me"
---
This is a sample page content for demo.
```
:memo: Updated README
2023-11-13 01:41:40 +00:00
Любые статические файлы могут быть размещены и опубликованы двумя способами:
* В `$HOME_STATIC_DIR` как публично доступная статика, без каких-либо ограничений "как есть", по тому же пути в котором файл расположен в директории;
* В `$HOME_CONTENT_DIR` рядом с нужной страницей: файл будет доступен в коллекциях `.Site.Resources` и `.Page.Resources` и ограничен настройками доступа родительской страницы;
:memo: Created README.md
2023-11-09 16:00:15 +00:00
Для рендера содержимого страниц в браузерах необходимы шаблоны, которые должны размещаться в `$HOME_THEME_DIR`. Для работы необходим хотя бы один шаблон с блоком `baseof` который будет вызываться для каждой страницы, например:
```html
<!-- theme/baseof.html -->
{{ define "baseof" }}
<!DOCTYPE html>
:memo: Updated README
2023-11-13 01:41:40 +00:00
<html lang="{{ or .Page.Language.Lang .Site.Language.Lang }}"
dir="{{ or .Page.Language.Dir .Site.Language.Dir }}">
:memo: Created README.md
2023-11-09 16:00:15 +00:00
<head>
<meta charset="UTF-8">
<meta name="viewport"
content="width=device-width, initial-scale=1.0">
<title>{{ .Site.Title }}</title>
</head>
<body>
:memo: Updated README
2023-11-13 01:41:40 +00:00
{{ block "body" . }}{{ .Page.Content | transform.Markdownify }}{{ end }}
:memo: Created README.md
2023-11-09 16:00:15 +00:00
</body>
</html>
{{ end }}
```
:memo: Updated README
2023-11-13 01:41:40 +00:00
Шаблонизация работает по [инструкциям стандартного шаблонизатора Go](https://pkg.go.dev/html/template) с небольшими дополнениями в виде [дополнительных утилит](../internal/templateutil/templateutil.go). В `$HOME_THEME_DIR` разрешена любая комбинация и иеархия шаблонов и их взаимосвязей до тех пор, пока существует `baseof` в качестве единого родительского блока.
:memo: Created README.md
2023-11-09 16:00:15 +00:00
:pencil2: Added missing .Page variable menton in tempaltes section
2023-11-09 16:04:46 +00:00
В качестве контекста в каждый шаблон пробрасываются две структуры: `.Site` с глобальными опциям из `$HOME_CONTENT_DIR/index.md` и текущая просматриваемая страница `.Page` с её опциями найденная в `$HOME_CONTENT_DIR`. Структуры данных в этих контекстах можно посмотреть в пакете [domains](../internal/domain), они используются в шаблонах как есть.