Создание статических сайтов из Markdown без HTML (pandoc, mkdocs, hugo и jekyll)04.07.2024 12:30

Всем привет! На протяжении нескольких лет практики написания скриптов на PowerShell, я веду заметки преимущественно связанные с данным языком и периодически фиксирую их в своем репозитории на GitHub (за последние несколько месяцев добавил достаточно много новых пример, в том числе шпаргалку по работе с командами Docker), чтобы всегда можно было к ним обратиться с рабочего компьютера через Интернет. Недавно задумался, почему бы не попробовать создать из файла в формате Markdown статический сайт, который можно очень просто, и главное бесплатно разместить на том же GitHub, особенно это стало актуально с тех пор, когда количество строк документа перевалило за 6 тысяч и на главной странице с описанием проекта весь объем документа уже не умещается, а используя приложение на Andrioid вовсе отображается пустая страница (хотя, достаточно разбить документ на несколько, что в будущем я и сделал для сайта). У меня нет опыта создания полноценных сайтов (за исключением конструкторов), и такой вариант я даже не рассматривал, язык описания README файлов очень даже подходит для оформления страницы, например, он также используется на Habr для написания статей, а в новом редакторе еще и в автоматизированном формате. Синтаксис написания у этого языка разметки очень простой, а по сравнению с HTML более компактный и читабельный (хотя, тут дело привычки). Можно найти много мануалов, например, статья на Хабр, или воспользоваться специализированными инструментами, предназначенными для редактирования Markdown документов, в котором описание не будет отличаться от редактирования документа Word, такой как MarkText. Еще существуют специальные плагины, например, Markdown Preview для Visual Studio Code, где по мимо подцветки синтаксиса, можно выбрать тему отображения, вывести структуру документа в формате меню, появляется возможность сразу наблюдать конечный результат и прямо на странице вносить свои изменения, сохраняя их в исходный файл или экспортировать в другие форматы. Также данный язык разметки все чаще используется для создания заметок, например в BoostNote, AppFlowy и Obsidian Notes, для последнего также есть несколько плагинов, упрощений работу с Markdown, например, редактор таблиц Advanced Tables.

Во всех примерах, я использовал стандартный файл README.md, который применяется для описания любого репозитория на GitHub. Когда у вас будет оформлен такой документ, его необходимо конвертировать в формат HTML, или собрать на его основе статический сайт с помощью специальных инструментов, далее, речь пойдет именно про них. Данная статья будет скорее кратким обзором, чем сравнением, и так как в этом деле я новичок, то расскажу про полезные инструменты, которые использовал в процессе изучения данной темы и нюансы, с которыми столкнулся.

Pandoc

Изначально, когда мне пришла идея создания Web-страницы, я вспомнил про Pandoc, т.к. ранее им неоднократно пользовался для конвертации файлов разных форматов (из одного в другой), чаще для документов Word (docx), pdf и epub. Это не типичный инструмент для решения данной задачи, но как мне кажется, это может быть полезно для понимания базовых основ. Для установки данного инструмента можно загрузить пакет из репозитория GitHub или воспользоваться менеджером пакетов Chocolaty:

choco install pandoc

Теперь, достаточно воспользоваться всего одной командой в консоли, чтобы создать из вашего Markdown файла документ, в формате HTML:

# Переходим в директорию, в которой находится ваш файл в формате Markdown
cd ~\Documents\Git\PS-Commands
# Конвертируем
pandoc -s README.md -o index.html

Используя данный инструмент, неважно в каком формате оформлен ваш исходный документ, вы можете использовать Word, после чего конвертировать его в формат Markdown или сразу в HTML, например так:

# Конвертируем документ Word в формат Markdown
pandoc -s word-for-markdown.docx -o index.md
# Конвертируем документ Word в формат HTML
pandoc -s word-for-markdown.docx -o index.html

В самом же Markdown файле, с помощью заголовков разных уровней (используя от 1 до 5 символов sharp (#) в начале строки) можно создать кликабельное меню документа, вот пример:

Меню:

- [Описание](#описание)
- [Информация](#информация)

# Описание
Текст описания

# Информация
Текст информации

По умолчанию, Pandoc будет накладывать стандартные стили CSS внутри HTML документа (содержимое блока ), который вы можете отредактировать самостоятельно, например, настроить темную тему документа, а если вы используете VSCode, то прямо в редакторе кода вы можете визуально изменить цвет любого элемента из представленной палитры цветов RGB:

Задаем цвет в стилях HTML документа через VSCode.

Также можно добавить немного интерактивности с помощью JavaScript. Если у вас большой документ, то будет полезно иметь кнопку прокрутки страницы, которая будет поднимать нас на самый вверх документа без ручного пролистывания. Открываем созданный index.html, где следом за блоком стилей создаем кнопку scroll-to-top и добавляем для нее JavaScript код внутрь блока :

↑

Внутри блока добавляем для созданной кнопки стиль:

    /* Стили для кнопки "наверх" */
    .scroll-to-top {
        position: fixed;
        bottom: 20px;
        right: 20px;
        background-color: #007bff;
        color: #fff;
        border: none;
        border-radius: 50%;
        width: 50px;
        height: 50px;
        font-size: 24px;
        cursor: pointer;
        display: none; /* Кнопка скрыта изначально */
        z-index: 1000; /* Отображение поверх других элементов */
    }

    .scroll-to-top:hover {
        background-color: #0056b3; /* Изменение цвета при наведении */
    }

Созданный документ можно открыть в любом браузере, например Google Chrome (достаточно просто перетащить документ в окно браузера) и просмотреть получившийся результат:

Меню HTML документа (в правом углу созданная кнопка для прокрутки страницы).

Таким образом можно добавить ряд других функций, например, кнопку копирования внутри блоков кода, конечный пример вы можете найти в ветке pandoc-solarized исходного репозитория. Pandoc не является единственным способом, как можно конвертировать Markdown в HTML, например, можно воспользоваться встроенным командлетом PowerShell ConvertFrom-Markdown, забрать содержимое в формате html и обернуть в стандартные тэги для чтения документа в браузере, вот пример того, как это можно сделать:

function Get-MarkdownToHtml {
    param (
        [Parameter(Mandatory = $true,ValueFromPipeline = $true)]$Markdown
    )
    $html = $(Get-Content index.md -Raw | ConvertFrom-Markdown).html
    @"
        
        
        
        
        
        $html
        











        
        "@
}

Get-Content README.md -Raw | Get-MarkdownToHtml | Out-File README.html

Хотя PowerShell не добавляет стили, результат преобразования тэгов будет аналогичным. Если исходный документ оформлен правильно, все должно получиться с первого раза, теперь такой документ можно опубликовать на GitHub (предварительно нужно создать аккаунт, если у вас его еще нет). Для создаваемого сайта имя вашего пользователя будет выступать в роли доменного имени 3-его уровня относительно github.io, например так: lifailon.github.io. Публикуем index.html в корне созданного репозитория (например, username.github.io), в настройках репозитория на вкладке Pages указываем источником Deploy from a branch и задаем ветку (по умолчанию, main). Процесс сборки и публикации выполняется автоматически, и в дальнейшем будет запускаться каждый раз, когда будет происходить commit в указанной ветке.

Безусловно это не полноценный сайт, у него нет структуры, тем не менее, если вам достаточно встроенного функционала Markdown или нужна статическая страница для формирования автоматических отчетов, то это может быть вполне неплохим решением. У меня есть простой пример, который формирует Markdown документ со списком игр и бесплатных раздач в магазине Epic Games (на текущий момент автоматическая сборка отключена, но вы можете сделать fork и самостоятельно запустить его), после чего этот документ конвертируется в HTML для публикации на статический странице по url-пути с наименованием данного репозитория, выглядит это так: https://lifailon.github.io/epic-games-radar, где epic-games-radar название вашего репозитория, на который можно создать ссылку в меню вашего основного сайта. Весь процесс автоматизирован с помощью GitHub Actions, который самостоятельно выполняет скрипт и обновляет репозиторий, после чего автоматически запускается процесс обновления Веб-страницы.

Mkdocs

В отличии от Pandoc, данный инструмент целенаправленно предназначен для генерации статических сайтов на основе файлов Markdown с целью создания проектной документации. Mkdocs написан на языке Python, как и другие инструменты в данной статье имеет открытый исходный код. Устанавливается данный инструмент в одну строку (предварительно в системе должен быть установлен Python и менеджер пакетов pip, который идет в составе с интерпретатором), а настраивается с помощью одного файла конфигурации с использованием языка разметки YAML.

# Устанавливаем mkdocs в системе через менеджер пакетов:
pip install mkdocs

После установки, инструмент будет доступен как любая другая утилита командной строки. Создаем проект, в котором будут находиться файлы, формирующие будущую структуру сайта:

mkdocs new lifailon.github.io.mkdocs
cd lifailon.github.io.mkdocs

Внутри директории проекта будет создан файл mkdocs.yml для настройки структуры сайта и директория docs, где по умолчанию располагается файл index.md, его содержимое будет отображаться на главной странице сайта, в него и копируем содержимое своего Markdown документа. Вот простой пример настройки:

site_name: PowerShell Commands
site_url: https://lifailon.github.io
nav:
  - PowerShell: index.md
  - Help: help.md
markdown_extensions:
  - markdown.extensions.nl2br

Запустим сервер, чтобы отобразить содержимое сайта:

mkdocs serve

После запуска, все внесённые изменения в файл index.md будут сразу отображаться на странице вашего браузера. Переходим в браузер и открываем наш сайт, по умолчанию, адрес на котором будет запущен сервер http://127.0.0.1:8000 (он также отображается в консоли).

Пример статической странице в MkDocs по умолчанию.

Слева автоматически создается меню из заголовков 1-го уровня в формате кнопок, которое закреплено при навигации по странице, но при этом отображается только то количество заголовков, которое умещается в окне браузера, а при пролистывании страницы они остаются на месте, и если у вас больше двух десятков таких заголовков, лучшим решением будет разбить один документ на несколько. Если в структуре сайта будет больше, чем один документ (которые в конфигурации перечислены в параметре nav:), то вверху страницы (в шапке, справа от заголовка) также добавляется меню кнопок для навигации между страницами сайта. В примере я использовал названия PowerShell для главной страницы и Help для перехода к документу help.md в корне директории docs, но также возможно использовать директории, и любые названия дочерних файлов Markdown, указав в конфигурации новый путь (например, New Page: DirectoryName\index.md).

По умолчанию, в Markdown при наборе обычного текста если мы делаем переход на новую строку используя кнопку Enter, то этот перенос не будет отображен на странице (за исключением параграфов, где используется отступ через одну пустую строку, т.е. Enter дважды), для этого необходимо в конце предыдущей строки добавить символ обратного слэша (\). При отображении документа в mkdocs такой перенос не происходит, по этой причине в конфигурационном файле было включено расширение markdown.extensions.nl2br, которое автоматически делает этот перенос, если он был использован в исходном документе, но, при этом, если использовался символ \, то он останется на старице, и к сожалению, от него можно будет избавиться только путём удаления, например, с помощью парсинга страницы. Для решения такой проблемы, я воспользовался простым скриптом PowerShell, который удаляет символ \ в конце каждой строки во всех дочерних документах, начиная с директории docs:

$docs = "$home\documents\lifailon.github.io.mkdocs\docs"
function Get-ReplaceSlash {
    param (
        [string]$directory
    )
    Get-ChildItem -Path $directory -Recurse -Filter *.md | ForEach-Object {
        $file = $_.FullName
        (Get-Content $file) -replace '\\$', '' | Set-Content $file
    }
    Get-ChildItem -Path $directory -Directory | ForEach-Object {
        Get-ReplaceSlash $_.FullName
    }
}

Get-ReplaceSlash $docs

Что бы произвести обратный процесс (если ваш исходный документ не содержал обратный слэш в конце каждой строки для автоматического переноса), вы можете воспользоваться упомянутым выше инструментом pandoc, и придать исходному документу синтаксически »правильный» вид. Это может пригодиться в том случае, если вы изначально оформляли документ для mkdocs и хотите использовать его на другом движке или платформе, например, на странице GitHub или Wiki.

pandoc input.md -f markdown+hard_line_breaks -o output.md

Из интересных преимуществ такого решения, очень хорошо реализован поиск по всем страницам содержимого сайта:

Поиск в MkDocs.

Также существуют несколько других тем, которые можно установить с помощью pip:

pip install mkdocs-theme-bootstrap4
pip install mkdocs-material

И в конфигурационном файле явно указать название темы (перезапускать сервер для этого не обязательно):

theme: material
#theme: bootstrap4
#theme: readthedocs

В ряду визуальных изменений, также обновляется поиск и меню, например, в теме bootstrap4 в меню добавляются заголовки 3-го уровня, а в material слева располагается меню для перехода между разными документами, а справа меню из заголовков (включая дочерние), при этом появляется возможность пролистывать такое меню отдельно от основного документа, а также результаты поиска отображаются куда приятнее, искомое слово подсвечивается и результат выглядит более читаемым.

Поиск в MkDocs с использованием темы Matreial.

Для темы Material возможно добавить параметры, оперируя функциями внутри конфигурационного файла, например, добавить кнопку копирования в блоках кода, или переключение между темной и светлой темой. Для этого необходимо обновить соответствующие настройки в своей конфигурации, вот пример, который добавит кнопку переключения темы (слева от окна поиска):

theme:
  name: material
  features:
    - content.code.copy
  palette:
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference
    - media: "(prefers-color-scheme: light)"
      scheme: default 
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

Любопытно, что проект с темой Material на GitHub смог обогнать по количеству звезд исходный репозиторий проекта Mkdocs, а среди спонсоров проекта является известный FastAPI Framework для Python, сайт с документацией которого базируется как раз на теме Material, он также поддерживает несколько языков, в том числе русский и может служить хорошим наглядным примером реализации.

Если вам необходимо заменить copyright в нижней части сайта или внести другие изменения дизайна, относящиеся непосредственно к теме, необходимо изучить файлы проекта mkdocs-material, или просто воспользоваться поиском. Для решения такой задачи идеально подойдем инструмент Everything, который производит мгновенный поиск в операционной системе Windows. Для начала, нужно определить, где установлена тема в системе, чтобы отфильтровать поиск по содержимому дочерних файлов, ограничив дальнейший поиск корневым каталогом с темой. После чего, с помощью Everything или любого другого привычно инструмента (например, NotePad++ или Double Commander) для поиска по содержимому файлов ищем по ключевому словосочетанию »Made with» (которое берем со страницы сайта) внутри содержимого всех дочерних файлов. Для Everything я использовал такую конструкцию:

*python*material* AND content:"Made with"

У меня получилось найти одно совпадение: C:\Users\Lifailon\AppData\Local\Programs\Python\Python312\Lib\site-packages\material\templates\partials\copyright.html

Вот измененный пример содержимого:

{#-
  This file was automatically generated - do not edit
-#}

  {% if config.copyright %}
    

      {{ config.copyright }}
    
  {% endif %}
  {% if not config.extra.generator == false %}
  PowerShell Commands on
  
    GitHub
  
  | Theme
  
    Material
  
  for
  
    MkDocs
  
  {% endif %}

Для того, чтобы отобразить изменения, которые были внесены в саму тему, необходимо перезапустить Web-сервер.

Пример сайта с использованием темы mkdocs-material и обновленным copyright.

Когда мы определились с темой и наполнили сайт достаточным количеством контента, остается произвести сборку, для этого используется следующая команда:

mkdocs build

По результатам выполнения будет создана директория site, где будут находиться все необходимые файлы для публикации на GitHub. Вы можете предварительно открыть файл index.html в своем браузере, и проверить его работоспособность, т.к. сайт не требует специального движка для своей работы, весь функционал будет корректно отображаться локально. Вы можете ознакомиться с рабочим примером такого сайта (исходник сборки опубликован на GitHub).

Hugo

Hugo, как и другие подобные инструменты похож на Mkdocs, написан на языке Golang и является полноценным фреймворком для создания веб-сайтов, он функциональнее и гибче в настройке, а количество тем насчитывает несколько сотен, где каждая тема это проект, который создан сообществом. Для установки в системе Windows можно использовать один из трех популярных менеджеров пакетов:

winget install Hugo.Hugo.Extended

choco install hugo-extended

scoop install hugo-extended

Или загрузить исполняемый файл из репозитория GitHub в директорию system32 (такой способ установки является универсальным и для меня он привыченее, нежели использовать классический установщик msi или exe), что позволит использовать утилиту не зависимо от текущего расположения в консоли:

$user = "gohugoio"
$repository = "hugo"
$release_latest = Invoke-RestMethod "https://api.github.com/repos/$($user)/$($repository)/releases/latest"
$url = $($release_latest.assets | Where-Object name -match "hugo_extended_[\d.]+_windows-amd64\.zip").browser_download_url
Invoke-RestMethod $url -OutFile $home\Downloads\hugo.zip
Expand-Archive -Path "$home\Downloads\hugo.zip" -DestinationPath "$home\Downloads\hugo\"
Copy-Item -Path "$home\Downloads\hugo\hugo.exe" -Destination "C:\Windows\System32\hugo.exe"
Remove-Item "$home\Downloads\hugo*" -Force -Recurse

Для начала работы с Hugo необходимо определиться с темой, так как стало актуально использовать темные темы, мне приглянулась dark-theme-editor. Устанавливаем:

# Создаем и инициализируем новый проект (сайт)
hugo new site lifailon.github.io.hugo
cd lifailon.github.io.hugo
# Инициализируем пустой репозиторий Git для темы
git init
# Добавляем тему в проект
git submodule add -f https://github.com/JingWangTW/dark-theme-editor.git themes/dark-theme-editor
# Добавляем название темы в конфигурацию (можно и руками, все равно редактировать)
echo 'theme = "dark-theme-editor"' >> hugo.toml

Процесс инициализации сайта и добавления темы всегда одинаков, вы можете клонировать тему из репозитория с помощью git clone (если поддерживается, в зависимости от указанного в документации) или добавить ее в своей проект как подмодуль из примера выше. Все файлы Markdown хранятся в директории content, внутри которой необходимо структурировать каждый файл в своей директории. Например, создаем директорию Database, а внутри нее уже создаем файл index.md с содержимым темы по базам данных. Если необходима вложенность, то сначала создаем директорию Database, внутри нее еще одну директорию MySQL, и в свою очередь внутри директории MySQL добавляем файл index.md, т.е. внутри директории Database должны находиться только дочерние директории, и отсутствовать файл индекса.

Вначале каждого файла index.md необходимо указать информацию, такую как наименование страницы (именно это название и будет отображаться в меню), дату публикации и имя автора, а также возможно добавить дополнительные параметры, такие как категории и тэги.

---
title: "InfluxDB"
author: "Lifailon"
date: "2024-03-14T03:00:00+03:00"
categories: ["Database"]
tags: ["REST API"]
---

Для настройки сайта используется конфигурационный файл hugo.toml, который находится в корне проекта.

В предыдущих версиях файл конфигурации имел название config.toml, по этой причине во многих старых темах (которые уже не обновляются) все еще можно встретить это название.

На выбор можно использовать один из трех языков разметки: toml, yamlили json, на официальном сайте присутствует понятная документация с примерами на всех трех языках. Исходя из просмотренных мною нескольких десятков репозиториев с темами, чаще всего для описания темы используется TOML. Настройка параметров может отличаться, и обычно зависит от используемый темы, поэтому придется ознакомиться с приложенной документацией к проекту. Приведу пример конфигурации для выбранной мною темы, где добавил свои комментарии:

baseURL = "https://lifailon.github.io"
languageCode = "en-us"
title = "PS-Commands"
theme = "dark-theme-editor"

[params]

[params.header]
# Заголовок сайта (указывается в шапке, теме и наименование вкладки главной страницы)
title = "Lifailon.GitHub.io"
# Описание на главное странице
subtitle = "Большая база заметок PowerShell на русском языке."

# Логотип
[params.header.logo]
imgUrl = ""
logoLink = ""
# Фавикон
[params.site]
faviconUrl = ""
# URL путь до изображений используется относительно корня директории (/) вашего проект

# Описание параметров нижнего колонтитула
[params.footer]
copyrightStr = "GitHub"
counter = false # Оторажать количество странц (index файлов)
language = false # Отображать текущий язык (en)
hugoVersion = true # Отображать текущую версию сборки hugo
theme = true # Отображать название темы (при нажатии переадресует на репозиторий GitHub)
modifiedTime = true # Отображать последнюю дату внесенных изменений 
dateFormat = "Jan 02 2006" # Формат отображаемой даты
gitHash = false

# Ссылки на социальные сети (отображается соответствующая иконка в левом углу, если параметр не пустой)
[params.footer.socialLink]
github = "https://github.com/Lifailon"
email = ""
telegram = ""
youtube = ""
instagram = ""
facebook = ""
twitter = ""
linkedin = ""
medium = ""
vimeo = ""

# Наименование автора, отображается в левом нижнем углу
[params.globalFrontmatter]
author = "Lifailon"

# Описание главное страницы
[params.homePage]
siteLongDescriptionTitle = "PowerShell Commands"
siteLongDescription = "Структура языка, синтаксис командлетов и модулей, работа с системными и внешними утилитами, платформой .NET, различными сервисами через REST API, а так же системами AD, Exchange, Hyper-V, VMWare, базами данных и т.д."
showRecentPostsBlock = false # Отображать последние добавленные посты на главной страницы
numOfRecentPosts = 5 # Количество отображамых постов
recentPostShowUrl = false # Отображать путь рядом с постами

# Настройки страницы постов (Markdown)
[params.page]
includeToc = true # Отображать меню для навигации по странице (создается автоматически из заголовков)
showAuthor = true # Отображать автора страницы
showDate = true # Отображать дату публикации
dateFormat = "Jan 02 2006" # Формат отображаемой даты
showTimeToRead = true # Отображать время на чтение статьи в минутах
showBreadcrumb = true # Отображать путь к странице в меню сверху (Home / Databases / InfluxDB)
codeBlockCopible = true # Добавить кнопку копирования для блока кода

В приведенной конфигурации используются не все параметры, с остальными можно ознакомиться в исходной документации с комментариями автора (в основной ветки main). Чаще всего исходники (файлы до сборки, где присутствуют файлы Markdown) публикуются в отдельной ветке, для темы dark-theme-editor это example-site. По мимо базовых настроек, можно реализовать перевод на другие языки, и переключаться между ними прямиком на сайте. В исходной конфигурации вы можете ознакомиться со структурой такой настройки в блоке [languages], внутри которого присутствует описание для каждого дочернего параметра (например, [languages.en] и languages.zh), что бы это работало, вам необходимо подготовить несколько index файлов на соответствующих языках (например, index.en.md и index.zh.md) для каждого поста и разместить их рядом, внутри своих директории.

На сайте с темой dark-theme-editor лаконично подана информация с примерами синтаксиса Markdown, что может стать отличной шпаргалкой.

Если вам привычнее использовать json или yaml для описания настроек, не обязательно переписывать конфигурацию вручную, можно конвертировать документ, например, с помощью PowerShell:

# Устанавливаем PowerShell модуль для чтения TOML (PSToml) или YAML (PSYaml)
Install-Module -Name PSToml -Scope CurrentUser
# Читаем содержимое конфигурации в формате TOML
$toml = Get-Content "$home\documents\lifailon.github.io.hugo\hugo.toml"
# Конвертируем TOML в JSON
$json = ConvertFrom-Toml $toml | ConvertTo-Json -Depth 3
# Сохраняем конфигурационный файл в формате JSON
$json | Out-File "$home\documents\lifailon.github.io.hugo\hugo.json"

После конвертации необходимо удалить или переименовать файл конфигурации в формате TOML (т.к. он имеет выше приоритет), при этом сервер перезапускать не нужно.

Что бы запустить веб-сервер с проектом, используйте следующую команду:

hugo server

Идем в браузер по адресу http://localhost:1313

Пример главной страницы сайт с использованием темной темы в Hogu.

Для сборки сайта используется команда hugo без параметров, которая создаст папку public с готовыми файлами сайта для развертывания. Если необходимо локально проверить получившийся результат перед публикацией, то просто открыть index.html как статический документ в браузере не получится, так как для доступа будет использоваться протокол file://, что вызывает проблемы с обработкой относительных путей, и как следствие, загрузкой ресурсов (скриптов, стилей, изображений и других файлов). Для таких целей удобнее всего использовать специальные расширения, например, Live Preview в VSCode, которое в процессе своей работы запускает локальный сервер (на базе Express) на порту 3000.

Расширение предпросмотра HTML в режиме реального времени для VSCode.

Хотя данное решение мне понравилось больше всего, отображение страницы при чтении с телефона требует оптимизации, текст в блоках кода выходит за рамки окна и может отображается некорректно.

Отображение блоков кода на сайте с использование Hugo.

Пример такой сборки вы можете найти в ветке hugo-dark исходного репозитория.

Я попробовал с десяток разных тем, переключаться между ними достаточно просто, а также много у кого можно встретить demo версию, которая чаще всего запущена через GitHub Page. Хотя визуальная часть всегда меняется, движок остается тем же, но есть несколько интересных тем, которые кардинально отличаются от остальных, это Blowfish (за счет интерактивности слегка перегружен) и DocuAPI. Последний используется для описания документации вашего API, с поддержкой примеров для разных языков программирования, выглядит современно, и к сожалению, даже такой простой реализации описания не хватает очень многим крупным проектам.

В скором будущем планирую сделать пример такой документации на базе DocuAPI для одного из своих проектов, и здесь оставлю ссылку на этот пример.

Jekyll

Jekyll — это простой генератор статических сайтов с поддержкой блогов, написанный на языке Ruby. Как сказано на странице исходного репозитория — это файловая CSM система без сложностей, и такая формулировка идеально описывает эту систему. Основой таких сайтов являются документы Markdown и Liquid, последний расширяет возможности Markdown с помощью объектов, тэгов и фильтров для отображения динамического контента, т.е. можно использовать привычные в языках программирования переменные и условия. Данный проект поддерживается площадкой GitHub, и он же является рекомендуемым движком для развертывания страницы. Для работы с данным инструментом, необходимо будет установить среду Ruby, которая необходима для работы Jekyll. В системе Windows можно воспользоваться менеджером пакетов chocolatey или скачать и запустить пакет RubyInstaller. Процесс настройки и сборки аналогичен предыдущим вариантам, так что вкратце, вот набор команд:

# Устанавливаем Jekyll, используя систему управления пакетами gem
gem install Jekyll
# Создаем новый (пустой) проект
jekyll new lifailon.github.io.jekyll
cd lifailon.github.io.jekyll
# Копируем Markdown документ в директорию постов (_posts)
cp "$home\Documents\Git\PS-Commands\README.md" "_posts/2024-04-15-PowerShell-Commands.md"
# Запускаем сервер (http://localhost:4000)
bundle exec jekyll serve

После сборки сайта с помощью команды jekyll build, файлы для публикации будут сгенерированы в директорию _site.

По умолчанию (без излишних настроек в конфигурации) выглядит достаточно голо:

Пример главной страницы с использованием Jekyll.

Есть и другой вариант, что бы упростить процесс создания сайта с использованием данной системы, был создан проект Jekyll Now, который сводит процесс настройки к минимуму. Существует отличный мануал для быстрого запуска, описанный в статье (тут перевод на русский язык) еще от 2014 года, где также можно ознакомиться со структурой директорий проекта. По сути, это тема (готовый шаблон), которую мы копируем и на базе нее собираем сайт. Алгоритм простой, клонируем репозиторий через git clone https://github.com/barryclark/jekyll-now, добавляем в директорию с постами свои Markdown документы и запустить сборку. Важный момент, каждый документ должен иметь название такого вида: год-месяц-день-название.md (например, 2024–04–15-Powershell-Commands.md), это наименование будет выступать в роли url-пути относительно доменного имени (http://127.0.0.1:4000/2024/04/15/Powershell-Commands.html). Также в шапке каждого документа необходимо задать принадлежность и название статьи, которое будет отображаться на сайте:

---
layout: post
title: Пост от 15 марта
---

После запуска сервера командой jekyll serve этот документ отобразится в списке на главной странице, и будет иметь приоритет при сортировке, согласно указанной дате (сверху новые). По такому же принципу вы можете отредактировать файл about.md, который располагается в верхнем меню. В конфигурационном файле _config.yml возможно настроить аватар, имя, описание, задать ссылки на социальные сети и прочие настройки, все по аналогии с Hugo, вот базовый пример:

name: Lifailon
description: Мой блог
avatar: https://avatars.githubusercontent.com/u/116945542?s=400&u=a0265b8aff463b2b6814705dffc04894954d0a59&v=4
footer-links:
  dribbble:
  email:
  facebook:
  flickr:
  github: Lifailon/PS-Commands
  instagram: test
  linkedin:
  pinterest:
  rss:
  twitter:
  stackoverflow:
  youtube:
  googleplus:
disqus:
google_analytics:
url: https://lifailon.github.io
# Если вы размещаете свой сайт в репозитории проекта на страницах GitHub (http://yourusername.github.io/repository-name)
# и НЕ в пользовательском репозитории (http://yourusername.github.io), тогда добавьте сюда baseurl, например: "/repository-name"
baseurl: ""

Если вы уже используете аватар на сайте GitHub, его можно указать в своей конфигурации (для этого достаточно нажать на него правой кнопкой маши и скопировать URL-адрес картинки). Содержимое главной страницы может выглядит примерно так:

Пример главной страницы блога с использованием Jekyll Now.

Из перечисленных инструментов мне понравился меньше всего, так как такое решение больше подходит для блога, нежели документации, интерфейс выглядит достаточно простым и устаревшим, а по сравнению с темами Hugo настроек поменьше.

Заключение

Существуют и другие генераторы статических сайтов с открытым исходным кодом, например, Gatsby, созданный на базе Node.js с использованием React и GraphQL, про который есть отличная статья на Хабр. Если нужен какой-то итог, то правильнее cделать его самостоятельно, пробуя различные решения и подбирая темы, которые вы сможете настроить под себя. Мне же хотелось продемонстрировать такие решения и подчеркнуть нюансы, с которыми столкнулся, т.к. для меня это был совершенно новый и интересный опыт. Лично для себя, я остановился на MkDocs с темой Material.

© Habrahabr.ru