Родительский раздел: База знаний 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-ссылку к родительской странице и
. Стартовые страницы разделов дополнительно содержат явное меню ссылок,
и
. Ссылки на страницы должны соответствовать реально существующим адресам и типизированным связям.