Файлы и директории

С помощью правильного именования исходных файлов вы можете задавать:

• порядок страниц внутри одного раздела (для директорий без _nav.yaml),
• имена выходных файлов при сборке HTML (для файлов без permalink).

В этом разделе описано поведение Собираки по умолчанию, без специальной настройки, а также упоминаются способы изменить это поведение. Примеры приведены для файлов с расширением .md (Markdown), но такое же поведение актуально и для файлов с расширением .rst.

Управление сортировкой страниц #

По умолчанию Собирака сортирует подразделы на каждом уровне иерархии по алфавиту. Поддиректории участвуют в сортировке наравне с файлами.

Если в директории есть индексный файл, Собирака ставит его на первое место.

├── _index.md
├── introduction.md
├── setup
│   ├── _index.md
│   ├── linux.md
│   ├── macos.md
│   └── windows.md
├── requirements.md
└── usage.md

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

Исходные файлы без числового префикса помещаются в конец списка и сортируются как обычно.

├── _index.md
├── 1-introduction.md
├── 2-requirements.md
├── 3-setup
│   ├── _index.md
│   ├── 1-windows.md
│   ├── 2-macos.md
│   └── 3-linux.md
└── usage.md

Управление именами выходных файлов #

По умолчанию при сборке HTML Собирака формирует путь к конечному файлу из основной части имени исходного файла (без расширения, опционального знака подчёркивания в начале и числового префикса). К именам файлов добавляется расширение .html.

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

├── _index.md          →  /index.html
├── 1-introduction.md  →  /introduction.html
├── 2-requirements.md  →  /requirements.html
├── 3-setup            →  /setup/
│   ├── _index.md      →  /setup/index.html
│   ├── 1-windows.md   →  /setup/windows.html
│   ├── 2-macos.md     →  /setup/macos.html
│   └── 3-linux.md     →  /setup/linux.html
└── usage.md           →  /usage.html

Директории и индексные файлы #

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

Каждый раздел в документации всегда имеет индексную страницу. В иерархии эта страница находится уровнем выше, чем все остальные страницы из её директории, то есть на одном уровне со страницами из родительского раздела. Собирака загружает индексную страницу из файла с именем “index” или числовым префиксом “0” (примеры: 0.md, 0-contents.md, _index.md), а если такого файла нет — автоматически генерирует простую индексную страницу с оглавлением.

При сборке в PDF содержимое такой страницы отображается в начале раздела, а при сборке в HTML страница становится файлом index.html. Большинство веб-серверов поддерживают index.html как имя файла по умолчанию, что позволяет видеть индексную страницу и по ссылке вида /example/index.html, и по более красивой ссылке вида /example/.

Изменения формата имён файлов #

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

Например, с помощью этой настройки вы можете:

• использовать после числового префикса другой разделитель вместо дефиса;
• использовать для индексной страницы другое имя вместо _index.md;
• игнорировать определённый суффикс в имени.

Чтобы написать подходящее значение настройки, необходимо знать регулярные выражения. Перед началом работы рекомендуется ознакомиться с тем набором регулярных выражений, которые Собирака использует по умолчанию, в файле namingscheme.py.

(?P<stem> .+ ) ( \.\d+ )?