Поиск

Авторы

Авторы

Table of Contents

Соглашения по оформлению

При написании документации Orchard используется Markdown. Мы используем несколько простых соглашений для поддержания единого стиля всех документов.

Заголовки и названия файлов

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

Структура

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

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

После аннотации следует основное содержание статьи, которое должно быть разбито на разделы с заголовками в первого уровня 1 # Это заголовок верхнего уровня.

Разделы более низкого уровня должны быть на 1 уровень ниже родительского.

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

[How To Build Awesome Documentation][link1]
[link1]: #HowToBuildAwesomeDocumentation

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

[Follow this link to learn how to build awesome documentation][link1]
[link1]: name-of-the-linked-document#HowToBuildAwesomeDocumentation

Имейте в виду, что якоря являются регистрозависимыми.

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

Разметка и стили

Статьи должны использовать стандарт Markdown, при этом необходимо избегать явного использования HTML, включая стили.

Жирность и курсив

Не используйте заголовки для расстановки акцентов.

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

Используйте **двойные звездочки** для очень важных моментов, которые будут выделены жирным.

Используйте > знак "больше" для выделения всего параграфа.

Код

Примеры кода необходимо выделять `обратными апострофами`, а многострочный код должен быть оформлен параграфами с отступом в 4 пробела.

Это блок с кодом

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

Маскировка Markdown

Если в вашем тексте встречается набор символов, которые воспринимаются как wiki-разметка, такие как `, * или _ но вам необходимо использовать их как есть, без интерпретации как разметки, добавьте обратный слеш (\) перед символом или окружите последовательность символов разделителями кода (`). Вы можете просмотреть исходный код этого документа (кликнув на кнопку редактирование в панели справа), где найдете множество подобных примеров.

Список символов, которые необходимо экранировать, можно посмотреть здесь.

Изображения

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

Изображения должны быть добавлены на github, в поддиректорию папки Attachments с именем, совпадающим с именем markdown-файла статьи. Если изображение имеется в маленьком и большом разрешении, меньшее должно иметь то же имя, что и большее, но с префиксом "s_".

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

![Подсказка к изображению](/Attachments/Название-темы/НазваниеИзображения.png)

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

[![Подсказка к изображению](../Attachments/Название-темы/НазваниеУменьшенногоИзображения.png)](/Attachments/Название-темы/НазваниеИзображения.png)

Допустимо использовать форматы PNG, JPG и GIF. Изображения должны использовать разумное сжатие. Старайтесь избегать использования формата JPG для скриншотов, используйте его для фотографий.

Ссылки

Ссылки на другие топики документации могут создаваться следующим образом:

[Текст ссылки](/Documentation/Topic-Name)

или так:

[Текст ссылки][ref1]
[ref1]: Topic-Name

Ссылки на внешний контент могут быть добавлены так:

[Текст ссылки](http://somesite/somepage)

или так:

[Text for the link][ref1]
[ref1]: http://somesite/somepage

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

Используйте ссылки на конкретные секции документа там, где это необходимо (см. Структура).

Таблицы

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

Заголовок A | Заголовок B | Заголовок C
----------- | ----------- | --------
Ячейка A.1  | Ячейка B.1  | Ячейка C.1
Ячейка A.2  | Ячейка B.2  | Ячейка C.2
Ячейка A.3  | Ячейка B.3  | Ячейка C.3

Эта разметка отобразит такую таблицу:

Заголовок A Заголовок B Заголовок C
Ячейка A.1 Ячейка B.1 Ячейка C.1
Ячейка A.2 Ячейка B.2 Ячейка C.2
Ячейка A.3 Ячейка B.3 Ячейка C.3
Подробно о таблицах читайте Markdown Extra Tables Reference.

Принять участие в написании документации

Русскоязычная документация Orchard создается как файлы Markdown в репозитории Git, размещенном на Github.

Внесение изменений в существующие статьи

В правой колонке страницы каждой статьи вы можете найти ссылку на соответствующий документ на Github.

Кнопка "Редактировать"

Более масштабные правки и добавления

Мы рекомендуем использовать GitHub для Windows для создания локальной копии документации. Это позволит вам иметь свою копию сайта с документацией, который вы можете запускать из WebMatrix или Visual Studio.