Со страницами Swift, Markdown и GitHub

Большинство крупных приложений имеют своего рода справочный центр, также известный как «база знаний». Вы знаете, «Чем мы можем вам помочь?» экраны.

Выполните поиск по запросу «программное обеспечение для базы знаний», и вы найдете бесчисленное множество сервисов, предлагающих эту функцию… но вы смотрели на их цены?

Если вы похожи на большинство известных мне разработчиков, вам, вероятно, не так уж много денег можно потратить на такую ​​небольшую часть вашего приложения. Серьезно, 999 долларов в месяц? Что ж, у меня хорошие новости - у вас уже есть все ресурсы, необходимые, чтобы сделать его самостоятельно, бесплатно! Я предполагаю, что у вас есть учетная запись GitHub, верно?

Вот что мы сделаем:

  • Справочный центр, который вы можете добавить в свое приложение
  • Источник данных для справочного центра, который вы напишете на GitHub.
  • В итоге вы получите что-то вроде этого:

Полный отказ от ответственности: мы будем использовать библиотеку с открытым исходным кодом, которую мой друг H. Кямран и я сделал за последние несколько месяцев. Это настраивает все, так что вам не нужно много писать. Это под лицензией MIT, так что не беспокойтесь об ответственности или о чем-то подобном.

Итак, приступим! Сначала перейдите в репозиторий SupportDocs, здесь:



aheze / SupportDocs
Создавайте справочные центры для ваших приложений iOS. Размещено на GitHub и всегда актуально. github.com



SupportDocs - это библиотека / рабочий процесс, которые возьмут на себя всю тяжелую работу. Имейте в виду, что здесь используется SwiftUI, поэтому в настоящее время он доступен только для iOS 13 и более поздних версий. Вот как это работает:

  1. Вы пишете справочные документы в Markdown, на GitHub
  2. Автоматически - страницы GitHub конвертируют их в HTML и размещают бесплатно.
  3. Автоматически - действие GitHub компилирует HTML в файл JSON.
  4. В своем приложении передайте URL-адрес JSON в библиотеку и покажите его своим пользователям.

Вы отвечаете за написание документов и вызов функции, которая представляет их в вашем приложении. Все остальное автоматизировано!

Сторона GitHub

Нам нужно будет настроить репозиторий GitHub, в который вы будете писать свои документы.

  1. Прокрутите вверх Страница SupportDocs и нажмите Use this template. Это сделает копию всего репозитория, который содержит код для GitHub Action и других ресурсов.
  2. Введите имя репозитория - это может быть что угодно.
  3. Убедитесь, что для него установлено значение Public (если в вашей учетной записи используется бесплатная версия GitHub, GitHub Pages работает только с общедоступными репозиториями).
  4. Обязательно проверьте Include all branches. Это действительно важно.
  5. Щелкните Create repository from template.
  6. В вашем новом репозитории перейдите на вкладку Settings.
  7. Прокрутите вниз до раздела GitHub Pages и выберите ветку DataSource и папку / (root). Затем нажмите Save, и готово для GitHub!

В новом репозитории переключитесь на ветку DataSource, щелкнув раскрывающийся список main и выбрав DataSource. Затем проверьте файлы в папках «Sample-Boba», «Sample-FastFood» и «Sample-Smoothies».

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

Чтобы добавить документы, нажмите кнопку Add file. Чтобы действие GitHub обнаружило их, необходимо убедиться, что:

  • Расширение документа заканчивается на .md.
  • Вверху документа (это называется вступительная статья) у вас есть кое-что для title. Я настоятельно рекомендую вам также добавить теги (подробнее об этом позже).

Не волнуйтесь, ваши пользователи не увидят главного - это только для GitHub Pages и GitHub Action. Они увидят только обработанную (нажмите кнопку Preview changes) уценку, которая находится после второго ---.

В любом случае, вы можете разместить свои документы где угодно, если они находятся в ветке DataSource - они могут быть в корневом каталоге, папке Sample-Boba, вашей собственной папке CoolHelpDocuments (вы можете создавать папки), что бы ни!

Теперь вернемся на главную страницу ветки DataSource. Скопируйте URL-адрес в верхней части README.

Здесь находится файл JSON. Всякий раз, когда вы вносите изменения в ветку DataSource, действие GitHub обновляет JSON, но URL-адрес всегда будет одним и тем же.

Скопировав URL-адрес, вы можете установить библиотеку в свое приложение!

Сторона приложения

Библиотека - это интерфейс, который увидят ваши пользователи, который будет примерно таким, в зависимости от того, насколько вы его настраиваете:

Вы можете использовать Swift Package Manager или CocoaPods для его установки. Выбор за вами, но я предпочитаю SPM, потому что он встроен в Xcode.

Для SPM добавьте это во вкладку Swift Packages. Полная инструкция здесь.

https://github.com/aheze/SupportDocs

Для CocoaPods просто добавьте это в свой Podfile:

pod 'SupportDocs'

Как только это будет сделано, вы можете представить библиотеку в своем приложении! Возьмите URL-адрес JSON, который вы скопировали ранее. Тогда вот как в SwiftUI:

А для UIKit:

Ну вот и все! Вот как это будет выглядеть:

Теперь, когда у вас все настроено и работает, вы можете настроить SupportDocs по своему вкусу - возможно, добавить кнопку «Закрыть» или показать документы только с определенными тегами.

Настройка визуализации документа

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

Настройка библиотеки

Это изменяет главный экран, который видят ваши пользователи, поэтому вы получаете много возможностей настройки. Вы можете получить доступ ко всем настраиваемым параметрам через структуру SupportOptions, которую вы можете передать в библиотеку.

Например, вы хотите добавить кнопку «Готово»?

В SwiftUI просто сделайте следующее:

Для UIKit это работает:

Все просто, правда? А теперь помните те теги, которые вы вставили на обложку? Как насчет того, чтобы показывать только те документы, которые помечены boba?

Для SwiftUI:

Для UIKit:

И это только начало. Вы можете найти все настраиваемые свойства здесь… или поэкспериментировать с примером проекта!

Заключение

Как разработчик, вы должны иметь дело с крайними сроками, EXC_BAD_ACCESS и т. Д.… И все это в условиях бюджетных ограничений.

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

Он выполняет свою работу, но, как и все, что делается за два дня, выглядит не очень хорошо… вот почему мы сделали SupportDocs. Я надеюсь, что этот проект поможет вам сэкономить время и деньги. Спасибо за чтение и удачного кодирования!