Перейти до змісту

Навігаційні зміни – документ процесу для менеджерів або редакторів

Підстава для цього документа

Коли розпочався проект документації, сподівалися, що меню в Mkdocs будуть максимально автоматичними, що зробить редагування ручної навігації рідкістю. Після кількох місяців генерування документів стало зрозуміло, що просто розмістити документи у правильній папці та дозволити Mkdocs розробити навігацію, щоб зберегти речі чистими та акуратними, не можна покладатися. Нам потрібні були категорії, які Mkdocs не надає, якщо документи не знаходяться в певних папках. Тоді Mkdocs створить навігацію за алфавітним сортуванням. Однак створення структури папок, яка виправляє навігацію, — це ще не все. Навіть для цього іноді знадобляться додаткові зміни, щоб зберегти порядок. Наприклад, використання великих літер без зміни структури папок у нижньому регістрі.

Цілі

Нашими цілями були:

  • Створення потрібної структури папок зараз (у майбутньому можуть знадобитися нові папки).
  • Налаштувати навігацію так, щоб області Rocky Installation, Migration і Contribution були вгорі
  • Налаштувати навігацію, щоб краще назвати деякі папки, і увімкнути правильне використання великих літер. Як приклад, «DNS» і «File Sharing Services» інакше відображаються як «Dns» і «File sharing» без будь-яких маніпуляцій.
  • Переконатися, що ці навігаційні файли доступні тільки менеджерам і редакторам.

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

Припущення

Передбачається, що у вас є локальний клон репозиторію Rocky GitHub: https://github.com/rocky-linux/documentation.

Зміни середовища

З цими змінами виникає справжня потреба «побачити», як будь-які зміни, які ви вносите, впливають на вміст у контексті веб-сайту, ПЕРЕД, як цей вміст буде закріплено в сховищі документів, а згодом стане «активним».

MkDocs — це програма Python, і додаткові пакети, які вона використовує, також є кодом Python, це означає, що середовище, необхідне для запуску MkDocs, має бути правильно налаштованим середовищем Python. Налаштування Python для завдань розробки (а саме те, що робиться під час запуску MkDocs) не є тривіальним завданням, і інструкції щодо цього виходять за рамки цього документа. Деякі міркування:

  • Версія Python має бути >= 3.8, також необхідно бути особливо обережним, щоб не використовувати «системну» версію Python комп’ютера, якщо на комп’ютері працює Linux/macOS. Наприклад, на момент написання цього документа системною версією Python для macOS залишається версія 2.7.
  • Запуск «віртуального середовища» Python. Під час запуску проектів програм Python і встановлення пакетів, наприклад MkDocs, спільнота Python наполегливо рекомендує створити ізольоване віртуальне середовище для кожного проекту.
  • Використовуйте сучасне IDE (інтегроване середовище розробки), яке добре підтримує Python. Дві популярні IDE, які також мають вбудовану підтримку запуску віртуальних середовищ, це:

Щоб це зробити ефективно, потрібно:

  • Налаштування нового проекту Python, який, в ідеалі, використовує віртуальне середовище (вище).
  • Встановлення mkdocs
  • Встановлення деяких плагінів python
  • Клонування цього репозиторію Rocky GitHub: https://github.com/rocky-linux/docs.rockylinux.org
  • Посилання на папку docs у вашому клонованому сховищі документації (ви також можете просто змінити файл mkdocs.yml, якщо хочете завантажити правильну папку, але зв’язування зробить ваше середовище mkdocs чистішим)
  • Запуск mkdocs serve у вашому клоні docs.rockylinux.org

Підказка

Ви можете створювати окремі середовища для mkdocs, використовуючи будь-яку з процедур у розділі «Локальна документація» меню «Внести свій внесок».

Примітка

Цей документ було написано в середовищі Linux. Якщо ваше середовище інше (Windows або Mac), вам потрібно буде дослідити відповідність деяких із цих кроків. Редактор або менеджер, який читає це, може внести до нього зміни, щоб додати кроки для цих середовищ.

Встановлення

  • Встановіть mkdocs у середовищі python: pip install mkdocs
  • Встановіть необхідні плагіни: pip install mkdocs-material mkdocs-localsearch mkdocs-awesome-pages-plugin mkdocs-redirects mkdocs-i18n
  • Клонувати репозиторій (зазначено вище)

Приєднання та запуск mkdocs

У вашому локальному файлі docs.rockylinux.org (клоні) виконайте наступне. Це передбачає розташування вашого клону документації, тому змініть за потреби:

ln -s /home/username/documentation/docs docs

Знову ж таки, за бажанням ви можете змінити локальну копію файлу mkdocs.yml, щоб установити шлях. Якщо ви використовуєте цей метод, ви повинні змінити цей рядок, щоб вказувати на вашу папку documentation/docs:

docs_dir: 'docs/docs'

Після завершення ви можете спробувати запустити mkdocs serve, щоб побачити, чи ви отримали бажаний вміст. Це буде працювати на вашому локальному хості на порту 8000; наприклад: http://127.0.0.1:8000/

Навігація та інші зміни

Навігація обробляється за допомогою файлів mkdocs .pages АБО значенням мета "title:" у передній частині документа. Файли .pages не є складними, АЛЕ якщо щось пропущено, це може спричинити збій завантаження сервера. Ось чому ця процедура ЛИШЕ для менеджерів і редакторів. Ці особи матимуть інструменти (локальне встановлення mkdocs, а також клони документації та docs.rockylinux.org), щоб щось, передане та об’єднане з GitHub, не порушувало обслуговування веб-сайту документації. Не можна очікувати, що учасник відповідатиме хоча б одній із цих вимог.

Файли .pages

Як уже зазначалося, файли .pages загалом досить прості. Це файл у форматі YAML, який mkdocs зчитує перед відтворенням вмісту. Щоб поглянути на один із складніших файлів .pages, давайте розглянемо файл, створений для форматування бічної навігації:

---
nav:
    - ... | index*.md
    - ... | installation*.md
    - ... | migrate2rocky*.md
    - Contribute: contribute
    - Automation: automation
    - Backup & Sync: backup
    - Content Management: cms
    - Communications: communications
    - Containers: containers
    - Database: database
    - Desktop: desktop
    - DNS: dns
    - Email: email
    - File Sharing Services: file_sharing
    - Git: git
    - Interoperability: interoperability
    - Mirror Management: mirror_management
    - Network: network
    - Package Management: package_management
    - ...

Тут index*md показує «Guides Home: », installation*.md показує посилання на документ «Встановлення Rocky Linux», а migrate2rocky*.md показує посилання на документ «Міграція на Rocky Linux». "*" у кожному посиланні дозволяє документу бути будь-якою мовою. Нарешті, розміщення "Внести свій внесок" знаходиться під цими елементами, а не в звичайному (алфавітному) порядку сортування. Переглядаючи список, ви можете побачити, що робить кожен елемент. Зауважте, що після запису «Керування пакетами: package_management» є ще дві папки (безпека та веб). Вони не потребують додаткового форматування, тому ми просто повідомляємо mkdocs завантажувати їх зазвичай із «-...»

Ви також можете використовувати форматування YAML у реальному файлі. Причиною для цього може бути те, що початковий заголовок файлу такий довгий, що він просто погано відображається в розділі навігації. Як приклад візьмемо заголовок цього документа "# mod_ssl на Rocky Linux у середовищі веб-сервера httpd Apache". Це дуже довго. Він дуже погано відображається на бічній панелі навігації, коли відкрито навігаційний елемент «Інтернет». Щоб виправити це, ви можете спільно з автором змінити його заголовок або змінити спосіб його відображення в меню, додавши заголовок перед заголовком усередині документа. Для прикладу документа додано назву:

---
title: Apache With `mod_ssl`
---

Це змінює назву щодо навігації, але залишає оригінальну назву автора в документі.

Ймовірно, не буде великої потреби в додаткових файлах .pages. Їх слід використовувати економно.

Висновок

Хоча навігаційні зміни, які, можливо, потрібно буде внести, не є складними, потенційна можливість зламати поточну документацію існує. З цієї причини лише менеджери та редактори з відповідними інструментами повинні мати дозвіл на редагування цих файлів. Наявність повного доступного середовища для перегляду того, як виглядатимуть живі сторінки, запобігає менеджеру чи редактору від помилок під час редагування цих файлів, порушуючи поточну документацію.

Author: Steven Spencer

Contributors: Ezequiel Bruni, Ganna Zhyrnova