65.9K
CodeProject 正在变化。 阅读更多。
Home

使用 DocuPanel 显示您的 Markdown 文档

mat35770
starIconstarIconstarIconstarIcon
emptyStarIcon
starIcon

4.73/5 (9投票s)

2017 年 3 月 22 日

Apache

5分钟阅读

viewsIcon

14267

本教程将解释如何使用 DocuPanel 在 WPF 应用程序中集成 Markdown 文档。

引言

当您开发应用程序时，您可能还会编写用户手册或文档来解释您的软件如何工作。您可以选择将其存储在互联网上或直接包含在您的应用程序中。如果您选择将文档集成到您的软件中，您将花费大量时间来创建一个视图并构建一个能够正确显示帮助的结构。

幸运的是，有一个工具可以为您完成这项工作。DocuPanel 是一个开源项目，它可以很好地、快速地将您的 Markdown 文档集成到您的 WPF 应用程序中。它是一个您可以添加到应用程序中的包，它会浏览您的文档文件以进行索引和分析，从而提供一个您可以添加到视图中的 UserControl。

本文旨在逐步解释如何添加 DocuPanel 以及如何使其与您自己的文档一起工作。

为了更好地理解该项目，您可以阅读 文档。

源代码托管在 GitHub 上。

必备组件

  • 安装 NuGet DocuPanel。
  • 在您的配置管理器中将平台修改为 x64。
  • 用 Markdown 编写的文档。

DocuPanel 使用 Chromium Browser CefSharp，因此您的应用程序必须是 x64 而不是 Any CPU 或 x86。但是，您也可以 下载 源代码并将其构建为 x86。

通过示例使用

让我们通过一个例子来解释 DocuPanel。此示例的源代码也可在 GitHub 上找到。

步骤 1 - 将帮助文件添加到您的项目中

  • 在您的项目中创建一个目录，您将在其中存储 markdown 文件。

    在我们的示例中，目录是 Documentation，我们的文档文件都是 .md 格式。

  • 您需要创建一个索引文件，其中包含有关如何组织文档的所有信息。在我们的示例中，索引文件是 book.json，但您可以将其命名为任何您喜欢的名称。唯一的强制要求是它必须是 json 类型，并放置在 Documentation 目录的 **根目录** 下。下面我将解释如何组织这个文件。
  • 文件应具有以下属性

您也可以创建一个子目录，以便您可以按照自己的意愿组织文件，在这里我们创建了一个名为 Configuration 的文件夹，其中包含 configuration.md 文件。

每个文件都必须具有 **唯一名称**，这一点非常重要。

步骤 2 - 创建您的索引 json 文件

为了了解文档的架构以及如何显示其页面，我们需要创建一个索引文件，其中包含所有这些信息。

此示例的 book.json 的内容是以下代码

{
  "Title": "Documentation",
  "Author": "RHEA System S.A.",
  "PagePath": "home.md",
  "Sections": [
    {
      "Name": "Getting Started",
      "PagePath": "getting-started.md"
    },
    {
      "Name": "How does it work",      
      "Sections": [
        {
          "Name": "Searches",
          "PagePath": "searches.md"
        },
        {
          "Name": "Configuration",
          "Sections": [
            {
              "Name": "Configuration",
              "PagePath": "Configuration\\configuration.md"
            }
          ]
        }
      ],
      "PagePath": "how-does-it-work.md"
    },
    {
      "Name": "License",
      "PagePath": "license.md"
    },
    {
      "Name": "Support",
      "Sections":[],
      "PagePath": "support.md"
    }
  ]
}

代码给出了以下层级结构

让我们解释一下代码

在 DocuPanel 中，treeView 的每个实体都称为 section。一个 section 可以关联到一个 Markdown 文件的路径，在这种情况下，当用户选择该 section 时，将显示关联的页面。一个 section 可以包含其他 sections，例如 How does it work 和 Configuration 包含子节，因此它们会显示为文件夹图标。在 Json 文件中，Sections 属性与其中的子节一起出现。

其他节显示为绿色页面，因为它们只包含关联的页面。

  • Title 是您文档的标题。
  • Author 是文档的作者。可以为空。
  • PagePath 是与该节关联的页面的相对路径。请注意，一个 section 不一定包含 PagePath。例如，一个节可以只包含子页面，就像我们在示例中对 Configuration 所做的那样。
  • Sections 是子节的列表。
  • Name 是 DocuPanel 显示的名称。两个节可以具有相同的名称，在本例中，我们有两个名为 Configuration 的节。

Title 和 Author 参数只能设置一次，因为它们提供了有关整个文档的信息。

每个节都有 Name、Sections、PagePath 参数。如果一个参数为空，您不必编写它。在上面的代码中，我们为 Support 节写了 "Sections":[]，但我们没有为 License 节写任何内容。

步骤 3 - 将 DocuPanel 添加到您的视图

我们的示例项目包含一个视图，该视图是一个简单的窗口。要集成 DocuPanel，我们添加以下 XAML 代码

<docuPanel:DocumentationView 
PathDocumentationIndex="C:\Projects\DocuPanel\DocuPanelSupport\bin\x64\Debug\Documentation\book.json"
RootAppData="Users\<userName>\AppData\Local\<YourAppDataFolder>"
UpdateIndexation="true"/>

PathDocumentationIndex：类型为 string 的属性，对应于文档索引文件的路径。据我所知，它必须在文档的根目录。

RootAppData：类型为 string 的属性，对应于应用程序数据文件夹的路径。DocuPanel 将在此路径下创建一个名为 DocuPanel 的目录来存储其数据。

UpdateIndexation：类型为 bool 的属性，指示是否需要更新索引。
如果为 true，DocuPanel 将浏览索引中指定的所有文件，并将它们转换为 HTML（如果它们尚不存在）。DocuPanel 将您的 Markdown 文件转换为 HTML 文件，以便 CefSharp 显示。搜索索引也将使用新的文档内容进行更新。请注意，如果您想更新文件的内容，要考虑更改，您必须从应用程序数据文件夹中删除 HTML 文件。

第一次使用 DocuPanel 以及每次更改文档时，都需要将此属性设置为 true。

在 示例 中，属性绑定到视图模型，以展示如何使用 MVVM 模式动态更改值。

结论

现在您应该可以在您的视图中看到 DocuPanel，能够浏览不同的页面并执行搜索。我希望本教程能帮助您将此项目集成到您的项目中。

如果您在此教程或使用过程中遇到任何问题，请 告知我们。

参考文献

DocuPanel 在 Concurrent Design Platform 4 和 RHEA GROUP 的其他项目中都有使用。

项目中使用的工具如下

关注点

DocuPanel 是我为开源项目做出的第一个贡献，我很享受开发初始版本的过程。如果您有任何改进它的想法，欢迎您的帮助。请随时贡献，不要犹豫联系我们或创建一个 pull request。

© . All rights reserved.