使用 Markdown 为您的 iOS 应用生成帮助中心！

您只需要在 GitHub 上编写您的文档，并在您的应用程序中安装本库。SupportDocs 的自定义 GitHub Action 和 GitHub Pages 将处理其余部分。

✅更新 11/20/20：SupportDocs 现已可用！感谢您检查它！😄

目录

• 工作原理
• 安装
  • 设置 GitHub 仓库
  • 安装库
    • CocoaPods
    • Swift Package Manager
• 示例项目
• 使用方法
  • 使用 GitHub 仓库
    • 添加和编辑文档
    • 文档标签
    • 扩展文档
  • 使用库
    • SwiftUI
    • UIKit
    • 结果
• 自定义
  • 文档渲染
    • 颜色
    • 自定义 HTML
  • 库
    • 示例
    • 类别
    • 导航栏
    • 进度条
    • 列表样式
    • 导航视图样式
    • 其他
• 作者
• 许可
• 注意

如何工作

1. 在GitHub上用Markdown撰写文档
2. GitHub Pages会将其转换为HTML并免费托管
3. 一个自定义的GitHub操作将为您生成JSON数据源
4. SupportDocs库将下载JSON并将其显示给您的用户！

SupportDocs库是用SwiftUI编写的，因此仅适用于iOS 13及以上。

安装

安装SupportDocs需要两步

1. 设置您撰写和托管文档的GitHub仓库
2. 在您的应用程序中安装库

设置GitHub仓库

这里将是您撰写文档的位置。GitHub Pages将您的Markdown转换为HTML，然后自定义的GitHub操作将自动将网页编译成一个JSON文件。

1. 滚动到页面顶部并点击 使用此模板
2. 输入仓库名称--这可以是你想要的任何名称
3. 确保它设置为 Public（如果您使用的是免费的GitHub版本，GitHub Pages仅适用于公共仓库）
4. 确保选中 包含所有分支。这一点非常重要。
5. 点击 从模板创建仓库
6. 在你的新仓库中，点击 设置 选项卡
7. 滚动到GitHub Pages部分，然后选择 DataSource 分支和 / (root) 文件夹。然后点击 保存。
8. GitHub仓库的工作到此完成！现在可以在应用程序中安装库。

安装库

这是您的用户将看到的实际界面。您可以使用您喜欢的任何方式安装，比如 CocoaPods 或 Swift Package Manager。

CocoaPods

CocoaPods 是 Cocoa 项目的依赖管理工具。要使用和安装说明，请访问其网站。要使用 CocoaPods 将 SupportDocs 安装到您的 Xcode 项目中，请在您的 Podfile 中添加它

pod 'SupportDocs'

Swift Package Manager

Swift Package Manager 集成于 Xcode，使用起来非常方便。

1. 前往您的项目设置
2. 点击您的项目
3. 切换到 Swift Packages 选项卡
4. 点击 + 按钮
5. 在文本框中输入 https://github.com/aheze/SupportDocs
6. 点击 下一步
7. 在文本框中填写最新的版本，1.0.0，并保留 Up to Next Major 选中状态。
8. 点击 下一步
9. 点击 完成，操作即已完成！

示例项目

在 示例 文件夹中查看示例项目！它包含一个游乐场，您可以在其中尝试 SupportDocs 的显示方式。

使用方法

SupportDocs 非常简单易用，分为两部分：GitHub 仓库和您的应用程序中的库。

GitHub 仓库是您添加和编辑文档的地方，使用 Markdown 格式。它是在线编辑的，因此您可以在任何时间进行编辑，始终向用户展示最新信息。所有文档都会编译成一个单独的 JSON 文件，您需要将此文件的 URL 传递给库。库是展现在您的用户面前的，需要在您的应用程序中。它仅需要 JSON 文件的 URL，您可以使用 SwiftUI 或 UIKit 将其嵌入。

使用 GitHub 仓库

在您之前设置的全新仓库中，切换 到 DataSource 分支。示例文档位于 Sample-Boba、Sample-FastFood 和 Sample-Smoothies 文件夹中 -- 探索一番。以下为指南：

文档可以放置在根目录或子文件夹中。然而，我们建议您使用文件夹来组织文档。在示例中：

• 标记为 boba 的文档位于 Sample-Boba 文件夹中
• 标记为 fastFood 的文档位于 Sample-FastFood 文件夹中
• 标记为 smoothies 的文档位于 Sample-Smoothies 文件夹中

添加和编辑文档

• 要添加文档，请点击 创建新文件 按钮。
• 如果您想将其添加到文件夹中，首先导航到该文件夹，然后点击 创建新文件 按钮。
  • 如果您想 创建新文件夹，请点击 创建新文件 -- 然后，在文件名中，首先输入文件夹名称，然后输入一个斜杠（/），接着是文件名（例如：fastFood/Burgers.md）。更多信息请点击 这里。

添加文档	在 Sample-Boba 子文件夹中添加文档

然后，为了使文档适合使用SupportDocs，您必须满足以下条件

• 文档扩展名必须以.md结尾
• 在文档顶部（这称为首页），您需要填写标题。我们强烈建议您也添加标签。

---
title: Buy blue boba
tags: boba
---

标题将在SupportDocs库中每行列表中显示。一旦您选择了一行，它也将作为导航栏的标题显示。

首页之后的---都是文档内容。您可以使用Markdown来编写您的文档。

Markdown	结果
--- title: Buy blue boba tags: boba --- # Buy blue boba Blue and yummy. Buy this at [google.com](https://google.com) 1. Eat 2. Eat 3. Eat 4. Eat 5. Eat 

标记文档

使用标签，您可以获得很大程度的控制，以决定在库中显示哪些内容。要添加标签，只需在标签下填写即可。例如，查看DataSource分支中的这个示例文档。

---
title: Buy blue boba
tags: boba
---

这个文档有boba标签。正如您所预料，DataSource分支中还有其他标记有boba的文档。

这里有一张图显示了DataSource分支中的文档、标题和标签。

一旦您的文档添加了标签，您就可以在库中选择显示哪些文档以及隐藏哪些文档。这在本库自定义文档的分类部分有详细说明。

使用图书馆

图书馆是在您的应用程序中嵌入的视图，以及用户看到的。但是在展示之前，您首先需要获取数据源URL！前往您全新的仓库的DataSource分支，滚动到README，并将URL复制下来。

自定义GitHub Action已为您生成此URL，请妥善保存！

现在您可以在应用程序中展示这个视图了。您可以使用SwiftUI或UIKit，下面是需要编写的最少的代码。

SwiftUI

import SwiftUI
import SupportDocs

struct SwiftUIExampleViewMinimalCode: View {
    let dataSource = URL(string: "https://raw.githubusercontent.com/aheze/MyHelpCenter/DataSource/_data/supportdocs_datasource.json")!
    @State var supportDocsPresented = false
    
    var body: some View {
        Button("Present SupportDocs from SwiftUI!") { supportDocsPresented = true }
        .sheet(isPresented: $supportDocsPresented, content: {
            SupportDocsView(dataSourceURL: dataSource, isPresented: $supportDocsPresented)
        })
    }
}

UIKit

import UIKit
import SupportDocs

class UIKitExampleControllerMinimalCode: UIViewController {
    
    /**
     Connect this inside the storyboard.
     
     This is just for demo purposes, so it's not connected yet.
     */
    @IBAction func presentButtonPressed(_ sender: Any) {
        
        let dataSource = URL(string: "https://raw.githubusercontent.com/aheze/MyHelpCenter/DataSource/_data/supportdocs_datasource.json")!
        
        let supportDocsViewController = SupportDocsViewController(dataSourceURL: dataSource)
        self.present(supportDocsViewController, animated: true, completion: nil)
    }
}

结果

现在你已经建立了库并使其正常工作，可以前往库自定义部分，根据需要自定义SupportDocs。也许可以添加一个“关闭”按钮，或者仅显示带有特定标签的文档。

自定义

您可以对要显示的内容有很强的控制权。

• 文档渲染：如何渲染Markdown。如果您想，可以自定义颜色并添加自己的HTML！
• 库：用户看到的导航基础。几乎可以自定义任何内容，从分类到导航栏颜色。

文档渲染	库

作者

SupportDocs是由A. Zheng和H. Kamran维护的项目。

许可权

MIT License

Copyright (c) 2020 A. Zheng and H. Kamran

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

备注

示例库

您可以使用SupportDocs在此处找到示例仓库。

搜索

即将推出搜索功能！我正在尝试调试动画，但最迟应在12/10完成。

暗黑模式

SupportDocs默认支持暗黑模式！您无需做任何事情。