Build a Help Center for Your iOS App

With Swift, Markdown, and GitHub Pages

Image credit: Author

Most big apps have some sort of help center, also known as a “knowledge base.” You know, the “What can we help you with?” screens.

Search up “knowledge base software,” and you’ll find countless services that offer this functionality… but have you looked at their pricing?

If you’re like most developers I know, you probably don’t have that much to spend on such a small part of your app. Like seriously, $999 per month? Well, I have good news — you actually already have all the resources you need to make one yourself, for free! I’m assuming you have a GitHub account, right?

Here’s What We’ll Make:

• A help center that you can add to your app
• The data source for the help center, which you’ll write on GitHub
• You’ll end up with something like this:

Full disclaimer: We’ll be using an open-source library that my friend H. Kamran and I made over the past few months. This sets up everything so you don’t have to do much coding. It’s under the MIT License, so don’t worry about liability or anything.

So, let’s get started! First, go to the SupportDocs repository, here:

aheze/SupportDocs

SupportDocs is the library/workflow that’ll be doing all the heavy lifting. Keep in mind, this uses SwiftUI so it’s currently only for iOS 13 and above. Here’s how it works:

1. You write help documents in Markdown, on GitHub
2. Automatic — GitHub Pages will convert them into HTML and host it for free
3. Automatic — A GitHub Action will compile the HTML into a JSON file
4. In your app, pass the JSON URL to the library and display it to your users

You’re in charge of writing your documents and calling the function that presents them in your app. Everything else is automated!

The GitHub Side

We’ll need to set up the GitHub repository where you’ll write your documents.

1. Scroll up to the top of the SupportDocs page and click Use this template. This will make a copy of the entire repository, which contains the code for the GitHub Action and other assets.
2. Enter a repository name — this can be whatever you want.
3. Make sure it’s set to Public (if your account is using the free version of GitHub, GitHub Pages only works for public repos).
4. Make sure to check Include all branches. This is really important.
5. Click Create repository from template.
6. In your brand new repository, go to the Settings tab.
7. Scroll down to the GitHub Pages section, and select DataSource branch and / (root) folder. Then click Save, and that’s it for GitHub!

In your brand-new repository, switch to the DataSource branch by clicking the main dropdown and selecting DataSource. Then, check out the files inside the “Sample-Boba,” “Sample-FastFood,” and “Sample-Smoothies” folders.

You’ll find a bunch of markdown documents that describe different types of food. This is just for demo purposes — but they are actually the documents that will be shown to your users. You can replace them with your own guides/FAQs by editing them like any other file on GitHub: Just click the pencil icon in the top-right corner, and commit your changes when done.

To add documents, click the Add file button. For the GitHub Action to detect them, you must make sure that:

• The document extension ends in .md.
• At the top of the document (this is called the front matter), you have something for the title. I strongly suggest you add tags too (more on this later).

Don’t worry, your users won’t see the front matter — this is just for GitHub Pages and the GitHub Action. They’ll only see the rendered (click the Preview changes button) markdown that’s after the second ---.

What your users will see

Anyway, you can put your documents anywhere as long as they’re in the DataSource branch — they can be in the root directory, the “Sample-Boba” folder, your own “CoolHelpDocuments” folder (you can make folders), whatever!

Now, go back to the main page of the DataSource branch. Copy the URL that’s at the top of the README.

Copy this. Keep it safe, because the GitHub Action generated it for you!

This is where the JSON file is located. Whenever you make changes inside the DataSource branch, the GitHub Action will update the JSON, but the URL will always be the same.

Once you’ve copied your URL, you can install the library in your app!

The App Side

The library is the interface that your users will see, which will be something like this, depending on how much you customize it:

You can use either the Swift Package Manager or CocoaPods to install it. It’s up to you, but I prefer SPM because it’s built-in to Xcode.

For SPM, add this inside the Swift Packages tab. Full instructions here.

https://github.com/aheze/SupportDocs

For CocoaPods, just add this to your Podfile:

pod 'SupportDocs'

Once that’s done, you can present the library in your app! Grab the JSON URL that you copied earlier. Then, here’s how in SwiftUI:

And for UIKit:

Well, that’s it! Here’s how it will look:

Now that you’ve got everything set up and working, you might want to customize SupportDocs to your liking — perhaps add a “Dismiss” button or only show documents with specific tags.

Customizing the Document Rendering

This changes how the Markdown is rendered, like the background color of the page. Most likely, the default theme will work for you — but if you want to change it, here’s how.

Customizing the Library

This changes the main screen that your users see, so you get a lot of customizability. You can access all configurable options via the SupportOptions struct, which you can pass into the library.

For example, want to add a “Done” button?

In SwiftUI, just do this:

For UIKit, this works:

Simple, right? Now, remember those tags that you put in the front matter? How about only show documents that are tagged with boba?

For SwiftUI:

For UIKit:

And that’s just the beginning. You can find all the customizable properties here… or, play around with the example project!

Conclusion

As a developer, you have to deal with deadlines, EXC_BAD_ACCESS, and more… all while under budget constraints.

When I was making my first app, I was in a rush to get it done, so I slapped on a messy help center just a few days before submitting it to the App Store.

I made it myself because I can’t afford services like Zendesk

It gets the job done, but like anything made in two days, it doesn’t look very good… well, that’s why we made SupportDocs. I hope this project can help you save some time and money. Thanks for reading, and happy coding!