Документация

Хотите помочь улучшить документацию? Спасибо! Файлы документации размещены на GitHub, позволяя любому предлагать изменения.

Исходники документации написаны на Markdown.

Как редактировать страницы¶

Для редактирования страниц вам понадобится учетная запись GitHub. Зарегистрируйтесь, если у вас еще нет учетной записи

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

Если вы хотите добавить новые страницы или уже просматриваете исходники на GitHub, не забудьте сначала выбрать правильную ветку (2.x или 3.x). Затем вы можете перемещаться по языковым папкам, чтобы найти нужный каталог.

Создание новых файлов¶

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

Чтобы новая папка отображалась в навигации, либо должен быть файл index.md непосредственно в каталоге, либо должен быть файл с тем же именем, что и каталог, с расширением .md. Например, в этой гипотетической структуре каталогов, new-section и other-section оба есть в меню, но hidden-section нет, потому, что у него нет индексной страницы:

• new-section/
  • new-section/index.md
  • new-section/other-page.md
• other-section.md
• other-section/
  • other-section/greatness.md
• hidden-section/
  • hidden-section/secret.md

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

Инфо блок¶

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

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

---

title: 'Отличная документация'
description: 'Это описание метаданных будет использоваться поисковыми системами..'

---

Порядок отображения в меню¶

Чтобы изменить порядок в навигации, добавьте sortorder:

---

title: 'Отличная документация'
description: 'Это описание метаданных будет использоваться поисковыми системами..'
sortorder: 3

---

Любой документ без сортировки будет добавлен после документов с сортировкой и будет использовать естественную сортировку на основе имени файла.

Переводы¶

Чтобы связать перевод с оригинальной (английской) версией документации, добавьте запись «translation» в начало. Укажите путь без префикса версии или языка, например:

---

title: "Дружественные URL-адреса на моем языке"
translation: "getting-started/friendly-urls"

---

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

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

Чтобы проверить, правильно ли подключен перевод, вам нужно запустить приложение в локальной среде и выполнить php docs.php index:translations. См. Репозиторий DocsApp для получения дополнительной информации.

Скринкаст¶

Если вы новичок в git или GitHub или являетесь более опытным специалистом по визуальному обучению, следующий скринкаст (с 2019 г.) покажет вам, как можно редактировать документацию с помощью только браузера.

Смотрите также¶

1. Markdown свод правил проверки