Родительский раздел: База знаний ShariX Open. Эта статья — каноническая инструкция для генераторов архивов публикации.

Единый канонический формат для previewPackage / publishPackage — sharix.knowledge.bundle версии 1. В корне ZIP только файл манифеста и перечисленные в нём документы:

manifest.json
documents/ShariXKnowledgeZipContractExample.txt

Не класть в архив README, вложенные ZIP, папку с именем выпуска, файлы ОС или запись каталога documents/. documents/<id>.txt — текст в UTF-8, имя файла точно совпадает с path и id в манифесте. sha256 вычисляется по байтам текста. Это проверка целостности при передаче, не контроль существующей редакции Wiki.

Пример manifest.json для примера страницы ниже:

{
  "format": "sharix.knowledge.bundle",
  "version": 1,
  "documents": [
    {
      "id": "ShariXKnowledgeZipContractExample",
      "page": "sharixopen:knowledge:examples:zip_contract_example",
      "area": "open",
      "type": "verification",
      "title": "Проверка пакета ShariX Knowledge",
      "status": "review",
      "schema_version": 1,
      "relations": {},
      "extensions": {},
      "path": "documents/ShariXKnowledgeZipContractExample.txt",
      "sha256": "987a979e8e2a0c5655cbf44b25c64c688eb49cb3d82e60112a5824d207104547"
    }
  ]
}

Содержимое documents/ShariXKnowledgeZipContractExample.txt:

====== Проверка пакета ShariX Knowledge ======
~~NOCACHE~~

Статья для проверки структуры публикационного ZIP.

Значения: page — постоянный адрес DokuWiki; area — open, platform либо joint; id — синтаксически корректный ID входного пакета, который плагин согласует с существующим ID страницы; type — policy, architecture, decision, contract, component, procedure, requirement, verification либо reference; status — draft, review, approved, deprecated; schema_version равен 1. Связи relations — массивы ID документов, extensions.taxonomy.parents — ID родительских документов. Не придумывать несуществующие ID связанных страниц.

Для обычного создания или обновления base_sha256 не требуется. Плагин определяет существование страницы по page независимо от старых JSON-файлов, сохраняет её собственный ID, перезаписывает через штатный API DokuWiki и ведёт историю редакций.

Плагин сам добавляет в начало DokuWiki-страницы скрытый блок. Генератор ZIP не должен дублировать его вручную в тексте статьи. Пример структуры блока, которую можно увидеть в исходнике страницы:

<sharix-knowledge-meta>
{
  "schema": 1,
  "id": "ShariXKnowledgeOpenArchitectureStart",
  "page": "sharixopen:knowledge:architecture:start",
  "area": "open",
  "type": "architecture",
  "title": "Архитектура ShariX Open",
  "status": "approved",
  "schema_version": 1,
  "relations": {"related_to": ["ShariXKnowledgeOpenKnowledgeModulesStart"]},
  "extensions": {"taxonomy": {"domain": "architecture", "parents": [], "terms": []}}
}
</sharix-knowledge-meta>

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

Django-модуль ShariX Knowledge принимает описанный канонический ZIP и может принимать упрощённый архив с путями open/…txt, platform/…txt, joint/…txt. Папочный формат — только входной вариант Django: перед запросом DokuWiki он преобразуется в канонический manifest.json + documents/. Не отправлять папочный формат непосредственно в API DokuWiki.

Через маршрутизатор Platform допустимо объединять области open, platform и joint в одном каноническом ZIP: Platform разделяет его по целевой wiki. Если пакет отправляется напрямую в DokuWiki, допускаются только области соответствующей установки: open — публичная, platform и joint — внутренняя.

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

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

Обычная замена существующей страницы публикуется после общего просмотра изменений; DokuWiki хранит историю. Сходство с другой страницей по иному адресу должно быть показано как выбор: объединить, перенести или создать отдельно. Удаление — отдельная явная операция operation=delete с delete_confirmation и проверкой AUTH_DELETE; отсутствие файла в новом ZIP не удаляет страницу. Конфликтные страницы можно пропустить и опубликовать остальные. При просмотре различий показывать цветной построчный diff.

Каждая содержательная страница должна иметь , понятную структуру, wiki-ссылку к родительской странице и

. Стартовые страницы разделов дополнительно содержат явное меню ссылок,

и

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

• Пакет v1 и проверка содержимого
• Open / Platform / Joint: маршруты и проверка
• Состав пакета и приёмка