Release 0.0.1

.gitignore

@@ -5,5 +5,5 @@ build/
 node_modules/
 
 **/*.iml
-
+bundle/ui-bundle.zip
 

README.adoc

@@ -1,11 +1,11 @@
-= ProgTech Book
-:url-project: https://github.com/progtech-course/book/actions/workflows
+= DevTools Book
+:url-project: https://github.com/devtools-course/book/actions/workflows
 :workflow: site.yml
 :img-ci-status: {url-project}/{workflow}/badge.svg
 
 image:{img-ci-status}[CI Status]
 
-Материалы курса "Технологии Программирования".
+Материалы курса "Инструменты разработчика".
 
 Проект распространяется под лицензией link:LICENSE[MPL-2.0].
 

antora-playbook.yml

@@ -1,19 +1,30 @@
 site:
-  title: ProgTech Book
-  start_page: ptbook::index.adoc
+  title: DevTools Book
+  start_page: book::index.adoc
+
 content:
   sources:
     - url: .
       branches: [ '*' ]
 ui:
   bundle:
-    url: https://github.com/progtech-course/antora-ui/releases/download/latest/ui-bundle.zip
+    url: https://github.com/devtools-course/antora-ui/releases/download/latest/ui-bundle.zip
+#    url: /home/nbah/antora-ui-default/build/ui-bundle.zip
     snapshot: true
   supplemental_files: ./supplemental-ui
+
+asciidoc:
+  attributes:
+    experimental: ''
+    page-pagination: ''
+    allow-uri-read: ''
+  extensions:
+    - ./lib/remote-include-processor.js
+
 antora:
   extensions:
     - require: '@antora/lunr-extension'
       languages: [en, ru]
 
 #runtime:
-#  fetch: true
+#  fetch: true

antora.yml

@@ -1,5 +1,5 @@
-name: ptbook
-version: latest
-title: ProgTech Book
+name: book
+version: dev
+title: DevTools Book
 nav:
   - modules/ROOT/nav.adoc

lib/remote-include-processor.js

@@ -0,0 +1,68 @@
+'use strict'
+
+const { execFileSync } = require('node:child_process')
+const fs = require('node:fs')
+const { createHash } = require('node:crypto')
+
+/**
+ * An Asciidoctor include processor that handles remote (URL) includes. This version gets registered each time a
+ * document is loaded and is thus scoped to the document, which allows it to cache the contents of the URL for
+ * subsequent references. This extension relies on an internal API to look up and delegate to the default include
+ * processor once the URL is cached. It caches the URL in the ROOT component, so that component must be filtered
+ * out from the navigation in the UI template.
+ */
+function createExtensionGroup ({ contentCatalog }) {
+    return function () {
+        this.includeProcessor(function () {
+            this.prepend() // register in front of Antora's include processor
+            this.handles((target) => target.startsWith('https://') || target.startsWith('http://'))
+            this.process((doc, reader, target, attrs) => {
+                const cachedTarget = readUrl(contentCatalog, target)
+                if (cachedTarget === false) {
+                    const cursor = reader.$cursor_at_prev_line()
+                    const logMessage = doc.createLogMessage(`include uri not readable: ${target}`, { source_location: cursor })
+                    doc.getLogger().error(logMessage)
+                    reader.pushInclude(`Unresolved directive in ${reader.path} - include::${target}[]`, target, target, 1, attrs)
+                    return
+                }
+                const nextIncludeProcessor = findNextIncludeProcessor(doc, this, cachedTarget)
+                nextIncludeProcessor && nextIncludeProcessor.process_method['$[]'](doc, reader, cachedTarget, Opal.hash(attrs))
+            })
+        })
+    }
+}
+
+function readUrl (contentCatalog, url) {
+    contentCatalog.getComponentVersion('ROOT', '') || contentCatalog.registerComponentVersion('ROOT', '')
+    const src = { component: 'ROOT', version: '', module: 'cache', family: 'partial', relative: sha1(url) + '.adoc' }
+    let file = contentCatalog.getById(src)
+    if (!file) {
+        try {
+            file = contentCatalog.addFile({ contents: execFileSync('curl', ['--silent', '-L', url]), src })
+        } catch {
+            file = contentCatalog.addFile({ contents: null, src })
+        }
+    }
+    return file.contents == null ? false : 'ROOT:cache:partial$' + src.relative
+}
+
+function sha1 (string) {
+    const shasum = createHash('sha1')
+    shasum.update(string)
+    return shasum.digest('hex')
+}
+
+function findNextIncludeProcessor (doc, currentIncludeProcessor, target) {
+    let skip = true
+    return doc.getExtensions().$include_processors().find((candidate) => {
+        candidate = candidate.instance
+        if (skip) return candidate === currentIncludeProcessor ? (skip = false) : false
+        return candidate.handles(target)
+    })
+}
+
+module.exports.register = (registry, context) => {
+    const toProc = (fn) => Object.defineProperty(fn, '$$arity', { value: fn.length })
+    registry.$groups().$store('remote-include-processor', toProc(createExtensionGroup(context)))
+    return registry
+}

modules/ROOT/nav.adoc

@@ -1,4 +1,13 @@
-.Intro
+.О проекте
 * xref:authors.adoc[Авторы]
 * xref:code-of-conduct.adoc[Code of conduct]
+* xref:dev-guides.adoc[Гайды по разработке]
 
+.Linux FS
+* xref:linux/file-types.adoc[Типы файлов]
+* xref:linux/fhs.adoc[FHS]
+* xref:linux/devices.adoc[]
+* xref:linux/ttys.adoc[]
+
+.Packages & Archives
+* xref:utils/rpm.adoc[]

modules/ROOT/pages/authors.adoc

@@ -1,5 +1,5 @@
 = Авторы
-:page-pagination:
+:description: Авторы проекта
 
 Здесь можно найти информацию про людей, участвовавших в создании этого ресурса.
 

modules/ROOT/pages/code-of-conduct.adoc

@@ -1,5 +1,4 @@
 = Code of conduct
-:page-pagination:
 
 
 Все материалы на этом сайте являются открытыми и доступны всем. При их использовании ознакомьтесь с лицензией https://www.mozilla.org/en-US/MPL/2.0/[MPL-2.0], под которой распространяется проект.

modules/ROOT/pages/dev-guides.adoc

@@ -0,0 +1,90 @@
+= Как разрабатывать сайт
+:page-authors: Иван Калинин
+
+== Инструменты
+
+Для разработки вам потребуется:
+
+* `npm` -- можно установить через пакетный менеджер, например `apt install node` (обычно поставляется в пакете `node`)
+* IDE с плагином для asciidoctor
+** Для JetBrains IDE советую установить плагин https://plugins.jetbrains.com/plugin/7391-asciidoc
+
+Склонируйте проект и из его корня исполните:
+[,shell]
+----
+npm install
+----
+
+== Просмотр сайта
+
+Чтобы запустить сборку сайта исполните:
+[,shell]
+----
+npx antora --stacktrace antora-playbook.yml
+----
+Полученный сайт будет лежать в папке `build`. Однако, у него могут не отображаться иконки на блоках и на каждое изменение необходимо вручную пересобирать.
+
+
+Для динамического превью нужно использовать докер:
+[.wrap,shell]
+----
+docker run --rm -p 35729:35729 -p 2020:2020 -v "${PWD}":/preview/antora -v "${PWD}/bundle:/preview/bundles" ghcr.io/vshn/antora-preview --antora='.' --style=ui-bundle
+----
+
+NOTE: Для подгрузки стилей скачайте `ui-bundle.zip` из https://github.com/progtech-course/antora-ui/releases/tag/latest[проекта] и поместите в папку `bundle` в корне проекта.
+
+Сайт будет доступен на http://localhost:2020. Однако, уже тут не будет работать фавиконка и настройки UI.
+
+Подробнее об образе можно прочитать в https://github.com/vshn/antora-preview[репозитории проекта].
+
+== Настройка плейбука
+
+При локальной разработке советую использовать следующую модификацию `antora-playbook.yml`:
+[.wrap,yaml]
+----
+site:
+  title: ProgTech Book
+  start_page: ptbook::index.adoc
+content:
+  sources:
+    - url: .
+      branches: [ '*' ]
+ui:
+  bundle:
+    url: https://github.com/progtech-course/antora-ui/releases/download/latest/ui-bundle.zip
+    snapshot: true
+  supplemental_files: ./supplemental-ui
+antora:
+  extensions:
+    - require: '@antora/lunr-extension'
+      languages: [en, ru]
+
+# runtime:
+#   fetch: true
+----
+
+Изменения:
+
+. `url: .` -- используется локальный репо, а не исходники в гитхабе
+. `runtime: fetch: true` -- если обновился исходник с UI, то эта настройка перескачает его, иначе будет использоваться закэшированный
+
+WARNING: Не нужно это коммитить в репозиторий!
+
+== Возможности asciidoctor
+
+Посмотреть, как можно оформить материалы, можно на https://progtech-course.github.io/antora-ui[превью UI]. Исходники аскидоктора лежат https://github.com/progtech-course/antora-ui/blob/main/preview-src/index.adoc[здесь].
+
+Также поддерживается кастомная стилизация TODO:
+
+[.wrap,asciidoc]
+----
+// TODO
+[TIP.todo]
+====
+Нужна ссыль на mounting process
+====
+----
+
+CAUTION: При ее использовании просьба оставлять выше комментарий `// TODO` -- так IDE сможет трекать тудушки в проекте.
+
+При написании страницы добавляйте параметр `:description:` с кратким описанием, о чем написано на странице, а также указывайте себя в `:page-authors:`. При указании авторства пишите так же, как в заголовке xref:authors.adoc[authors.adoc] -- иначе не сработают автоматические ссылки.

modules/ROOT/pages/index.adoc

@@ -1,8 +1,7 @@
-= ProgTech Book
-// :page-authors: Иван Калинин
-:page-pagination:
+= DevTools Book
+:description: Материалы курса "Инструменты разработчика"
 
-Здесь собраны материалы курса "Технологии программирования".
+Здесь собраны материалы курса "Инструменты разработчика".
 
 image::crya.png[]