All you need to do is write your documents on GitHub, and install the library in your app. SupportDocs' custom GitHub Action and GitHub Pages will take care of the rest.
The SupportDocs library is written in SwiftUI, so it's only for iOS 13 and above.
Installing SupportDocs takes two steps:
This will be where you write your documents. GitHub Pages will translate your Markdown into HTML, and a custom GitHub Action will automatically compile the web pages into a JSON file.
Public(If you are using the free version of GitHub, GitHub Pages only works for public repos)
DataSourcebranch and / (root) folder. Then click Save.
This is the actual interface that your users will see. You can install using CocoaPods or Swift Package Manager, whichever one you prefer.
CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To install SupportDocs into your Xcode project using CocoaPods, add it in your
The Swift Package Manager is built into Xcode, which makes it really easy to use.
https://github.com/aheze/SupportDocsin the text field
1.1.0, in the text field. Leave Up to Next Major selected.
Check out the example project in the
Example folder! It contains a playground where you can play around with how SupportDocs is displayed.
SupportDocs is pretty simple to use, with two parts: the GitHub repository and the library in your app.
The GitHub repository is where you add and edit your documents using Markdown. This is online, so you can edit at any time and always show the latest information to your users. All your documents are compiled into a single JSON file, the URL of which you'll pass into the library. The library is what's displayed to your users, in your app. All it needs is the URL of the JSON file, and you can either use SwiftUI or UIKit to embed it.
In you brand new repository that you set up earlier, switch to the
DataSource branch. The example documents are inside the
Sample-Smoothies folders -- take a look around. Here's a guide:
.github/workflowsis for the GitHub Action, for compiling your documents into JSON
Imagescontains the images used in the example documents
Sample-Bobacontains all documents tagged with boba
Sample-FastFoodcontains all documents tagged with fastFood
Sample-Smoothiescontains all documents tagged with smoothies
_datacontains the generated data source URL
_layoutsis for GitHub Pages to convert your Markdown into HTML
_sassis where you can customize the look of the HTML, including light and dark mode colors
_scriptscontains the script used by the GitHub Action, as well as the README template. This template is what you should edit if you want to change the README at all -- if you change it directly, your changes will be overriden.
.gitignoreis for git to ignore unnecessary files
404.mdis the 404 document that will be displayed if your URLs are wrong. You can also pass this into
options.other.error404in case your data source URL fails.
README.mdis for your reference. It contains a link to the data source URL, and a table of contents that shows all your documents. Do not edit this file directly -- instead, edit the file in
_config.ymlsets the default theme, "Primer," for GitHub Pages. We recommend that you don't change this, as we customized dark mode specifically for the "Primer" theme -- you'll need to configure
assets/css/main.scssif you use your own theme.
Documents can be placed in the root directory or a subfolder. However, we recommmend that you use folders to organize your documents. In the example,
bobaare in the
fastFoodare in the
smoothiesare in the
/), followed by the filename (Example:
fastFood/Burgers.md). Read more here.
|Add a Document||Add a Document in the |
Then, to make the document eligible for SupportDocs, you must fulfill these criteria:
title. We strongly suggest you add tags too.
title: Buy blue boba tags: boba
title is what will be displayed in each row of the list, in the SupportDocs library. Once you select a row, it's also what's shown as the title of the navigation bar.
Everything after the
--- of the front matter is your document's content. You use Markdown to write your documents.
title: Buy blue boba
Buy blue boba
Blue and yummy. Buy this at google.com
This document has the tag
Here is a graphic which shows the documents, titles, and tags in the
Once your documents have tags, you can choose to show which documents to show and which ones to hide, in the library. This is covered in the Categories section of the library customization documentation.
Using the Library
The library is the view that you embed in your app, and what the user sees. But before you present it, you need to get the data source URL first! Go to your brand-new repo's
The custom GitHub Action generated this URL for you, so keep it safe!
Now you can present the view in your app. You can use SwiftUI or UIKit, and here's the least code that you need to write for it to work.
Now that you have the library set up and working, you can hop on over to the library customization section and customize SupportDocs to your liking. Perhaps add a "Dismiss" button or only show documents with specific tags.
You get a lot of control over what to display.
You can find an example repository generated from SupportDocs here.
SupportDocs does not collect any data. We provide this note to help you fill out your App Privacy Details.
Testing on Apple Silicon / Big Sur
On my MacBook Pro M1 running Big Sur 11.0.1, I get a crash when loading the web page on iOS 13 simulators. It works fine for iOS 14, and the crash doesn't happen at all when I run on my Intel Mac. I'm pretty sure that this won't be a problem for actual devices, but keep in mind that you might run into some issues during testing. Apple is still polishing up Big Sur.
SupportDocs supports Dark Mode right out of the box! You don't need to do anything.