Типография

November 8, 2025 · View on GitHub

en ru

Типография

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

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

Да, это непросто. Хорошая документация требует времени, внимания к деталям и постоянной доработки. Но мы не ищем лёгких путей — мы работаем над тем, чтобы каждый следующий релиз становился чуть понятнее, доступнее и полезнее для всех, кто работает с MoonShine.

Заголовок

Название раздела является первым и обязательным элементом страницы.

# Title

Навигация

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

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

- [Subtitle 1](#subtitle-1)
- [Subtitle 2](#subtitle-2)

Note

Для разделения слов в ссылках используется kebab-case.

Разделитель

После навигации необходимо указать разделитель.

---

Заголовок подраздела

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

## Subtitle

Если используется Навигация, то необходимо перед заголовком добавить якорь:

<a name="anchor"></a>
## Subtitle

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

<a name="basics"></a>
## Основы

Если описывается компонент, который наследуется от другого класса, и в навигации есть пункт Основы, то описание наследования пишем строго после этого пункта.

<a name="basics"></a>
## Основы

Наследует [Select](/docs/{{version}}/fields/select).

\* имеет те же возможности.

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

<a name="basics"></a>
## Основы

Содержит все [Базовые методы](/docs/{{version}}/fields/basic-methods).

Контент

Кроме тегов markdown допускается использование html-тегов.

Warning

Все предложения должны заканчиваться точкой.

Желательно построчно синхронизировать тексты в ru и en версиях разделов.

Для выделения имени собственного используются двойные звёздочки **, например, **MoonShine**.

Примеры кода

  • для оформления методов, классов и тд. используется одиночный апостроф `,
  • названия методов должны заканчиваться скобками, например: setLabel(),
  • для оформления блоков кода используется тройные апострофы ``` с указанием языка программирования и начинаться блок должен с новой строки,
  • для всех классов, используемых в примерах, необходимо указать use в алфавитном порядке и обернуть их в collapse.
// torchlight! {"summaryCollapsedIndicator": "namespaces"}
// [tl! collapse:1]
use MoonShine\UI\Fields\Text;

Text::make('Title')

или

// torchlight! {"summaryCollapsedIndicator": "namespaces"}
// [tl! collapse:start]
use MoonShine\UI\Fields\Text; // [tl! collapse:end]

Text::make('Title')

Для подсветки изменений в коде можно использовать специальные аннотации.

MenuItem::make('Settings', SettingResource::class, 'heroicons.outline.adjustments-vertical') // [tl! remove]
MenuItem::make(SettingResource::class, 'Settings', 'adjustments-vertical') // [tl! add]

или

MenuItem::make('Settings', SettingResource::class, 'heroicons.outline.adjustments-vertical') // [tl! --]
MenuItem::make(SettingResource::class, 'Settings', 'adjustments-vertical') // [tl! ++]

Указать название файла или класса, к которому относится код, можно через параметр filename.

```php filename:config/moonshine.php

Warning

Использование пробелов в названиях недопустимо.

Списки

- элементы списка заканчивается запятой,
- после последнего элемента ставится точка.

Вкладки

~~~tabs

tab: Tab 1
Content tab 1

tab: Tab 2
Content tab 2

~~~

Уведомления

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

> [!NOTE]
> Простое уведомление.

> [!WARNING]
> Предупреждение.

> [!TIP]
> Советы.

Изображения

Изображения добавляем в директорию /resources/screenshots.

Ссылку указываем - https://raw.githubusercontent.com/moonshine-software/doc/4.x/resources/screenshots/filename.png

Пример:

![belongs_to_many](https://raw.githubusercontent.com/moonshine-software/doc/4.x/resources/screenshots/belongs_to_many.png)

Для показа изображения в темной или светлой теме, необходимо к ссылке добавить hash тег #light или #dark.

![belongs_to_many](https://raw.githubusercontent.com/moonshine-software/doc/4.x/resources/screenshots/belongs_to_many.png#light)
![belongs_to_many](https://raw.githubusercontent.com/moonshine-software/doc/4.x/resources/screenshots/belongs_to_many_dark.png#dark)

Shortcodes

Include

Шорт-код include подключает markdown и отображает его, а затем пропускает содержимое через sprintf, поэтому все параметры после пути к markdown будут переданы в том же порядке.

@include($path_to_md, ...$params)

Пример файла

_includes/my-partial.md

## Hello world
%s - %s

Пример использования

_includes/test.md

<a name="what-is-moonshine"></a>
## What is MoonShine

@include('_includes/test', 'test', 3)

Под капотом

sprintf('markdown', 'test', 3);

Результат

<h2>What is MoonShine</h2>
test - 3