Онлайн-попередній перегляд Markdown і збірка локальних документів відповідають на різні запитання. Онлайн-попередній перегляд запитує: «Чи чисто цей Markdown відображається в загальному попередньому перегляді та чи є очевидні проблеми авторства?» Локальна збірка документів запитує: «Чи працює цей вміст у нашій фактичній системі документації?»
Обидва корисні. Помилка полягає в тому, що просять один шар виконувати роботу іншого. Converty Markdown Validator — це швидка рання перевірка. Ваша збірка локальних документів залишається остаточною перевіркою середовища, коли має значення рендеринг на платформі.
Використовуйте онлайн-попередній перегляд для швидкого перегляду чернетки
Онлайн-попередній перегляд Markdown корисний, коли вміст ще рухається. Розділ README, примітка до випуску, запис у журналі змін або документ підтримки можна перевірити, перш ніж він стане запитом на отримання або збіркою документів.
Попередній перегляд допомагає вловити:
- поламані на вигляд столи
- питання структури рубрики
- відсутній альтернативний текст
- порожні посилання
- кодові огорожі без маркування
- необроблений HTML, який потребує перегляду
Це етап, на якому швидкий зворотний зв’язок має більше значення, ніж повна точність середовища.
Використовуйте збірку локальних документів для остаточного відтворення
Локальна збірка документів є правильним рівнем, коли кінцева платформа має спеціальну поведінку. Багато систем документації перетворюють Markdown за допомогою компонентів, маршрутизації, підсвічування синтаксису, користувальницьких виносок або стилю, що залежить від фреймворку.
Лише локальна збірка може показати, чи працює вміст у цьому середовищі. Якщо на сторінці використовуються користувальницькі компоненти, імпортовані фрагменти або спеціальне рендеринг продукту, попередній перегляд у браузері має бути першим, а не останнім.
Найкращий робочий процес використовує обидва
Використовуйте онлайн-попередній перегляд, щоб очистити джерело. Використовуйте локальну збірку, щоб перевірити призначення.
Ця послідовність економить час, оскільки локальна збірка більше не виявляє основних помилок Markdown. Він може зосередитися на специфічній для платформи поведінці, яку він унікально здатний перевірити.
Щоб отримати практичний робочий процес ранньої перевірки, прочитайте Як попередньо переглянути GitHub-Flavored Markdown перед тим, як зафіксувати це. Про передачу продуктів і документів прочитайте Як команди продуктів і документів можуть переглядати розмітку без втрати форматування.
Відкрийте Markdown Validator, якщо вам потрібен швидкий рівень онлайн-попереднього перегляду, перш ніж перемістити той самий вміст у збірку локальних документів або попередній перегляд остаточної публікації.
