Нотация для публикации документов и понятий это комплексный подход к написанию и публикации документации, сохраняя документы в разметке в кодовой базе и публикуя их непосредственно в Notion или через общедоступные веб-сайты. Он подчеркивает бесшовный рабочий процесс, где документация живет с кодом, доступна для поиска и извлекает выгоду из функций AI, поиска и форматирования Notion. Инструмент предоставляет интерфейс CLI (нотацию) для отправки документов разметки в Notion, настройки интеграции Notion и управления тем, как документация всплывает на поверхность для конечных пользователей.
Как работает нотация
- Напишите документацию в простой разметке вместе с вашим кодом.
- Создайте страницу Notion, чтобы разместить документацию и получить ключ API для Notion.
- Настройте файл Notation.toml с помощью секрета Notion API и имени родительской страницы.
- Запустите корабль нотаций, чтобы опубликовать свои документы в Notion, где вы можете использовать функции Notion, такие как поиск ИИ, форматирование и таблица содержимого.
- Необязательно отправлять документы в качестве общедоступного веб-сайта, используя интеграции, такие как Super.so или аналогичные инструменты.
Начало работы
- Установите инструмент нотации и поместите двоичный код в свой PATH.
- Редактировать ~/.notation/Notation.toml, чтобы включить ваш секрет Notion и уникальное имя родительской страницы.
- Создайте интеграцию Notion в рабочем пространстве Notion и вставьте секрет в Notation.toml.
- Запуск судна нотации -src </path/to/your/docs> для публикации.
- Просмотр документов в Notion, с дополнительным публичным развертыванием веб-сайта.
Варианты развертывания
- Документация по внутреннему рабочему пространству
- Публичный хостинг страницы понятия
- Полное развертывание веб-сайта с помощью таких сервисов, как Super.so
FAQ / Советы
- Родитель страница в Notation.toml определяет, где новые страницы появятся в Notion.
- Вы можете включить intro.md в корневой версии для отображения на родительской странице напрямую.
- Вы можете передавать аргументы CLI, такие как -title и -emoji, для настройки метаданных страницы при доставке.
Безопасность и конфиденциальность
- Рабочий процесс опирается на токен интеграции Notion; храните свой секрет в безопасности и не разоблачайте его публично.
- Содержание документации остается в пределах понятия с опубликованной поверхностью в зависимости от настроек совместного использования понятия.
Основные характеристики
- Процесс работы с документацией на основе Markdown интегрирован с кодом
- Публикуйте документы непосредственно в Notion из локальной установки Notation
- Интеграция понятий с секретным управлением API через Notation.toml
- Встроенный контроль иерархии страниц Notion через родитель page и intro.md
- Опциональное развертывание документов в качестве общедоступного веб-сайта через внешние службы
- Улучшенный поиск и богатые возможности форматирования через Notion
- Легкий, без тяжелой фронтенд-инструмента или отдельной CMS
Как использовать нотацию
- Напишите свою документацию в разметке в репо, используя intro.md для прямого родительского контента, если это необходимо.
- Создайте интеграцию понятий и получите секретный ключ.
- Поместите секрет и имя вашей целевой родительской страницы в ~/.notation/Notation.toml в разделе [упоминание].
- Запуск судна нотации -src/path/to/docs для публикации в Notion.
- Получите доступ к документам в Notion, используйте поиск ИИ и делитесь или публикуйте по мере необходимости.
