Markdown документация, база знаний

Установка

Размещение всех комопнентов модуля, добавление страниц, инфоблоков и т.п. можно сделать на этапе установки модуля и именно этот вариант рекомендуется. Но если вы решили установить все вручную, то делать это следует по шагам.

По умолчанию будем считать что вы делаете раздел с документациями, по факту это может быть и база знаний, разницы в установке нету.

Директория с документацией

В первую очередь определяемся с директорией в коотрой должны буть все документации, прдеположим это будет /doc/. Создаем в ней 2 файла - .seciton.php и index.php.

Содержимое файла .section.php

<?
$sSectionName = "Документация";
$arDirProperties = Array(
   "description" => "Документация",
   "keywords" => "Документация"
);
?>

Тип инфоблока тоже назовем doc, поэтому в параметрах вызова комопнента указываем "IBLOCK_TYPE" => "doc".

В данном случае мы настраиваем компоненты с поддержко ЧПУ. Обратите внимание парамтер "SEF_FOLDER" => "/doc/"

Содержимое файла .index.php

<?
require($_SERVER["DOCUMENT_ROOT"]."/bitrix/header.php");

$APPLICATION->SetPageProperty("title", "Документация");
$APPLICATION->SetPageProperty("keywords", "...");
$APPLICATION->SetPageProperty("description", "...");
$APPLICATION->SetTitle("Документация");

?>
<?
	$APPLICATION->IncludeComponent(
	"bxmaker:mdbase", 
	".default", 
	array(
		"IBLOCK_TYPE" => "doc",
		"CACHE_TYPE" => "A",
		"CACHE_TIME" => 60*60*24*10,
		"CACHE_GROUPS" => "Y",
		"COMPONENT_TEMPLATE" => ".default",
		"SEF_MODE" => "Y",
		"SEF_FOLDER" => "/doc/",
		"COMPOSITE_FRAME_MODE" => "A",
		"COMPOSITE_FRAME_TYPE" => "AUTO",
		"SEF_URL_TEMPLATES" => array(
			"index" => "",
			"item" => "#IBLOCK_CODE#/",
			"section" => "#IBLOCK_CODE#/#SECTION_CODE_PATH#/",
			"detail" => "#IBLOCK_CODE#/#SECTION_CODE_PATH#/#ELEMENT_CODE#/",
			"search" => "#IBLOCK_CODE#/search/",
		)
	),
	false
);
?>
<?require($_SERVER["DOCUMENT_ROOT"]."/bitrix/footer.php");?>

Логотип и ссылки в шапке

Чтобы изменить логотип в шапке шаблона, используемого для раздела с докумнетациями, необходимо в настрйоках модуля загрузить свой логотип.

Ссылка с логотипа по умолчанию ведет на корневой адрес сайта - /.

Слово документация может быть заменено без правки шаблона, для этого неоходимо задать свойство раздела в котором размещена документация или база знаний. Нужно либо через публичную часть указать другое название через свойства раздела или вручную в исходном коде страницы в файле /doc/index.php. Код свойства - MDBASE_ROOT_NAME

$APPLICATION->SetDirProperty('MDBASE_ROOT_NAME', 'База знаний');

Ссылка по умолчанию указана как /doc/, чтобы ее изменить достаточно указать свойство раздела с кодом MDBASE_ROOT_URL.

$APPLICATION->SetDirProperty('MDBASE_ROOT_URL', '/custom_doc/');

Добавление правила для ЧПУ

Добавляем правило через админку битркиса, или добавляем вручную в файл /urlrewrite.php в корне сайта. Доабвляем запись:

<?php
$arUrlRewrite=array (
//...
array (
    'CONDITION' => '#^/doc/#',
    'RULE' => '',
    'ID' => 'bxmaker:mdbase',
    'PATH' => '/doc/index.php',
    'SORT' => 100,
  ),
//...
);
?>

Шаблон сайта

Подключаем шаблон модуля к текущему сайту, для этого в админке идем в *Рабочий стол / Настройки / Настройки продукта / Сайты / Список сайтов*, находим нужный и добавляем шаблон.

  1. Выбираем шаблон - "BXmaker. Markdown документация, база знаний"
  2. Сортировку задаем - 1
  3. Тип условия - Для папки или файла
  4. Условие - /doc/

Скриншот добавления шаблона для документации к сайту

Инфоблоки

Для раздела документаций используется тип инфоблока, то есть в разделе с документациями отображаются документации только одного типа.

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

Добавление типа инфоблока

При добавлении типа инфоблока, необходимо указать его идентификатор - doc. Поставить галочку - Использовать древовидный классификатор элементов по разделам.

И на вкладке дополнительно заполнить поле - "Файл с формой редактирования элемента". В качестве значения необходимо указать путь /bitrix/modules/bxmaker.mdbase/include/iblock_element_form.php

Добавление инфоблока

Далее в добавленный ранее тип инфоблока добавляем сами инфоблоки. Со следующими настройками.

  1. Включаем активность инфоблока
  2. Указываем символьный код
  3. Указываем название
  4. Указываем привязку к текущему сайту
  5. Отключаем индексацию разделов
  6. URL страницы информационного блока - #SITE_DIR#doc/#IBLOCK_CODE#/
  7. URL страницы раздела - #SITE_DIR#doc/#IBLOCK_CODE#/#SECTION_CODE_PATH#/
  8. URL страницы детального просмотра - #SITE_DIR#doc/#IBLOCK_CODE#/#SECTION_CODE_PATH#/#ELEMENT_CODE#/
  9. Даем доступ для всех пользователей [2] - Чтение
  10. Включаем обазательность указания символьного кода для жлемнетов и для разделов

Добавление записи

Далее можно добавить запись в добавленый инфоблок. Указываем название, символьный код, активность и сам текст в формате markdown. Также можно указать униклаьные тексты в мета тегах, задав их на вкладке seo.

После сохранения записи, кэш компонентов обновится и документация станет доступной.

4.jpg

5.jpg

Представление в публичной части

После всех проделанных операций, в публичной части документации должны отображаться примерно так

Скриншот раздела документаций

Скриншот страницы с записью в документации

Скриншот поиска по документации