文档模块

什么是文档模块？

文档模块是ABP的一个应用程序模块。它简化了软件文档管理。该模块是免费且开源的。

集成

目前，文档模块允许您将文档存储在GitHub和文件系统中。

托管

文档模块是一个应用程序模块，不提供任何托管解决方案。您可以在本地或云上托管您的文档。

版本管理

当您使用GitHub存储文档时，文档模块支持版本管理。如果您的文档有多个版本，用户界面上会有一个下拉框供切换版本。如果您选择文件系统存储文档，则不支持多版本。

ABP的文档 也使用此模块。

文档模块遵循模块架构最佳实践指南。

安装

本文档涵盖 Entity Framework Core 提供程序，但您也可以选择 MongoDB 作为数据库提供程序。

1- 创建应用程序

如果您没有现有的ABP项目，您可以 从abp.io网站的入门页面生成CLI命令 并运行它，或者运行以下命令：

abp new Acme.MyProject

2- 运行空应用程序

下载项目后，解压ZIP文件并打开 Acme.MyProject.sln。您将看到解决方案包含 Application、Application.Contracts、DbMigrator、Domain、Domain.Shared、EntityFrameworkCore、HttpApi、HttpApi.Client 和 Web 项目。右键单击 Acme.MyProject.Web 项目并设为启动项目。

数据库连接字符串位于您的 Acme.MyProject.Web 项目的 appsettings.json 中。如果您有不同的数据库配置，请更改连接字符串。

{
  "ConnectionStrings": {
    "Default": "Server=(LocalDb)\\MSSQLLocalDB;Database=MyProject;Trusted_Connection=True"
  }
}

运行 Acme.MyProject.DbMigrator 项目，它将负责应用数据库迁移和种子数据。数据库 MyProject 将在您的数据库服务器中创建。

现在，一个空的ABP项目已经创建好了！您可以运行您的项目并查看空网站。

登录网站时，请输入 admin 作为用户名，1q2w3E* 作为密码。

3- 安装模块

文档模块的包托管在NuGet上。有4个包需要安装到您的应用程序中。每个包都必须安装到相应的项目。

3.1- 使用ABP CLI

建议使用ABP CLI安装模块，在解决方案文件（.sln）目录下打开CMD窗口，并运行以下命令：

abp add-module Volo.Docs

3.2- 手动安装

或者，您也可以手动将nuget包安装到每个项目：

• 将 Volo.Docs.Domain nuget包安装到 Acme.MyProject.Domain 项目。

  dotnet add package Volo.Docs.Domain
  

• 将 Volo.Docs.EntityFrameworkCore nuget包安装到 Acme.MyProject.EntityFrameworkCore 项目。

  dotnet add package Volo.Docs.EntityFrameworkCore
  

• 将 Volo.Docs.Application nuget包安装到 Acme.MyProject.Application 项目。

  dotnet add package Volo.Docs.Application
  

• 将 Volo.Docs.Web nuget包安装到 Acme.MyProject.Web 项目。

  dotnet add package Volo.Docs.Web
  

3.2.1- 添加模块依赖

如果一个ABP模块依赖于另一个模块，则必须声明 [DependsOn] 属性。每个模块都必须添加到相应项目的 [DependsOn] 属性中。

• 打开 MyProjectDomainModule.cs，并添加 typeof(DocsDomainModule)，如下所示；

  [DependsOn(
          typeof(DocsDomainModule),
          typeof(AbpIdentityDomainModule),
          typeof(AbpAuditingModule),
          typeof(BackgroundJobsDomainModule),
          typeof(AbpAuditLoggingDomainModule)
          )]
      public class MyProjectDomainModule : AbpModule
      {
          //...
      }
  

• 打开 MyProjectEntityFrameworkCoreModule.cs，并添加 typeof(DocsEntityFrameworkCoreModule)，如下所示；

      [DependsOn(
          typeof(DocsEntityFrameworkCoreModule),
          typeof(MyProjectDomainModule),
          typeof(AbpIdentityEntityFrameworkCoreModule),
          typeof(AbpPermissionManagementEntityFrameworkCoreModule),
          typeof(AbpSettingManagementEntityFrameworkCoreModule),
          typeof(AbpEntityFrameworkCoreSqlServerModule),
          typeof(BackgroundJobsEntityFrameworkCoreModule),
          typeof(AbpAuditLoggingEntityFrameworkCoreModule)
          )]
      public class MyProjectEntityFrameworkCoreModule : AbpModule
      {
          //...
      }
  

• 打开 MyProjectApplicationModule.cs，并添加 typeof(DocsApplicationModule)，如下所示；

     [DependsOn(
          typeof(DocsApplicationModule),
          typeof(MyProjectDomainModule),
          typeof(AbpIdentityApplicationModule))]
      public class MyProjectApplicationModule : AbpModule
      {
          public override void ConfigureServices(ServiceConfigurationContext context)
          {
              Configure<AbpPermissionOptions>(options =>
              {
                  options.DefinitionProviders.Add<MyProjectPermissionDefinitionProvider>();
              });
          }
      }
  

• 打开 MyProjectWebModule.cs，并添加 typeof(DocsWebModule)，如下所示；

     [DependsOn(
          typeof(DocsWebModule),
          typeof(MyProjectApplicationModule),
          typeof(MyProjectEntityFrameworkCoreModule),
          typeof(AbpAutofacModule),
          typeof(AbpIdentityWebModule),
          typeof(AbpAccountWebModule),
          typeof(AbpAspNetCoreMvcUiBasicThemeModule)
      )]
      public class MyProjectWebModule : AbpModule
      {
          //...
      }
  

3.2.2- 添加NPM包

打开 package.json 并添加 @abp/docs": "^5.0.0，如下所示：

  {
      "version": "1.0.0",
      "name": "my-app",
      "private": true,
      "dependencies": {
          "@abp/aspnetcore.mvc.ui.theme.basic": "^5.0.0",
          "@abp/docs": "^5.0.0"
      }
  }

然后在 Acme.MyProject.Web 项目文件夹中打开命令行终端并运行以下命令：

abp install-libs

4- 数据库集成

4.1- Entity Framework 集成

如果您选择Entity Framework作为数据库提供程序，则需要配置文档模块。为此；

• 打开 MyProjectMigrationsDbContext.cs 并在 OnModelCreating() 中添加 builder.ConfigureDocs()。

  public class MyProjectMigrationsDbContext : AbpDbContext<MyProjectMigrationsDbContext>
    {
        public MyProjectMigrationsDbContext(DbContextOptions<MyProjectMigrationsDbContext> options)
            : base(options)
        {
  
        }
  
        protected override void OnModelCreating(ModelBuilder builder)
        {
            base.OnModelCreating(builder);
  
            /* Include modules to your migration db context */
  
            builder.ConfigurePermissionManagement();
            builder.ConfigureSettingManagement();
            builder.ConfigureBackgroundJobs();
            builder.ConfigureAuditLogging();
            builder.ConfigureIdentity();
            builder.ConfigureIdentityServer();
            builder.ConfigureFeatureManagement();
            builder.ConfigureTenantManagement();
            builder.ConfigureDocs(); //添加此行以配置文档模块
  
            /* Configure customizations for entities from the modules included  */
  
            builder.Entity<IdentityUser>(b =>
            {
                b.ConfigureCustomUserProperties();
            });
  
            /* Configure your own tables/entities inside the ConfigureQaDoc method */
  
            builder.ConfigureMyProject();
        }
    }
  

• 在 Visual Studio 中打开 Package Manager Console，并选择 Acme.MyProject.EntityFrameworkCore 作为默认项目。然后编写以下命令为文档模块添加迁移。

  add-migration Added_Docs_Module
  

  当命令成功执行后，您将在 Acme.MyProject.EntityFrameworkCore\Migrations 文件夹中看到一个名为 20181221111621_Added_Docs_Module 的新迁移文件。

  现在，为文档模块的数据库更改更新数据库。为此，在 Visual Studio 的 Package Manager Console 中运行以下代码。确保 Acme.MyProject.EntityFrameworkCore 仍是默认项目。

  update-database
  

  最后，您可以检查数据库以查看新创建的表。例如，您可以看到 DocsProjects 表必须已添加到您的数据库中。

5- 链接文档模块

文档模块的默认路由是；

/Documents

要将文档模块链接添加到您的应用程序菜单；

• 打开 MyProjectMenuContributor.cs 并将以下行添加到 ConfigureMainMenuAsync() 方法中。

  context.Menu.Items.Add(new ApplicationMenuItem("MyProject.Docs", l["Menu:Docs"], "/Documents"));
  

  MyProjectMenuContributor.cs 的最终样式

      private async Task ConfigureMainMenuAsync(MenuConfigurationContext context)
      {
          var l = context.ServiceProvider.GetRequiredService<IStringLocalizer<MyProjectResource>>();
  
          context.Menu.Items.Insert(0, new ApplicationMenuItem("MyProject.Home", l["Menu:Home"], "/"));
  
          context.Menu.Items.Add(new ApplicationMenuItem("MyProject.Docs", l["Menu:Docs"], "/Documents"));
      }
  

Menu:Docs 关键字是一个本地化键。要本地化菜单文本，请打开项目 Acme.MyProject.Domain 中的 Localization\MyProject\en.json。并添加以下行

"Menu:Docs": "Documents"

en.json 的最终样式

{
  "culture": "en",
  "texts": {
    "Menu:Home": "Home",
    "Welcome": "Welcome",
    "LongWelcomeMessage": "Welcome to the application. This is a startup project based on the ABP. For more information, visit abp.io.",
    "Menu:Docs": "Documents"
  }
}

文档模块的新菜单项已添加到菜单中。运行您的Web应用程序并浏览到 http://localhost:YOUR_PORT_NUMBER/documents URL。

您将看到一个警告，内容为；

There are no projects yet!

由于我们尚未添加任何项目，此警告是正常的。

6- 添加新的文档项目

打开数据库中的 DocsProjects，并插入一条具有以下字段信息的新记录；

• 名称：文档的显示名称，将在网页上显示。
• 短名称：简短且URL友好的名称，将在您的文档URL中使用。
• 格式：文档的格式（对于Markdown：md，对于HTML：html）
• 默认文档名称：初始页面的文档。
• 导航文档名称：用于导航菜单（索引）的文档。
• 最低版本：显示文档的最低版本。低于此版本的文档将不会列出。
• 文档存储类型：文档的来源（对于GitHub：GitHub，对于文件系统：FileSystem）
• 额外属性：一个序列化的 JSON，用于存储所选 DocumentStoreType 的特殊配置。
• 主网站URL：当用户单击文档模块页面上的徽标时将跳转的URL。您可以简单地设置为 / 以链接到您的网站根地址。
• 最新版本分支名称：这是GitHub的配置。它是用于检索文档的分支名称。您可以将其设置为 master。

"GitHub"的示例项目记录

您可以使用 ABP GitHub文档来配置您的GitHub文档存储。

• 名称：ABP (GitHub)

• 短名称：abp

• 格式：md

• 默认文档名称：Index

• 导航文档名称：docs-nav.json

• 最低版本：<NULL>（无最低版本）

• 文档存储类型：GitHub

• 额外属性：

  {"GitHubRootUrl":"https://github.com/abpframework/abp/tree/{version}/docs","GitHubAccessToken":"***","GitHubUserAgent":""}
  

  请注意，GitHubAccessToken 用 *** 遮蔽了。这是一个私有令牌，您必须从GitHub获取。请参阅 https://help.github.com/articles/creating-a-personal-access-token-for-the-command-line/

• 主网站URL：/

• 最新版本分支名称：dev

对于 SQL 数据库，您可以使用下面的 T-SQL 命令将指定的示例插入到您的 DocsProjects 表中：

INSERT [dbo].[DocsProjects] ([Id], [Name], [ShortName], [Format], [DefaultDocumentName], [NavigationDocumentName], [MinimumVersion], [DocumentStoreType], [ExtraProperties], [MainWebsiteUrl], [LatestVersionBranchName], [ParametersDocumentName], [ConcurrencyStamp]) VALUES (N'12f21123-e08e-4f15-bedb-ae0b2d939659', N'ABP (GitHub)', N'abp', N'md', N'Index', N'docs-nav.json', NULL, N'GitHub', N'{"GitHubRootUrl":"https://github.com/abpframework/abp/tree/{version}/docs","GitHubAccessToken":"","GitHubUserAgent":""}', N'/', N'dev', N'', N'12f21123e08e4f15bedbae0b2d939659')

请注意，GitHubAccessToken 被遮蔽了。这是一个私有令牌，您必须获取自己的令牌并替换 *** 字符串。

现在您可以运行应用程序并导航到 /Documents。

"FileSystem"的示例项目记录

您可以使用 ABP GitHub文档来配置您的GitHub文档存储。

• 名称：ABP (FileSystem)

• 短名称：abp

• 格式：md

• 默认文档名称：Index

• 导航文档名称：docs-nav.json

• 最低版本：<NULL>（无最低版本）

• 文档存储类型：FileSystem

• 额外属性：

  {"Path":"C:\\Github\\abp\\docs"}
  

  请注意，Path 必须替换为您本地的文档目录。您可以从 https://github.com/abpframework/abp/tree/master/docs 获取ABP的文档，并复制到 C:\\Github\\abp\\docs 目录以使其工作。

• 主网站URL：/

• 最新版本分支名称：<NULL>

对于 SQL 数据库，您可以使用下面的 T-SQL 命令将指定的示例插入到您的 DocsProjects 表中：

INSERT [dbo].[DocsProjects] ([Id], [Name], [ShortName], [Format], [DefaultDocumentName], [NavigationDocumentName], [MinimumVersion], [DocumentStoreType], [ExtraProperties], [MainWebsiteUrl], [LatestVersionBranchName], [ParametersDocumentName], [ConcurrencyStamp]) VALUES (N'12f21123-e08e-4f15-bedb-ae0b2d939659', N'ABP (FileSystem)', N'abp', N'md', N'Index', N'docs-nav.json', NULL, N'FileSystem', N'{"Path":"C:\\Github\\abp\\docs"}', N'/', NULL, N'', N'12f21123e08e4f15bedbae0b2d939659')

添加上述示例项目之一并运行应用程序。在菜单中您将看到 Documents 链接，单击菜单链接打开文档页面。

到目前为止，我们已经从abp.io网站创建了一个新的应用程序，并为其准备好使用文档模块。

7- 创建新文档

在示例项目记录中，您看到 格式 指定为 md，这指的是 Markdown。您可以点击以下链接查看markdown速查表；

https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

ABP文档模块可以将markdown渲染为HTML。

现在让我们看一个markdown格式的示例文档。

# 这是一个标题

欢迎使用文档模块。

## 这是一个子标题

 [这是一个链接](https://abp.io) 

![这是一张图片](https://abp.io/assets/my-image.png)

## 这是一个代码块

```csharp
public class Person
{
    public string Name { get; set; }

    public string Address { get; set; }
}
```

作为一个例子，您可以查看ABP的文档：

https://github.com/abpframework/abp/blob/master/docs/en/

条件部分功能（使用Scriban）

文档模块使用 Scriban 来条件性地显示或隐藏文档的某些部分。为了使用该功能，您必须为每种语言创建一个JSON文件作为参数文档。它将包含所有的键值对及其显示名称。

例如，en/docs-params.json：

{
    "parameters": [{
        "name": "UI",
        "displayName": "UI",
  "values": {
   "MVC": "MVC / Razor Pages",
   "NG": "Angular"
  }
    },
 {
        "name": "DB",
        "displayName": "Database",
  "values": {
   "EF": "Entity Framework Core",
   "Mongo": "MongoDB"   
  }
    },
 {
        "name": "Tiered",
        "displayName": "Tiered",
  "values": {
   "No": "Not Tiered",
   "Yes": "Tiered"
  }
    }]
}

由于并非您项目中的每个文档都可能具有部分或不需要所有这些参数，因此您必须在文档的任何位置声明将使用哪些参数来对文档进行分区，作为一个JSON块。

例如 Getting-Started.md：

​json //[doc-params] { "UI": ["MVC","NG"], "DB": ["EF", "Mongo"], "Tiered": ["Yes", "No"] } ​

此部分将在渲染期间自动删除。当然，这些键值必须与参数文档中的匹配。

现在您可以使用 Scriban 语法在文档中创建部分。

例如：

{{ if UI == "NG" }}

* `-u` 参数指定UI框架，本例中为 `angular`。

{{ end }}

{{ if DB == "Mongo" }}

* `-d` 参数指定数据库提供程序，本例中为 `mongodb`。

{{ end }}

{{ if Tiered == "Yes" }}

* `--tiered` 参数用于创建N层解决方案，其中身份验证服务器、UI和API层在物理上是分离的。

{{ end }}

您也可以在文本中使用变量，在其键后添加 _Value 后缀：

本文档假定您更喜欢使用 **** 作为UI框架，使用 **** 作为数据库提供程序。

此外，如果希望获取当前文档的语言代码或版本（这对于创建重定向到另一个域中的另一个文档系统的链接可能很有用），则 Document_Language_Code 和 Document_Version 键是预定义的。

重要提示：Scriban使用"和"作为语法。因此，如果您要在文档中使用这些（例如一个Angular文档），则必须使用转义块。有关更多信息，请参阅 Scriban文档。

8- 创建导航文档

导航文档是文档页面的主菜单。它位于页面的左侧。它是一个 JSON 文件。查看以下示例导航文档以了解其结构。

{  
   "items":[  
      {  
         "text":"Sample Menu Item - 1",
         "items":[  
            {  
               "text":"Sample Menu Item - 1.1",
               "items":[  
                  {  
                     "text":"Sample Menu Item - 1.1.1",
                     "path":"SampleMenuItem_1_1_1.md"
                  }
               ]
            },
            {  
               "text":"Sample Menu Item - 1.2",
               "items":[  
                  {  
                     "text":"Sample Menu Item - 1.2.1",
                     "path":"SampleMenuItem_1_2_1.md"
                  },
                  {  
                     "text":"Sample Menu Item - 1.2.2",
                     "path":"SampleMenuItem_1_2_2.md"
                  }
               ]
            }
         ]
      },
      {  
         "text":"Sample Menu Item - 2",
         "items":[  
            {  
               "text":"Sample Menu Item - 2.1",
               "items":[  
                  {  
                     "text":"Sample Menu Item - 2.1.1",
                     "path":"SampleMenuItem_2_1_1.md"
                  }
               ]
            }
         ]
      }
   ]
}

上面的示例 JSON 文件将呈现为 HTML 导航菜单，如下所示。

最后，一个新的文档模块已添加到您的项目中，并从GitHub获取内容。

全文搜索（Elastic Search）

文档模块支持使用Elastic Search进行全文搜索。默认情况下未启用。您可以配置 DocsElasticSearchOptions 来启用它。

Configure<DocsElasticSearchOptions>(options =>
{
    options.Enable = true;
    options.IndexName = "your_index_name"; //默认IndexName是abp_documents
});

如果 Index 不存在，应用程序启动后会自动创建 Index。

DefaultElasticClientProvider 负责创建 IElasticClient。默认情况下，它从 IConfiguration 读取Elastic Search的 Url。 如果您的 IElasticClient 需要额外的配置，请使用覆盖 IElasticClientProvider 服务，并在依赖注入系统中替换它。

{
  "ElasticSearch": {
    "Url": "http://localhost:9200"
  }
}

行高亮

您可以将高亮应用于特定的代码行或一系列连续的行。 请参见以下示例：

 ```C# {3, 5}
 public class Book : Entity<Guid>
 {
     public string Name { get; set; }
     public string Surname { get; set; }
 }

public class Book : Entity<Guid>
{
    public string Name { get; set; }
    public string Surname { get; set; }
}

public class Book : Entity<Guid>
{
    public string Name { get; set; }
    public string Surname { get; set; }
}

## 引用下一篇和上一篇文档

**文档模块** 支持引用前一篇和后一篇文档。如果您有一系列彼此严格相关且需要按顺序阅读的文档，这将非常有用。

要从一个文档引用前一篇和后一篇文档，您应按如下方式指定文档标题及其路径：



指定下一篇和上一篇文档后，它们将出现在当前文档的末尾，如下图所示：

![](https://files.koudingke.cn/docs/abp-docs/zh-Hans/images/docs-referencing.png "")

## 单一项目模式

**单一项目模式** 允许您在应用程序中使用单个名称作为项目名称。如果您不考虑支持具有多个文档的多个项目，而是只有一个项目并且只想为其提供文档，这对您尤其有用。

您只需配置 `DocsUiOptions`，将单一项目模式设置为 **启用**，并定义一个常量项目名称：

```csharp
Configure<DocsUiOptions>(options => 
{
    options.RoutePrefix = "docs";
    options.SingleProjectMode.Enable = true;
    options.SingleProjectMode.ProjectName = "abp";
});

多语言模式

多语言模式 允许您显示一个下拉框，列出并显示所有文档语言，并在路由中配置相关语言。

它默认启用并支持多种语言，但如果您只考虑支持单一语言，并且不想在文档系统侧边栏中显示语言下拉框，您可以配置 DocsUiOptions 并将多语言模式支持设置为 false 来禁用它：

Configure<DocsUiOptions>(options => 
{
    options.MultiLanguageMode = false;
});

另请参阅

文档模块也可作为独立应用程序使用。查看 VoloDocs。