Стандарт оформления страницы: навигация, граф, каталог и связи

База знаний ShariX · Подготовка архивов · Обязательные блоки страниц · Формат ZIP · Open / Platform / Joint · Правила для ИИ

Назначение: обязательный шаблон для всех новых и обновляемых управляемых страниц ShariX Knowledge. Он одинаково применяется к документации open, platform и joint, но сведения каждой области публикуются только в соответствующей wiki. Статус: проект правил review.

1. Почему необходим шаблон

Машинные связи в manifest.json нужны графу, но не создают понятного меню для человека. Обычные DokuWiki-ссылки необходимы даже при наличии графа. Раздел, состоящий из отдельных страниц без точки входа, не считается корректно оформленным. Если в пакете несколько документов, их надо объединить в одну объяснимую структуру.

2. Какие блоки обязательны

Элемент	Главная страница wiki / стартовая страница раздела	Обычная содержательная страница	Назначение
Заголовок `====== … ======`	Да	Да	Понятное название документа
Путь навигации и ссылка на родительский раздел	Да (на главный каталог, если есть родитель)	Да	Переходы читателя без графа
Краткое описание, назначение и статус документа	Да	Да	Что описано, для кого и насколько утверждено
Оглавление и явные wiki-ссылки на дочерние/тематические страницы	Да	По смыслу, минимум ссылка на родителя и связанные материалы	Не допускать страниц-сирот
`~~NOCACHE~~`	Да	Да, если присутствует динамический блок	Снять риск кеширования ACL-зависимых блоков
`~~SHARIX_KNOWLEDGE_GRAPH~~`	Да	Нет, кроме осмысленных специальных страниц-обзоров	Визуальная карта знаний с фильтрами
`~~SHARIX_KNOWLEDGE_CATALOG~~`	Да	Нет, кроме страниц-каталогов	Текстовые ссылки на опубликованные доступные материалы
`~~SHARIX_KNOWLEDGE_RELATED~~`	Рекомендуется, если страница управляется ShariX Knowledge	Да	Соседи по связям для открытой страницы
Раздел «Связанные материалы» и ссылки назад/вперёд	Да	Да	Завершить маршрут чтения

Важно: каталог и граф плагина показывают опубликованные доступные текущему посетителю материалы соответствующей wiki, а не только текущий раздел. Нужное меню конкретного раздела пишется вручную обычными DokuWiki-ссылками. Один RELATED не заменяет GRAPH, CATALOG или меню.

Эти блоки требуют установленного и работоспособного плагина ShariX Knowledge с поддержкой графа (сборка 0.1.5+, включая исправленную 0.1.7). Для неуправляемых старых страниц автоматические связи могут отсутствовать. Не делать вид, что связность проверена только потому, что синтаксис распознан.

3. Каноническая стартовая страница раздела

Вместо фиктивных адресов подставить реальный namespace и действительные названия страниц. Код ниже — образец содержимого DokuWiki, а не буквальный текст для слепой вставки.

====== Название раздела ======
 
[[sharixopen:knowledge:start|База знаний]] · [[sharixopen:example:start|Название раздела]]
 
**Назначение:** что находится в разделе и кто его читатель.
**Статус:** draft / review / approved / deprecated; не путать с lifecycle.
 
===== С чего начать =====
  * [[sharixopen:example:concepts|Понятия и термины]] — введение.
  * [[sharixopen:example:usage|Сценарии использования]] — практическая часть.
  * [[sharixopen:example:setup|Настройка]] — руководство.
 
===== Граф знаний =====
~~NOCACHE~~
~~SHARIX_KNOWLEDGE_GRAPH~~
 
===== Каталог опубликованных документов =====
~~SHARIX_KNOWLEDGE_CATALOG~~
 
===== Связанные материалы =====
~~SHARIX_KNOWLEDGE_RELATED~~
 
[[sharixopen:knowledge:start|Вернуться к главной базе знаний]]

example выше только условный namespace; перед публикацией заменить его на реальные существующие или создаваемые страницы. В platform и joint заменять все адреса на соответствующие внутренние пространства, не оставляя открытые ссылки на выдуманные внутренние страницы.

4. Каноническая дочерняя страница

====== Название документа ======
 
[[sharixopen:knowledge:start|База знаний]] · [[sharixopen:example:start|Раздел]] · Текущая страница
 
**Назначение:** зачем нужен документ.
**Статус документа:** review. **Состояние разработки:** planned / in_progress / implemented / retired / unspecified.
 
===== Содержание =====
Конкретные проверяемые сведения. Для процесса — участники, условия, шаги и результат;
для сценария — акторы, предусловия и основной/альтернативный поток;
для настройки — предпосылки, действия, контроль и откат;
для термина — определение, контекст применения и ссылки на употребления.
 
===== Что читать дальше =====
  * [[sharixopen:example:another_page|Связанный документ]] — почему он относится к теме.
  * [[sharixopen:example:start|Вернуться в раздел]].
 
===== Связанные материалы =====
~~NOCACHE~~
~~SHARIX_KNOWLEDGE_RELATED~~

На реальной дочерней странице не вставлять GRAPH и CATALOG механически: эти блоки ставятся на главной/стартовой странице. Все три блока допустимы на странице-обзоре, как в стартовом шаблоне выше.

5. Метаданные графа и текст должны совпадать

В тексте	В `manifest.json`	Проверка
Дочерняя страница раздела	`extensions.taxonomy.parents` = реальный ID родительского документа	На странице есть ссылка на родителя; в графе — связь `contains`
Зависимость документа	`relations.depends_on` = ID требуемого документа	В тексте указано, в чём состоит зависимость, со ссылкой на страницу
Применимость, проверка, конфликт, замещение	`applies_to`, `verified_by`, `conflicts_with`, `supersedes`	Реальная, обоснованная связь и человекочитаемое объяснение
Тематический переход	`relations.related_to` = ID другой страницы	В содержании есть понятная читателю wiki-ссылка
Использование термина	`extensions.taxonomy.terms` = существующий ID термина	Термин объяснён или ведёт на словарь

Разрешённые ключи relations: applies_to, depends_on, supersedes, verified_by, conflicts_with, related_to. Рёбра contains строятся из taxonomy.parents; uses_term — из taxonomy.terms, а defines_term — из extensions.glossary. В версии плагина 0.1.7 обычные DokuWiki-ссылки в тексте не образуют автоматически рёбер links_to: они служат для читательской навигации, а для машинной связи укажите подтверждённое отношение по ID. Все рёбра строятся только для реально опубликованных метаданных страниц, доступных текущему читателю.

Если точная цель связи неизвестна — не выдумывать ID, URL или документ. Сохранить пояснение в тексте как требует уточнения, не создавать фальшивое ребро. Если у автора нет доступа к intrawiki, публичная страница не должна раскрывать внутреннюю структуру даже через метаданные.

6. Для Open, Platform и Joint

Область	`area`	Формат адресов	Где читатель увидит блоки
ShariX Open	`open`	`sharixopen:…`	Публичная wiki, только открытые данные
ShariX Platform	`platform`	`sharixplatform:platform:…`	Только intrawiki, с учётом ACL
Совместная зона	`joint`	`sharixplatform:joint:…`	Также только intrawiki, с учётом ACL

Публичный автор может создать структуру предложения для platform или joint, описав только известные ему открытые факты. Не создавать в Open страницу с реальными названиями или сведениями закрытых процессов. Достаточно безопасного описания предложения, status=review и передачи через разрешённую модерацию. Администратор intrawiki подтвердит детали, права и ссылки перед публикацией.

Читайте также правила областей и модерации.

7. Обязательная проверка результата ИИ

Перед передачей ZIP автор или ИИ обязан проверить сами тексты, а не только manifest.json:

Есть одна логическая точка входа; для каждого поддерева — своя start-страница, если материалов несколько.
На каждой странице есть заголовок, вводная часть, статус и ссылки на родителя/близкие материалы; обратный путь работает.
На каждой стартовой странице буквально присутствуют три отдельные строки GRAPH, CATALOG, NOCACHE (полный синтаксис выше), а также реальные текстовые ссылки на дочерние страницы.
На каждой дочерней странице буквально присутствует RELATED и NOCACHE (полный синтаксис выше) и обычные wiki-ссылки.
Каждый документ имеет правильные id, page, area, sha256 и (только для обновления) настоящий base_sha256 текущего опубликованного текста.
В extensions.taxonomy.parents и relations используются действительные ID соответствующих опубликованных или включённых в тот же ZIP документов; никакой вымышленной внутренней структуры.
Указанные в тексте адреса соответствуют page и действительно существуют либо создаются тем же пакетом. Проверить, что не появляются красные ссылки после публикации.
Все специальные блоки в примерах помещены внутрь блоков исходного кода и поэтому не должны запускаться как виджеты внутри технической документации. На реальных страницах директивы располагаются вне кодовых блоков на отдельных строках.
Граф, каталог и блок связанных материалов после публикации действительно отображаются для обычного читателя с учётом ACL. Проверка ZIP не заменяет эту проверку браузером.

Если хоть один пункт нельзя проверить без доступа к wiki — явно отметить непроверенное, не писать «всё прошло». Разрешается передать пакет на модерацию как проект, но не объявлять результат опубликованным и корректным.

Связанные материалы

Главная страница правил · Точный формат архива · Инструкция для ИИ · Общая модель знаний

Нет опубликованных связей для этой страницы.