SteamPress

Language Build Status Code Coverage MIT License

SteamPress 是一个 Swift 博客引擎，可与 Vapor 框架结合使用，将博客部署到运行在 Vapor 之上的网站。它使用 Fluent，因此可以与任何具有 Fluent 驱动程序的数据库一起使用。它还包含一个 Markdown Provider，允许您以 Markdown 格式编写文章，然后使用 Leaf 渲染 Markdown。

该博客既可以用作您网站的根目录（即出现在 https://www.acme.org），也可以用作子路径（即 https://www.acme.org/blog/）。

在 https://github.com/brokenhandsio/SteamPressExample 中，有一个示例展示了它如何在网站中工作（以及它在 Leaf 模板方面需要什么，以及传递给它们的参数）。

特性

如何使用

添加为依赖项

SteamPress 很容易与您的应用程序集成。 有两个提供程序为 PostgreSQL 或 MySQL 提供实现。您也可以自由编写自己的集成。通常，您会选择其中一个实现，因为它提供了数据库的存储库集成。在此示例中，我们使用 Postgres。

首先，将提供程序添加到您的 Package.swift 依赖项中

dependencies: [
    // ...
    .package(name: "SteampressFluentPostgres", url: "https://github.com/brokenhandsio/steampress-fluent-postgres.git", from: "1.0.0"),
],

然后将其作为依赖项添加到您的应用程序目标

.target(name: "App",
    dependencies: [
        // ...
        "SteampressFluentPostgres"
    ])

在 configure.swift 中，导入提供程序

import SteampressFluentPostgres

接下来，在您的服务中注册提供程序

try services.register(SteamPressFluentPostgresProvider())

提供程序要求您将 SteamPress 的模型添加到您的迁移中

/// Configure migrations
var migrations = MigrationConfig()
// ...
migrations.add(model: BlogTag.self, database: .psql)
migrations.add(model: BlogUser.self, database: .psql)
migrations.add(model: BlogPost.self, database: .psql)
migrations.add(model: BlogPostTagPivot.self, database: .psql)
// Optional but recommended - this will create an admin user for you to login with
migrations.add(migration: BlogAdminUser.self, database: .psql)
services.register(migrations)

手动设置

首先将 SteamPress 添加到您的 Package.swift 依赖项中

dependencies: [
    // ...,
    .package(name: "SteamPress", url: "https://github.com/brokenhandsio/SteamPress", from: "1.0.0")
]

然后作为依赖项添加到您的目标中

.target(name: "App",
    dependencies: [
        // ...
        "SteamPress"
    ])

这将为您注册路由。 您必须为您的服务提供不同存储库类型的实现

services.register(MyTagRepository(), as: BlogTagRepository.self)
services.register(MyUserRepository(), as: BlogUserRepository.self)
services.register(MyPostRepository(), as: BlogPostRepository.self)

然后您可以将 SteamPress 提供程序注册到您的服务中

let steampressProvider = SteamPress.Provider()
try services.register(steampressProvider)

集成

SteamPress 在登录时提供“记住我”功能，以延长会话的持续时间。 为了使它工作，您必须注册中间件

var middlewares = MiddlewareConfig()
// ...
middlewares.use(BlogRememberMeMiddleware.self)
middlewares.use(SessionsMiddleware.self)
services.register(middlewares)

注意： 必须在注册 SessionsMiddleware 之前注册此中间件。

SteamPress 使用 PasswordVerifier 协议来检查密码。 Vapor 没有为此提供默认的 BCrypt 实现，因此您必须自己注册

config.prefer(BCryptDigest.self, for: PasswordVerifier.self)

最后，如果您希望在您的博客 Leaf 模板中使用 #markdown() 标签，您必须注册它。 还有一个分页标签，使分页变得容易

 var tags = LeafTagConfig.default()
tags.use(Markdown(), as: "markdown")
let paginatorTag = PaginatorTag(paginationLabel: "Blog Posts")
tags.use(paginatorTag, as: PaginatorTag.name)
services.register(tags)

配置

您可以将许多配置选项传递给提供程序以配置 SteamPress

要配置这些，您可以将它们传递给提供程序。 例如

let feedInformation = FeedInformation(
    title: "The SteamPress Blog", 
    description: "SteamPress is an open-source blogging engine written for Vapor in Swift", 
    copyright: "Released under the MIT licence", 
    imageURL: "https://user-images.githubusercontent.com/9938337/29742058-ed41dcc0-8a6f-11e7-9cfc-680501cdfb97.png")
try services.register(SteamPressFluentPostgresProvider(blogPath: "blog", feedInformation: feedInformation, postsPerPage: 5))

此外，您应该将 WEBSITE_URL 环境变量设置为您网站的根地址，例如 https://www.steampress.io。 这用于在整个 SteamPress 中设置各种参数。

登录

首次启动 SteamPress 时，如果您启用了 BlogAdminUser 迁移，则会在数据库中创建一个管理员用户。 用户名是 admin，密码将打印到您应用程序的日志中。 建议您在网站启动并运行后首次登录时立即重置密码。

评论

SteamPress 当前支持使用 Disqus 作为评论引擎。 要使用 Disqus，请启动应用程序，并将环境变量 BLOG_DISQUS_NAME 设置为您的 Disqus 站点的名称。 （您可以从您的 Disqus 管理面板获取您的 Disqus 站点的名称）

这会将其传递给博客索引（blog.leaf）、博客文章（blogpost.leaf）、作者页面（profile.leaf）和标签页面（tag.leaf）的 Leaf 模板，以便您可以在需要时包含它。 如果您想手动设置评论，您可以自己完成，只需包含您的提供程序所需的文件。 这主要是为 示例网站 提供简单的配置。

Open Graph 和 Twitter Card 支持

SteamPress 支持 Open Graph 和 Twitter Card。 博客文章页面上下文将以 ISO 8601 格式传递创建日期和上次编辑日期（如果适用），以支持 Open Graph 文章，参数为 createdDateNumeric 和 lastEditedDateNumeric。

博客文章页面还将传递许多其他有用的参数，用于 Open Graph 和 Twitter Card。 请参阅下面的 blogpost.leaf 部分。

站点的 Twitter 句柄可以通过 BLOG_SITE_TWITTER_HANDLE 环境变量进行配置（站点的 Twitter 句柄不带 @）。 如果设置，这将按照如下所述注入到公共页面中。 这是用于 Twitter Card 的 twitter:site 标签

Google Analytics 支持

SteamPress 使您可以轻松地将 Google Analytics 集成到您的博客中。 只需启动应用程序，并将 BLOG_GOOGLE_ANALYTICS_IDENTIFIER 环境变量设置为您的 Google Analytics 标识符。 （您可以从 Google Analytics 控制台获取您的标识符，它看起来类似于 UA-12345678-1）

这会将 googleAnalyticsIdentifier 参数传递给 pageInformation 变量中的所有公共页面，您可以包含它，然后使用 示例网站的 javascript 进行集成。

Atom/RSS 支持

SteamPress 自动提供用于注册 RSS 阅读器的端点，可以使用 RSS 2.0 或 Atom 1.0。 这些端点可以在博客的 atom.xml 和 rss.xml 路径中找到； 例如，如果您的博客位于 https://www.example.com/blog，则 atom feed 将显示在 https://wwww.example.com/blog/atom.xml。 这些默认情况下有效，但您可能需要配置一些字段。 这些字段通过传递给提供程序的 FeedInformation 参数进行配置。 配置选项为

搜索支持

SteamPress 内置了博客搜索。 它将在您的博客路径下注册一个路由 /search，您可以通过该路由发送一个查询，使用键 term 来搜索博客。

预期的 Leaf 模板

SteamPress 期望在 Resources/Views 中的正确位置有许多 Leaf 模板文件。 所有这些文件都应该位于 blog 目录中，管理模板文件位于 admin 目录中。 有关 SteamPress 如何与 Leaf 模板配合使用的示例，请参阅 示例 SteamPress 网站。

对于每个公共 Leaf 模板，将传入一个带有以下信息的 pageInformation 参数

对于管理页面，pageInformation 参数具有以下信息

您的 Resources/View 目录的基本结构应为

主博客站点

blog.leaf

这是博客的索引页。 它将收到的参数是

blogpost.leaf

这是用于查看单个完整博客文章的页面。 设置的参数为

tag.leaf

这是标签页面。一篇博客文章可以标记多个标签，一个标签也可以被标记在多篇博客文章上。此页面通常用于查看该标签下的所有文章。参数如下：

profile.leaf

这是用户个人资料页面。通常用于查看用户撰写的所有文章以及关于用户的一些信息。可以设置的参数如下：

tags.leaf

这是用于查看博客上所有标签的页面。它为博客提供更多导航点，并且在用户从标签的 URL 中删除标签时提供一个页面。可以传递给它的参数是：

authors.leaf

这是用于查看博客上所有作者的页面。它为用户提供了一个有用的页面，可以查看所有为该站点做出贡献的人员。

search.leaf

这是将显示搜索结果的页面。除了标准参数之外，它还有许多参数：

login.leaf

这是用于登录到博客管理部分的页面。参数如下：

管理站点

index.leaf

这是博客的主要管理页面，您可以在其中创建和编辑用户和文章。此页面的参数是：

resetPassword.leaf

如果您需要重置密码，将被重定向到此页面。参数如下：

createPost.leaf

这是用于创建新博客文章或编辑现有博客文章的页面。此页面的参数是：

createUser.leaf

这是用于创建新用户或编辑现有用户的页面。参数如下：

POST 路由

管理站点有许多 POST 路由用于创建和编辑用户等，否则您将收到错误。

本节需要填写，但您可以查看代码中的控制器以了解它们应该是什么，或参阅 示例站点。

Markdown 标签

Markdown 标签允许您在 Leaf 文件中将 Markdown 呈现为 HTML。 要使用，只需简单地使用

#markdown(myObject.markdownContent)

这将把对象 myObject 的 markdownContent 转换为 HTML（您将 myObject 作为参数传递给您的 Leaf 视图）。 它在底层使用 Github Flavoured Markdown，但有关更多详细信息，请参见 Leaf Markdown repo。

API

SteamPress 还包含一个 API，用于访问某些可能有用的内容。 当前端点为：