OpenGuides

Рекомендации по форматированию файлов

[≔ Оглавление]

---

Общие правила ↑↑

Цель проекта — создать и поддерживать справочник по организации жизни "Искры".

При этом мы хотим получить пособие, обладающее:

• информативностью;
• наглядностью;
• удобством навигации.

Поэтому введём правила формирования заметок, инструкций и т.п.

Структура ↑↑

Общий вид репозитория:

- корневая директория:
    * директория-глава справочника
    ...
    * директория-глава справочника:
        + README.md с основным содержанием
        <дополнительные файлы|директории>
    * файл глобального значения
    ...
    * файл г.з.
    * корневой README.md

Каждая страница справочника — это файл в формате .md.

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

# Заглавие
## Раздел
#### Заголовок
###### Подзаголовок

Обычно 1-й, 2-й, 4-й и 6-й уровни визуально хорошо различимы между собой, однако, в длинных документах нумеровать их всё же стоит (в стиле a la ГОСТ 7.32-2017 или более поздней редакции).

Все остальные файлы рекомендуется помещать в отдельные подкаталоги. Примем следующий вариант наименования этих подкаталогов как эталонный:

• img для изображений;
• pdf для (как ни странно) PDF.

Навигация внутри файла ↑↑

Важным аспектом является навигация внутри страницы.

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

Шаблон "якоря" внутри файла:

<a name="a"></a>

Ссылка на него:

[](#a)

Пример:

<a name="sample"></a>

[пример](#sample)

Можно ссылаться на заголовки. Для получения ссылки на заголовок:

1. выбрасываем все видимые символы, кроме букв и пробелов;
2. переводим буквы в нижний регистр;
3. видимые пробелы заменяем на дефисы -;
4. если в конце был пробел, а за ним только спецсимволы, то ставим дефис на его месте.

Если ссылка не заработала, то смотрим на якорь рядом с заголовком в результирующем HTML-представлении.

Пример ссылки на заголовок:

[LibreOffice](#libreoffice-наверх)

## LibreOffice [[↑наверх↑](#top)]

Навигация между файлами ↑↑

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

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

###### Подробнее в [файле ⎘](./TODO.md)

При добавлении в корневой README.md в роли шаблона используем предыдущие пункты содержания.

---

Шаблоны ↑↑

Ниже даны шаблоны для README.md и поддокументов. Ссылки на начало документа можно указывать либо кратко [↑↑](#top), либо полностью [[↑наверх↑](#top)].

Шаблон шапки README.md:

# <Заглавие> <a name="top"></a>
#### [≔ К содержанию](../README.md)

В файлах корневого каталога шаблон отличается на 1 точку:

# <Заглавие> <a name="top"></a>
#### [≔ К содержанию](/OpenGuides/)

Шаблон шапки файла-подраздела (ссылки на которые есть в README.md):

# <Заглавие> <a name="top"></a>
#### [⌂ На главную](/OpenGuides/)

Шаблон содержимого (для любого док.):

----
## <Глава/Раздел> [↑↑](#top)

<текст>

#### <заголовок> [↑↑](#top)

<текст>

###### <подзаголовок> [↑↑](#top)

<текст>

Вариант с длинной ссылкой "наверх":

----
## <Глава/Раздел>  [[↑наверх↑](#top)]

<текст>

#### <заголовок>  [[↑наверх↑](#top)]

<текст>

###### <подзаголовок>  [[↑наверх↑](#top)]

<текст>