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

Так что вы заинтересованы в создании собственной темы для Discourse? Вы попали в нужное место :smile:

Это руководство будет больше сосредоточено на аспектах SCSS/CSS при работе с темами в Discourse. Если вы также знакомы с JS/EmberJs/Handlebars, вы можете углубиться в изучение, обратившись к этому руководству.

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

Подготовка к созданию тем

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

Чтобы максимально эффективно работать с темами в Discourse, я рекомендую настроить следующее, чтобы обеспечить вам самый быстрый и бесшовный процесс дизайна. Эти шаги позволят вам видеть изменения по мере их внесения, без необходимости нажимать «Сохранить» и обновлять страницу из админ-панели сайта Discourse.

Полностью возможно пройти это руководство, используя консоль администратора (при условии, что у вас есть доступ уровня администратора к форуму Discourse.)

  • Установите Discourse Theme CLI и прочитайте эту тему, чтобы понять, что он может делать.
  • Получите API-ключ с https://discourse.theme-creator.io/
    • Войдите с помощью вашей учетной записи Meta
    • Нажмите на Мои темы
    • Нажмите на API-ключ
    • В всплывающем окне нажмите Сгенерировать API-ключ и скопируйте сгенерированный для вас ключ (мы используем его чуть позже)

Запуск Discourse Theme CLI

Когда Discourse Theme CLI установлен, и ваш API-ключ готов, откройте ваш любимый текстовый редактор или окно терминала и измените рабочую директорию на то место, где вы хотите создать папку темы.

Там выполните следующую команду discourse_theme new your_theme_name и заполните подсказки следующим образом:

  1. Как вы хотите назвать вашу тему? Выберите имя темы

  2. Вы хотите начать отслеживание этой темы? Да

  3. Каков корневой URL вашего сайта Discourse? https://discourse.theme-creator.io/

  4. Вы хотите сохранить это имя сайта в…? Да

  5. Каков ваш API-ключ? введите API-ключ, полученный от theme creator

  6. Вы хотите сохранить этот API-ключ…? Да

  7. Выберите Создать и синхронизировать с новой темой, когда появится запрос

  8. Выберите Ничего не делать, когда появится запрос о дочерних компонентах темы

Если все прошло успешно, вы теперь должны сможете перейти в Мои темы на https://discourse.theme-creator.io/ и увидеть вашу новую тему в списке тем слева.

Чтобы просмотреть эти изменения в реальном времени, нажмите на имя вашей темы, а затем в нижней части области информации нажмите на Предпросмотр

Теперь Theme CLI также отслеживает любые изменения в newly created directory (созданной папке) и будет сохранять, а также обновлять тему на theme-creator при каждом изменении.

Первые шаги

Discourse Theme CLI создал каркас темы внутри папки с именем, которое мы указали в команде, выполненной ранее. Генерируется много файлов, которые мы не будем использовать, поэтому мы удалим все, кроме следующего:

common/common.scss

desktop/desktop.scss

mobile/mobile.scss

about.json

Внутри директории выполните также rm -rf .git, чтобы удалить отслеживание версий git, оно не понадобится для этого руководства.

Ваша директория темы теперь должна выглядеть так:

Стоит отметить, что стили, которые мы добавляем в эти файлы, будут отображаться в соответствующих случаях использования. Стили в common.scss будут применяться к десктопу + мобильным устройствам, в то время как стили в desktop.scss будут применяться только к десктопному просматриванию, а те, что в mobile.scss, — только к мобильным видам.

Hello World (в цвете)

Discourse использует SCSS для своего оформления, поэтому, чтобы наилучшим образом использовать стили, вам, возможно, стоит ознакомиться с SASS, но если нет, вы все равно сможете следовать этому руководству.

Хорошо, теперь к тому, чего мы все ждали… ТЕМИРОВАНИЕ!

Сейчас в нашем about.json пока не определены какие-либо color_schemes (схемы цветов), поэтому вставьте следующий код в этот раздел, а затем сохраните.

{
  "name": "my theme",
  "about_url": null,
  "license_url": null,
  "assets": {},
  "color_schemes": {
    "Default": {
      "primary": "222222",
      "secondary": "ffffff",
      "tertiary": "0088cc",
      "quaternary": "e45735",
      "header_background": "ffffff",
      "header_primary": "333333",
      "highlight": "ffff4d",
      "danger": "e45735",
      "success": "009900",
      "love": "fa6c8d"
    }
  }
}

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

Обзор темы

Чтобы было что реализовать в этом руководстве, я проведу вас через создание простой темы на основе этой палитры цветов.

image

Изменение цвета фона + основного цвета текста

Давайте сделаем что-то очень простое. Мы изменим значение "Secondary" (вторичный) в нашей текущей схеме цветов. Давайте изменим его на "secondary": "EEF4F7" (это меняет цвет фона). Также давайте изменим значение "primary" (основной) на "203243".


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

Использование схемы цветов

Все следующие ключи определены в файле about.json под соответствующим именем схемы цветов. Эти описания являются хорошей справкой, чтобы помочь вам понять, какова основная цель каждого имени переменной:

Цвет Описание
primary Большинство текста, значков и границ
secondary Основной цвет фона и цвет текста некоторых кнопок
tertiary Ссылки, некоторые кнопки, уведомления и акцентный цвет
quaternary Навигационные ссылки
header_background Цвет фона шапки сайта
header_primary Текст и значки в шапке сайта
highlight Цвет фона выделенных элементов на странице, таких как посты и темы
danger Цвет выделения для действий, таких как удаление постов и тем
success Используется для указания того, что действие было выполнено успешно
love Цвет кнопки «нравится»

Каждая из этих переменных доступна для использования в наших файлах SCSS следующим образом.

body {
  background-color: var(--primary);
}

Также создаются другие версии каждого цвета для нашего использования. Такие вещи, как var(--primary-medium) или var(--primary-very-low), можно использовать, чтобы получить разные оттенки одного и того же цвета.

Давайте изменим другие цвета в нашей схеме цветов “Default” (По умолчанию), чтобы они соответствовали этому:

"Default": {
      "primary": "203243",
      "secondary": "EEF4F7",
      "tertiary": "416376",
      "quaternary": "5E99B9",
      "header_background": "FaFaFa",
      "header_primary": "EEF4F7",
      "highlight": "86BDDB",
      "danger": "8F393E",
      "success": "70DB82",
      "love": "FC94CB"
    }

:flashlight: Вы можете увидеть все доступные переменные для использования в ваших файлах SCSS, если нажмете на ссылку Style Guide (Руководство по стилям), просматривая вашу тему на theme creator, а затем нажмете на Colors (Цвета) в левом меню.

Styleguide (Руководство по стилям) — это очень полезный раздел, который стоит просматривать при создании кастомной темы. Каждый Atom (Атом) покажет вам, как будут выглядеть определенные элементы Discourse с примененными вами стилями.

Углубляемся

С предыдущим разделом позади, я думаю, что пора углубиться в то, что можно сделать в Discourse только с помощью SCSS. (Подсказка: МНОГО!)

Оформление шапки

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

image

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

Целевой класс для настройки шапки — .d-header.

В нашем файле common/common.scss давайте добавим следующее:

.d-header {
  box-shadow: none;
  border-bottom: 1px solid var(--primary-low-mid);
  height: 5em;
}

Это удалит тень по умолчанию (box-shadow) на шапке, даст ей немного больше высоты, а также установит нижнюю границу, чтобы создать некоторую разделение.

Для значков – Внутри скобок SCSS .d-header давайте добавим этот вложенный код.

.d-header {
  // ...предыдущий код
  .d-icon {
    color: var(--primary-low-mid);
  }
}

Выглядит хорошо, но внимательный взгляд заметит, что увеличенная высота шапки оставила нам меньше места между ней и остальными элементами форума Discourse!

Интервал между основной областью и шапкой контролируется целью #main-outlet. Давайте немного увеличим этот интервал, добавив следующее в конец вашего файла common/common.scss.

#main-outlet {
  padding-top: 6.5em;
}

Контейнер навигации

Контейнер навигации включает следующие элементы.

image

Левая область — это выпадающие списки фильтров категорий/тегов, за которыми следуют навигационные ссылки, заканчивающиеся кнопкой New Topic (Новая тема).

Выпадающий список категорий / тегов

Давайте внесем некоторые изменения в эту область. Для этого добавьте следующее в ваш файл common.scss.

.navigation-container {
  .select-kit.combo-box {
    .select-kit-header {
      border-radius: 0.9em;
      background-color: var(--header_background);
    }
  }
}

Здесь мы нацеливаем на .select-kit-header, чтобы дать каждому из них одинаковый радиус скругления, а также более светлый цвет фона.

Нажатие на любой из них открывает выпадающее меню.

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

.navigation-container {
  .select-kit.combo-box {
    // ...предыдущий код
    &.category-drop,
    &.tag-drop {
      .select-kit-body {
        border-radius: 0.9em;
        background-color: var(--header_background);

        .select-kit-collection {
          background-color: var(--header_background);
          border-top-left-radius: 0px;
          border-top-right-radius: 0px;
        }
      }
    }
  }
}

Это приводит к следующему виду…

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

Давайте исправим это, посмотрев в инспекторе нашего браузера. Это всегда очень полезный инструмент, чтобы узнать, какие классы/ID нам нужно нацелить, чтобы правильно применить стили.

При видимом выпадающем меню щелкните правой кнопкой мыши по области поиска и выберите «Инспектировать» (Inspect) элемент в вашем браузере.

Мы видим, что этот ввод находится внутри div с классом select-kit-filter.

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

Добавьте следующий код, вложенный в scss .select-kit-body из предыдущего раздела.

.select-kit.combo-box.category-drop,
.select-kit.combo-box.tag-drop {
  .select-kit-body {
    // ...предыдущий код
    .select-kit-filter {
      border-top: 0px;
    }
  }
}

С этим наш код для оформления контейнера навигации должен выглядеть так.

.navigation-container {
  // Category + Tag Drop Down (Выпадающий список категорий + тегов)
  .select-kit.combo-box {
    .select-kit-header {
      border-radius: 0.9em;
      background-color: var(--header_background);
    }

    &.category-drop,
    &.tag-drop {
      .select-kit-body {
        border-radius: 0.9em;
        background-color: var(--header_background);

        .select-kit-collection {
          background-color: var(--header_background);
          border-top-left-radius: 0px;
          border-top-right-radius: 0px;
        }

        .select-kit-filter {
          border-top: 0px;
        }
      }
    }
  }
}

Навигационные ссылки

Давайте добавим некоторые стили, чтобы эти навигационные ссылки выглядели похоже на это:

image

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

Мы видим, что наши элементы навигации находятся внутри UL с классом "nav nav-pills ..."

Вернувшись в наш файл common.scss, под предыдущим разделом, но все еще вложенным внутри navigation-container, давайте добавим следующее:

.nav-pills {
  & > li a {
    &.active {
      color: var(--tertiary);
      background-color: var(--secondary);
      border-bottom: 4px solid var(--tertiary);
    }
  }
}

Это изменение нацелит только наши ссылки с классом active, которые являются дочерними элементами nav-pills. Это изменение должно сделать нашу активную ссылку выглядящей так:

image

Это нормально, но я хотел бы, чтобы нижняя граница простиралась только на ширину текста. Для этого, над строкой &.active {, давайте добавим следующее, что повлияет на все ссылки A внутри тегов <li> навигации.

// ...другой код
.nav-pills {
  & > li a {
    padding: 0;
    margin-right: 20px;
    color: var(--tertiary-high);
    border-bottom: 4px solid transparent;

    &.active {
      // ...еще код
    }
  }
}

Теперь нам нужно стилизовать эффект “наведения” (hover) так же, как эффект “активного” состояния.

Под нашим предыдущим &.active давайте добавим

&:hover {
  color: var(--tertiary);
  background-color: var(--secondary);
  border-bottom: 4px solid var(--primary);
}

Так что весь наш код навигации теперь должен выглядеть так:

// Nav Pills
.nav-pills {
  & > li a {
    padding: 0;
    margin-right: 20px;
    color: var(--tertiary-high);
    border-bottom: 4px solid transparent;

    &.active {
      color: var(--tertiary);
      background-color: var(--secondary);
      border-bottom: 4px solid var(--tertiary);
    }

    &:hover {
      color: var(--tertiary);
      background-color: var(--secondary);
      border-bottom: 4px solid var(--primary);
    }
  }
}

Кнопки

Кнопки в Discourse бывают многих форм и размеров. Вы можете просмотреть их разнообразие в разделе Кнопки в Style Guide (Руководстве по стилям).

Я хотел бы изменить большинство кнопок в этой теме, чтобы они были скругленными с некоторым кастомным оформлением. Это изменит кнопку + New Topic (+ Новая тема), а также другие кнопки по всему сайту.

В конце нашего файла common.scss давайте добавим следующее:

.btn {
  background-color: var(--header_background);
  color: var(--primary);
  border-radius: 1.2em;
  border: 1px solid var(--primary-low-mid);

  .d-icon {
    color: var(--primary);
  }

  &:hover {
    background-color: var(--quaternary-low);
    color: var(--primary);
    .d-icon {
      color: var(--primary);
    }
  }

  &.btn-default,
  &.btn-primary {
    padding: 10px 12px;
  }
}

Это сделает наши кнопки выглядящими так:

image

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

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

Я не хочу, чтобы эти кнопки редактирования текста были затронуты моим предыдущим оформлением. Это требует немного более сложного SASS/CSS, но мы можем заставить наш код :not() не влиять на эти кнопки. :wink:

Давайте добавим эту строку кода перед нашей текущей целью .btn. Это сообщит нашим стилям применяться только к кнопкам, которые не являются дочерними элементами .d-editor-button-bar.

:not(.d-editor-button-bar) > .btn

Хорошо, это сработало отлично… но подождите! Теперь есть этот странный бунтарь, делающий по-своему.

image

Инспектируя это в браузере, я вижу, что у этой кнопки есть класс .select-kit-header, потому что при нажатии на эту шестеренку появятся дополнительные параметры.

:flashlight: Я не могу подчеркнуть, насколько важно использовать инструменты инспектора вашего браузера при создании тем Discourse. Они ваш лучший друг, который сопровождает вас в этом путешествии.

Теперь, когда мы знаем, что мы НЕ хотим нацеливать на эту кнопку, давайте добавим еще немного функциональности :not() в наш код.

:not(.d-editor-button-bar) >
.btn:not(.single-select-header)

Это выберет все кнопки, которые НЕ являются дочерними элементами .d-editor-button-bar и не имеют класса .single-select-header. Я знаю, что это немного запутанно, но внутри Discourse много движущихся частей, поэтому иногда стилизация должна быть очень специфичной, чтобы правильно влиять на элементы.

Я также заметил, что наше текущее оформление неловко влияет на кнопку закрытия модального окна. Нажатие на что-либо, что открывает модальное окно, позволит вам увидеть это, или даже проще, мы можем перейти к разделу модальных окон в Style Guide (Руководстве по стилям).

Чтобы исправить это, я добавлю еще одну цель в наш код.

:not(.d-editor-button-bar) >
.btn:not(.single-select-header):not(.modal-close)

Продолжаем…

Я вижу еще одну кнопку, которая, похоже, не была затронута нашим кодом. Это кнопка Tracking (Отслеживание), расположенная в самом низу потока постов темы.

image

Я добавлю следующую строку, после запятой, в наш текущий код .btn.

:not(.d-editor-button-bar) >
.btn:not(.single-select-header):not(.modal-close),
.topic-notifications-button > .select-kit > .btn

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

:flashlight: Не стесняйтесь настраивать любые параметры в вашем собственном css. Чем больше вы экспериментируете с этими стилями и видите, что и как они влияют на html, тем больше вы будете учиться!

Куда двигаться дальше

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

Помните МНОГО вещей можно настроить, используя только SCSS. Если вы хотите углубиться в разработку, я рекомендую прочитать статьи, на которые даны ссылки в начале этого поста.

Не стесняйтесь задавать любые вопросы, и я с удовольствием постараюсь помочь вам или направить вас в правильном направлении.


Этот документ контролируется по версиям - предложите изменения на github.

45 лайков

Привет, @jordan.vidrine,

При работе над разделом Запуск CLI темы Discourse этого руководства я столкнулся с ошибкой 301.

Мне удалось её исправить, используя https://discourse.theme-creator.io/ вместо https://theme-creator.discourse.org в качестве корневого URL.

Надеюсь, это поможет!

7 лайков

О да, мы обновили этот URL, и этот пост тоже требует обновления — спасибо, что сообщили нам!

6 лайков

Спасибо за эту информацию, @IdentityDan!
Также для справки: если вы столкнулись с этой ошибкой, вам, скорее всего, потребуется отредактировать файл /home/USERNAME/.discourse_theme, в котором хранятся связи между ключами API и сайтами Discourse для каждой темы.
Таким образом, даже если создание темы завершается сбоем, данные, введённые в «мастере», сохраняются в этом файле. Если вы попытаетесь создать новую тему с тем же именем, URL и ключи API будут получены из этого файла.

3 лайка

Ещё один момент: при использовании предварительного просмотра темы ссылка на «Руководство по стилю» работает некорректно. Она перенаправляет на страницу со стандартной темой, но если добавить к URL ?preview_theme_id=THEME-ID-NUMBER, то «Руководство по стилю» отобразится с правильной темой.

1 лайк

Спасибо, это потрясающе

2 лайка

Здравствуйте, я только начинаю читать пост…
Но прежде чем двигаться дальше, я хотел бы узнать, можно ли использовать CLI с самостоятельно размещённым экземпляром?
Или же нам необходимо использовать CLI с theme-creator.io для разработки, а после завершения «импортировать» тему в самостоятельно размещённый экземпляр?
В моём случае меня больше интересует использование в качестве темы для настройки разового форума, а не создание многоразовой темы, предназначенной для публикации.
Так что мне всё ещё следует использовать CLI с этим публичным сайтом?
Спасибо.

1 лайк

Это возможно, и я рекомендую именно этот метод. Единственное, о чём стоит помнить: все изменения будут сразу же отображаться на форуме по мере их внесения.

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

2 лайка

Я часто делаю это с помощью «тестового» живого сервера, доменное имя которого я не решаюсь прекратить арендовать.

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

Очевидно, я все еще плачу за хранилище (и, возможно, за IP-адрес), но по крайней мере я не плачу за круглосуточные вычислительные ресурсы.

Кажется, есть ещё одно место, которое требует обновления!

1 лайк