diff --git a/docs/README.en.md b/docs/README.en.md index 7434330..2d1b4a7 100644 --- a/docs/README.en.md +++ b/docs/README.en.md @@ -14,6 +14,7 @@ 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_STATIC_DIR` -- name or path of the directory containing publicly accessible files from any part of the site "as is", default is `static/`; * `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`. @@ -41,9 +42,14 @@ backlink: "https://mstdn.io/@toby3d" 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`; +* `$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. @@ -53,6 +59,7 @@ 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: @@ -67,7 +74,9 @@ 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. +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: ```html @@ -75,7 +84,9 @@ Templates are required to render page content in browsers and must be placed in {{ define "baseof" }} - + + {{ .Site.Title }} - {{ block "body" . }}{{ .Page.Content }}{{ end }} + {{ block "body" . }}{{ .Page.Content | transform.Markdownify }}{{ end }} {{ 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. +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](../internal/templateutil/templateutil.go). 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. diff --git a/docs/README.ru.md b/docs/README.ru.md index 8856035..75e24eb 100644 --- a/docs/README.ru.md +++ b/docs/README.ru.md @@ -14,6 +14,7 @@ * `HOME_CONTENT_DIR` -- имя или путь директории в которой содержатся страницы и статика, по-умолчанию `content/`; * `HOME_HOST` -- IP-адрес на котором будет работать движок, по-умолчанию `0.0.0.0`; * `HOME_THEME_DIR` -- имя или путь директории в которой содержатся файлы шаблонов, по-умолчанию `theme/`; +* `HOME_STATIC_DIR` -- имя или путь директории в которой содержатся публично доступные файлы из любой части сайта "как есть", по-умолчанию `static/`; * `HOME_PORT` -- порт на котором будет работать движок, по-умолчанию `3000`; Конфигурация сайта и его страниц полностью обеспечивается через FrontMatter в Markdown-файлах находящиеся в `$HOME_CONTENT_DIR`. @@ -41,9 +42,14 @@ 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`; -* `$HOME_CONTENT_DIR/2023/11/09.md`: `/2023/11/09`, `/2023/11/09/`, `/2023/11/09/index.html` и `/2023/11/09.html`; +* `$HOME_CONTENT_DIR/folder/file.md`: + * `/folder/file` + * `/folder/file/` + * `/folder/file.html` +* `$HOME_CONTENT_DIR/now/index.md`: + * `/now` + * `/now/` + * `/now/index.html` * и так далее; Правила по локализациям здесь также применимы: `folder/file.ru.md` b `folder/file.en.md`, `now.jp.md`, `2023/11/09.de.md` и так далее. @@ -53,6 +59,7 @@ backlink: "https://mstdn.io/@toby3d" --- # Известные параметры: title: "Hello, World!" +description: "Demo page for demo" # Любые другие наборы ключей-значений будут восприниматься как второстепенные параметры и доступные через `.Page.Params`: style: @@ -67,7 +74,9 @@ contact: "hey@toby3d.me" This is a sample page content for demo. ``` -Статические файлы вроде изображений, видео, `robots.txt`, стилей, скриптов и чего-угодно ещё размещаются в `$HOME_CONTENT_DIR` как есть: в корень если они должны быть доступны глобально через `.Site.Files` и для домашних страниц, а также в нужных директориях со страницами для доступа к ним через `.Page.Files`. Формат и имена файлов ничем не ограничены. +Любые статические файлы могут быть размещены и опубликованы двумя способами: +* В `$HOME_STATIC_DIR` как публично доступная статика, без каких-либо ограничений "как есть", по тому же пути в котором файл расположен в директории; +* В `$HOME_CONTENT_DIR` рядом с нужной страницей: файл будет доступен в коллекциях `.Site.Resources` и `.Page.Resources` и ограничен настройками доступа родительской страницы; Для рендера содержимого страниц в браузерах необходимы шаблоны, которые должны размещаться в `$HOME_THEME_DIR`. Для работы необходим хотя бы один шаблон с блоком `baseof` который будет вызываться для каждой страницы, например: ```html @@ -75,7 +84,9 @@ This is a sample page content for demo. {{ define "baseof" }} - + + {{ .Site.Title }} - {{ block "body" . }}{{ .Page.Content }}{{ end }} + {{ block "body" . }}{{ .Page.Content | transform.Markdownify }}{{ end }} {{ end }} ``` -Шаблонизация работает по [инструкциям стандартного шаблонизатора Go](https://pkg.go.dev/html/template) с небольшими дополнениями в виде дополнительных утилит. В `$HOME_THEME_DIR` разрешена любая комбинация и иеархия шаблонов и их взаимосвязей до тех пор, пока существует `baseof` в качестве единого родительского блока. +Шаблонизация работает по [инструкциям стандартного шаблонизатора Go](https://pkg.go.dev/html/template) с небольшими дополнениями в виде [дополнительных утилит](../internal/templateutil/templateutil.go). В `$HOME_THEME_DIR` разрешена любая комбинация и иеархия шаблонов и их взаимосвязей до тех пор, пока существует `baseof` в качестве единого родительского блока. В качестве контекста в каждый шаблон пробрасываются две структуры: `.Site` с глобальными опциям из `$HOME_CONTENT_DIR/index.md` и текущая просматриваемая страница `.Page` с её опциями найденная в `$HOME_CONTENT_DIR`. Структуры данных в этих контекстах можно посмотреть в пакете [domains](../internal/domain), они используются в шаблонах как есть.