Преамбула #

В приложении Obsidiian есть встроенный сервис Publish, который позволяет создать свой сайт и публиковать заметки в интернете в один клик. Но у него есть как плюсы, так и минусы.

Плюсы:

• минимум настроек, всё работает из коробки;
• поддерживается весь основной функционал Обсидиана.

Минусы:

• он платный (и довольно дорогой);
• ограниченные возможности настройки сайта.

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

Этот мой сайт сделан совершенно бесплатно (я только заплатила сто рублей за домен, но даже это было необязательно). Он хостится на Github Pages и создан при помощи генератора статических сайтов Hugo. Но главное — новые страницы публикуются напрямую из Обсидиана, одной командой. В этой статье я расскажу, как можно сделать подобный сайт самостоятельно.

Общая информация #

Генерация сайта происходит в два этапа. Во-первых, нужно отправить заметку из Обсидиана в репозиторий на гитхабе. Во-вторых, добавленные Markdown-файлы нужно преобразовать в Html-страницы и собрать из них сайт. Для первого этапа нам понадобится установить плагин для Обсидиана Github Publisher. За второй будет отвечать специальный шаблон, который мы разместим в репозитории. Шаблон будет применяться автоматически каждый раз при добавлении нового файла.

Начать настройку сайта лучше всего с выбора шаблона. Шаблон — это набор правил, по которым кучка маркдаун-файлов преобразуется в сайт. Он определяет внешний вид и функционал сайта: расположение элементов, меню и иконки, стили, скрипты и т. п., а также правила, по которым синтаксис Markdown преобразуется в Html. В интернете можно найти огромное количество шаблонов для статических сайтов, но не все они поддерживают специфический синтаксис Обсидиана, поэтому лучше всего выбирать шаблон, специально заточенный под Обсидиан. Популярным вариантом является Quartz. Ещё можно попробовать Mkdocs или Amethyst. Мой сайт сделан на основе шаблона Amethyst, но его я не рекомендую, потому что он сильно устаревший, и мне пришлось его очень здорово переписать под себя. Может быть, когда-нибудь я напишу и опубликую документацию к собственному шаблону (пока что он сыроват).

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

Создание и настройка сайта на базе Quartz #

Установка шаблона на Github Pages #

Вот самый простой способ быстро создать сайт на базе Quartz:

• Зарегистрироваться на Github (если ещё нет аккаунта).
• Открыть репозиторий шаблона и нажать кнопку «Use this template». Создать новый публичный репозиторий.
• Переименовать ветку v4 в main.
• Отредактировать файл deploy.yml в папке .github/workflows, удалив строку token: ${{ secrets.GH_PAT }}.
• Перейти на страницу Settings —> Pages и выбрать Source —> Github Actions.
• Перейти на страницу Settings —> Environments — удалить все.
• В папке content создать файл index.md. Он обязательно должен содержать фронтмэттер со свойством title, содержащим заголовок для главной страницы.
• Снова перейти на страницу Settings —> Pages. Там появится ссылка на ваш новый сайт.

Настройка сайта #

Теперь для настройки сайта необходимо отредактировать файл quartz.config.ts. В нём нужно изменить следующие свойства:

• pageTitle — указать своё название сайта;
• locale — поменять на "ru-RU";
• baseUrl — здесь нужно указать свой адрес сайта (без "https://");
• theme — здесь можно заменить шрифты и цвета на какие вам хочется.

Дополнительно можно поменять внешний вид сайта:

• отредактировав файл quartz.layout.ts— можно поменять расположение элементов на сайте;
• отредактировав scss-файлы в папке quartz/styles.

Больше о настройках можно узнать в документации Quartz

Для добавления новых страниц на сайт Markdown-файлы должны добавляться в папку content. При этом каждый Markdown-файл должен как минимум содержать свойство title. Далее мы настроим, чтобы эти файлы туда добавлялись автоматически из Обсидиана.

Локальная копия сайта #

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

Чтобы запустить локальную копию сайта для отладки:

• Установите Git.
• Установите Node (после установки требуется перезагрузить компьютер).
• В своём репозитории скопируйте адрес для клонирования (Code —> HTTPS —> копировать)
• Откройте терминал и введите команду:

git clone <скопированный адрес>

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

cd <название скопированной папки>
npx quartz build --serve

Эта команда запускает сайт на локальном сервере. В браузере откройте адрес http://localhost:8080/. Это локальная версия сайта, где будут сразу отображаться все изменения, которые вы сделаете в скопированных файлах.

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

git add --a
git commit -m "My cool new changes"
git push origin main

Собственный домен #

По умолчанию адрес сайта на Github Pages отображается в формате <имя аккаунта>.github.io/<название репозитория>, но если вы хотите адрес покрасивее, то можно купить и настроить свой собственный домен. Как это сделать, я рассказывать не буду, потому что нашла очень доступную и внятную статью об этом.

Настройка Gihub Publisher #

Теперь, когда сайт готов, нужно добавить возможность публиковать новые страницы напрямую из Обсидиана. Для этого нужно будет настроить в Обсидиане плагин Gihub Publisher.

• Установливаем плагин
• На гитхабе переходим на страницу Settings — Developer settings — Personal access tokens — Fine-grained tokens — Generate new token. Придумываем название токена, указываем продолжительность действия и репозитории, к которым он применяется (лучше указать только репозиторий сайта). Затем указываем разрешения для репозитория. Их очень много, и они непонятные, поэтому лично я просто выставляю максимальные разрешения на всё. После генерации токен обязательно нужно где-то сохранить, потому что второй раз вам его не покажут.
• Открываем настройки Github Publisher и указываем следующие данные:
  • Вкладка Github config:
    • Имя своего аккаунта на гитхабе.
    • Название репозитория.
    • Токен.
  • Вкладка File paths:
    • Default folder — content.
    • Root folder — content.
  • Вкладка Content:
    • Internals links — да.
    • Convert internal links pointing to unpublished notes — да.
    • Wikilinks to MDlinks — нет.
  • Attachment & embeds:
    • Send linked files — нет.
    • Transfer attachments — да. Остальные настройки указываются по желанию. Дополнительно о возможностях плагина можно почитать в документации.

Публикация заметок #

Теперь можно публиковать заметки. Нужно создать заметку и добавить к ней свойство share: true, а также свойство title для заголовка. Можно добавить и другие свойства (в соответствии с настройками плагина и встроенными свойствами, указанными в документации Quartz), но эти обязательные. После этого в палитре команд вызываем команду Upload single current active note.

Если всё настроено правильно, то появится сообщение, что заметка опубликована. Для проверки можно зайти в репозиторий и убедиться, что заметка добавилась в папку content. Обычно после этого нужно с полминуты подождать прежде чем страница отобразится на сайте.

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

Заключение #

Надеюсь, это будет кому-нибудь полезно! Я сама не использую Quartz, потому что узнала о нём только после того, как практически написала собственный шаблон на Hugo, но я его тестировала, и он выглядит очень неплохо. Вдобавок, по тому же принципу можно настроить любой другой шаблон, будь то Hugo, Jekyll и так далее. Я перепробовала несколько разных вариантов, и, когда усвоишь общую идею, разница невелика.

Я сама не очень-то программист, и мне пришлось местами поломать голову, разбираясь во всех нюансах настройки, несмотря на наличие документации. Поэтому я постаралась расписать весь процесс максимально подробно, но при этом не вдаваясь в лишние дебри, чтобы инструкция была понятна даже людям, не слишком разбирающимся в гитхабе и прочих технологиях.