55

0

BookStack

使用 PHP 和 Laravel 创建文档/wiki 内容的平台

BookStack

GitHub 发布 执照 人群 构建状态 棉绒状态 可维护性

回购统计 不和谐 推特 YouTube

用于存储和组织信息和文档的平台。BookStack 的详细信息可以在官方网站https://www.bookstackapp.com/上找到。

📚项目定义

BookStack 是一个自以为是的 wiki 系统,它提供了一种愉快而简单的开箱即用体验。实例的新用户应该会发现体验直观,并且只需要基本的文字处理技能就可以参与在 BookStack 上创建内容。该平台应为需要的人提供高级电源功能,但不应干扰核心的简单用户体验。

BookStack 并非设计为可用于与上述声明不同的目的的可扩展平台。

在开发理念上,BookStack 采用轻松、开放、积极的方式。归根结底,这是由人们贡献自己的空闲时间开发和维护的免费软件。

🌟项目赞助商

下面显示的是我们的铜牌、银牌和金牌项目赞助商。非常感谢这些公司对项目的支持。注意:所列服务未经官方 BookStack 项目以任何方式进行测试、审查或支持。 查看所有赞助商

银牌赞助商

图表网 云上

铜牌赞助商

恒星托管

🛣️路线图

下面是 BookStack 的高级路线图视图,用于提供项目发展方向的方向感。这可能随时发生变化,并且不会反映许多功能和改进,这些功能和改进也将包含在此路线图的旅程中。有关即将发布的版本中包含的更详细的内容,您可以查看下面“发布过程”部分中定义的项目里程碑。

  • 平台 REST API - (大多数操作已实现,正在成熟)
    • 一个 REST API,至少涵盖对核心内容模型(书籍、章节、页面)的控制,以实现自动化和平台扩展。
  • 编辑对齐和审查(完成)
    • 审查页面编辑器,以实现更高的互操作性和功能对等性,同时考虑协作编辑的潜力。
  • 权限系统审查(进行中)
    • 改进权限的应用方式以及审查权限和角色系统的效率。
  • 安装和部署流程改造
    • 为用户创建一个简化且安全的流程,以减少开发要求(无 git 或作曲家要求)部署和更新 BookStack。

🚀发布版本控制和流程

每个 BookStack 版本都分配了一个基于日期的版本号,格式为 v<year>.<month>[.<optional_patch_number>]. 例如:

  • v20.12- 2020 年 12 月发布的新功能。
  • v21.06.2- 2021 年 6 月功能发布后的第二个补丁发布。

补丁版本通常相当小,主要用于修复,因此不太可能在更新时造成损坏。功能版本通常更大,除了修复和增强之外,还带来了新功能。这些版本更有可能在更新时引入重大更改,因此值得检查更新指南中的任何注释。

每个 BookStack 版本都会创建一个里程碑,并分配给它的问题和拉取请求,以定义该版本中的内容。里程碑被建立,然后一直工作直到完成,在一些测试和文档更新之后,将部署该版本。

功能发布和一些补丁发布将附有BookStack 博客上的帖子,其中将提供有关功能、更改和更新的更多详细信息,否则GitHub 发布页面将显示更改列表。您可以在此链接上注册以收到新 BookStack 博客文章的提醒(最多每周一次)。

🛠️开发与测试

BookStack 上的所有开发目前都在 development分支上完成。当需要发布时,development分支会合并到带有内置和缩小的 CSS 和 JS 的发布中,然后在其版本上标记。以下是当前的开发要求:

这个项目使用 SASS 进行 CSS 开发,它是与 JavaScript 一起使用一系列 npm 脚本构建的。以下 npm 命令可用于安装依赖项并运行构建任务:

# Install NPM Dependencies
npm install

# Build assets for development
npm run build

# Build and minify assets for production
npm run production

# Build for dev (With sourcemaps) and watch for changes
npm run dev

BookStack 有许多使用 Laravel 内置测试功能的集成测试,这些功能使用 PHPUnit。在应用程序配置中定义了一个 mysql_testing数据库,这是 PHPUnit 使用的。该数据库设置的数据库名称、用户名和密码均定义为 bookstack-test. 在测试之前,您必须创建该数据库和该组凭据。

测试数据库也需要事先迁移和播种。这可以通过以下命令完成:

php artisan migrate --database=mysql_testing
php artisan db:seed --class=DummyContentSeeder --database=mysql_testing

完成后,您可以 composer test在应用程序根目录中运行以运行所有测试。

📜代码标准

PHP 代码标准使用 PHP_CodeSniffer进行管理。使用PHPStanLarastan进行静态分析。以下命令可用于利用这些工具:

# Run code linting using PHP_CodeSniffer
composer lint

# As above, but show rule names in output
composer lint -- -s

# Auto-fix formatting & lint issues via PHP_CodeSniffer phpcbf
composer format

# Run static analysis via larastan/phpstan
composer check-static

如果提交 PR,按照我们的项目标准进行格式化将有助于清晰,但不要太担心使用/理解这些工具,因为我们总是可以在稍后阶段被我们的自动化工具拾取时解决问题。

🐋使用 Docker 进行开发

此存储库附带用于开发目的的 Docker Compose 配置。它将构建一个安装了所有需要的扩展的 PHP 映像,并启动一个 MySQL 服务器和一个节点映像来监视 UI 资产。

要开始使用,请确保您满足以下要求:

  • 安装了 Docker 和 Docker Compose
  • 您的用户是该 docker组的一部分

如果满足所有条件,您可以继续执行以下步骤:

  1. 复制 .env.example.env ,更改 APP_KEY为随机 32 字符字符串并设置 APP_ENVlocal.
  2. 确保端口 8080 未使用 ,否则更改 DEV_PORT为主机上的空闲端口。
  3. 运行 chgrp -R docker storage 。开发容器将 chown storage目录给 www-data容器内的用户,以便 BookStack 可以写入它。您需要在此处将组更改为主 docker机组,以免失去对 storage目录的访问权限。
  4. 运行 docker-compose up并等待,直到构建映像并完成所有数据库迁移。
  5. 您现在可以使用 admin@admin.compassword作为密码登录 localhost:8080(或指定的其他端口)。

如果需要,您将能够通过 docker-compose 运行任何工匠命令,如下所示:

docker-compose run app php artisan list

docker -compose 设置运行MailHog的实例并设置环境变量以将任何 BookStack 发送的电子邮件重定向到 MailHog。您可以通过 MailHog Web 界面查看此邮件 localhost:8025DEV_MAIL_PORT您可以通过设置环境变量来更改可以访问 MailHog 的端口。

运行测试

启动通用开发 Docker 后,迁移和播种测试数据库:

# This only needs to be done once
docker-compose run app php artisan migrate --database=mysql_testing
docker-compose run app php artisan db:seed --class=DummyContentSeeder --database=mysql_testing

迁移和播种数据库后,您可以像这样运行测试:

docker-compose run app php vendor/bin/phpunit

调试

docker-compose 设置附带 Xdebug,您可以在端口 9090 上收听。注意:对于某些编辑器,如 Visual Studio Code,您可能需要将工作区文件夹映射到 docker 容器中的 /app 文件夹才能工作。

🌎翻译

BookStack 中的文本翻译通过Crowdin 上的 BookStack 项目进行管理。一些字符串有冒号前缀的变量,例如 :userName. 保留这些值,因为它们将在运行时被替换。Crowdin 是提供翻译的首选方式,否则可以在 resources/lang路径中找到原始翻译文件。

如果您希望将新语言添加到 Crowdin,以便您能够为其提供翻译,请在此处打开一个新问题

请注意,BookStack 中的翻译提供给“Crowdin 全球翻译记忆库”,帮助 BookStack 和其他项目查找翻译。如果您对此贡献不满意,则不建议向 BookStack 提供翻译,甚至通过 GitHub 手动提供。

🎁贡献、问题和拉取请求

随意创建问题以请求新功能或报告错误和问题。请按照创建问题时提供的模板进行操作。

欢迎请求请求。除非进行小的调整或语言更新,否则最好尽早打开拉取请求或为您的预期更改创建一个问题,以讨论它将如何适应项目并计划合并。仅仅因为功能请求存在或被标记,并不意味着该功能将被核心项目接受。

拉取请求应该从 development分支创建,因为一旦完成它们将被合并回 development。请不要从分支构建或请求合并到 release分支,因为这仅用于发布版本。如果您希望更改 CSS 或 JavaScript 内容,请编辑 resources/. 其中的任何 CSS 或 JS 文件 public都是从这些源文件构建的,因此不应直接编辑。

该项目的行为准则可以在这里找到

🔒安全

可以在此处的文档站点上找到管理 BookStack 实例的安全信息。

如果您希望收到有关新的潜在安全问题的通知,您可以注册 BookStack 安全邮件列表

如果您想报告安全问题,可以在此处找到这样做的详细信息。

♿可访问性

我们希望尽可能多的人可以访问 BookStack。我们的目标是在可能的情况下至少达到 WCAG 2.1 A 级标准,尽管我们不会在每次发布时都严格测试这一点。如果您遇到任何可访问性问题,请随时打开一个问题。

🖥️网站、文档和博客

包含项目文档和博客的网站可以在BookStackApp/website repo 中找到。

⚖️执照

BookStack 源代码是在 MIT 许可下提供的。

BookStack 使用和包含的库是根据它们自己的许可和版权提供的。我们的许多核心依赖项的许可证可以在下面的归属列表中找到,但这并不是 BookStack 中使用的所有项目的详尽列表。