Инструмент для управления документами в формате Markdown

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

Пример

Документация по фреймворку SummerPHP.

Архитектура

• Исходные файлы (src/) и скомпилированные файлы (dist/) хранятся отдельно, что упрощает развёртывание.
• Файлы исходного кода размещаются в соответствующих папках согласно их иерархической структуре; скомпилированные файлы помещаются в каталог dist, имена файлов представляют собой MD5-хеш исходных путей, чтобы избежать дублирования.
• Поддерживается инкрементная компиляция: изменения отслеживаются с помощью MD5, и только изменённые файлы подвергаются компиляции.
• Автоматически генерируются каталоги без необходимости ручного создания.
• Можно настроить порядок файлов: перед именем файла можно указать число, которое будет определять порядок отображения в каталоге, но не будет отображаться в самом каталоге.

Компоненты

• Markdown в HTML: parsedown (без проверки безопасности, быстрая скорость).
• Highlight.js для подсветки кода.
• Класс инструментов PHP (tool/Dir.php) для обхода папки с исходными файлами Markdown.
• Класс инструментов PHP (tool/Html.php) для генерации HTML-кода левой панели каталога.

Использование

• Поместите файлы Markdown в папку src, используя те же имена для файлов и каталогов, которые будут использоваться в окончательном древовидном каталоге.
• Добавьте префикс к именам каталогов или файлов для упорядоченного отображения в каталогах, формат префикса: __\d+_, например, _01_xxx.md. В конечном каталоге префиксы не отображаются.
• Запустите интерпретатор PHP, выполнив файл compile.php (в Windows рекомендуется использовать php7+: path/to/php.exe compile.php), который преобразует файлы Markdown в HTML и размещает их в папке dist.
• Nginx/Apache сервер:
  • Создайте виртуальную машину (например, doc.hearu.top).
  • Направьте корневой каталог виртуальной машины на папку dist.
  • Установите index.html в качестве файла входа виртуальной машины.
  • Запустите сервер, и вы сможете получить доступ к doc.hearu.top в браузере (для локальной настройки необходимо изменить файл hosts).

  // Пример конфигурации nginx (обратите внимание: команда root указывает на каталог dist, при доступе через браузер не следует указывать dist в URL, иначе статические файлы, такие как js/css, будут недоступны)
  server {
          listen       80;
          server_name  www.test3.com;
  
  		index index.html;
  
          location / {
              root D:/server/code/markdown/dist;
          }
      }

Маленькие хитрости

• Добавьте pre-commit hook в git, который будет выполнять команду компиляции PHP перед каждым коммитом, избавляя от необходимости вручную запускать команду компиляции каждый раз.
• Добавьте post-push hook в git, чтобы сделать _book репозиторием git и автоматически развертывать его в корневом каталоге сервера после каждого push.
• Стиль кода и таблиц (стиль GitHub) уже реализован в файле dist/static/my.css, и нет необходимости перекомпилировать после изменений.

Примечание

• Программа записывает хэш содержимого после каждой компиляции в файл file_sign.php, и если файл не был изменен, повторная компиляция не производится. Удаление file_sign.php приводит к полной перекомпиляции.
• Во время компиляции программа копирует файлы Markdown из корневого каталога, содержащие строку index, в скомпилированный файл dist/index.html, который используется в качестве страницы по умолчанию при просмотре в браузере без указания index.html.