document/TranslateProject
2
0
Fork 0
mirror of https://github.com/LCTT/TranslateProject.git synced 2025-01-25 23:11:02 +08:00
Code Issues Packages Projects Releases Wiki Activity

translated

Browse Source
This commit is contained in:
geekpi 2023-01-29 08:46:39 +08:00
parent d563a36199
commit 37659ddca1
2 changed files with 98 additions and 98 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

98
sources/tech/20230103.1 ⭐️⭐️ Document with BookStack, an open source Confluence alternative.md
View File

@ -1,98 +0,0 @@
[#]: subject: "Document with BookStack, an open source Confluence alternative"
[#]: via: "https://opensource.com/article/23/1/bookstack-open-source-documentation"
[#]: author: "Dan Brown https://opensource.com/users/ssddanbrown"
[#]: collector: "lkxed"
[#]: translator: "geekpi"
[#]: reviewer: " "
[#]: publisher: " "
[#]: url: " "
Document with BookStack, an open source Confluence alternative
======
BookStack is an open source, web-based documentation system, that allows you to create a structured knowledge store for personal, team, or company use. BookStack focuses on ease-of-use and design to provide an experience suitable for an audience with, potentially, mixed skills in technology. It's built upon the PHP framework Laravel, with MySQL or MariaDB used as a datastore.
I built BookStack after attempting to find a documentation or wiki system for my workplace. [Confluence][1] was the closest option to suit my requirements but the user-based pricing introduced a barrier. The closed nature of Confluence also raised questions to the longevity of the documentation I'd be building. In the end, I decided to build my own platform to suit my needs. I released it under the MIT license to give back to the open source community that I'd come to love and benefit from over the years.
### Content hierarchy and organization options
To keep things familiar and intuitive, BookStack makes use of real-world book terms to describe its organization structure. Documentation content is created as a "Page":
- Pages belong to a specific "Book".
- Within a Book, Pages can optionally be grouped up into "Chapters".
- As your documentation grows, you can then use "Shelves" to categorize Books, with Books being able to be part of multiple shelves if needed.
This structure sits at the heart of BookStack, and can often be the love-it-or-hate-it deciding aspect of whether BookStack is suitable for your use case.
Upon this core hierarchy, BookStack also provides tagging, user favorites, and advanced search capabilities to ensure content remains discoverable.
### Writing documentation
The primary method of writing documentation in BookStack is through the use of its what-you-see-is-what-you-get (WYSIWYG) editor, which makes use of the open source [Tiny][2] project. This editor provides a range of content formats including:
- Various header levels
- Code blocks
- Collapsible blocks
- Tables
- Images
- Links
- iFrame embeds
- Alert callouts
- Bullet, numbered and tasks lists
- Drawings (through intregration with the open source [diagrams.net][3])
If you prefer [Markdown][4], you can use the built-in Markdown editor, which provides a live preview and supports the same feature set as the WYSIWYG editor. If permission allows, you can even jump between these editor options depending on the page you're editing.
### How your data is stored
Documentation is stored within a [MySQL or MariaDB][5] database in a relatively simple HTML format, in addition to the original Markdown content if Markdown was used. A lot of design and development decisions have been made to keep this HTML format simplistic. It uses plain standard HTML elements where possible, to ensure raw documentation content remains open and portable.
Uploaded images, attachments, and created drawings are saved on the local filesystem but can optionally be stored in an s3-compatible datastore like the open source [MinIO][6].
To keep your content accessible, there are built-in options to export content as PDF, HTML, plain text, or Markdown. For external consumption, there's a HTTP REST API and a webhook system. In terms of extension, a "logical theme system" allows running of custom PHP code upon a wide range of system events.
### Ready for business
BookStack comes with a range of features to support business environments. Support for a range of authentication options are built-in, including SAML2, OpenID Connect, and LDAP allowing easy single-sign-on usage with platforms such as [KeyCloak][7]. MFA options are available and can be mandated based upon role. An audit log provides full visibility of modification activities across an instance.
A full role-based permission system provides administrators full control over create, view, update, and delete actions of system content. This allows per-role system defaults, with options to set custom permissions on a per-hierarchy item basis.
### A community of support
After being active for over 7 years, the community for BookStack has grown with various avenues for discussion and support. We now have:
- [Our documentation site][8]
- [Video guides on YouTube][9]
- [A subreddit][10]
- [An active GitHub issues list][11]
- [Paid-for business support][12]
If you want to play with BookStack, you can try it out [on our demo site][13]. To learn how to set up your own instance, visit the [installation page of our documentation][14].
--------------------------------------------------------------------------------
via: https://opensource.com/article/23/1/bookstack-open-source-documentation
作者：[Dan Brown][a]
选题：[lkxed][b]
译者：[译者ID](https://github.com/译者ID)
校对：[校对者ID](https://github.com/校对者ID)
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
[a]: https://opensource.com/users/ssddanbrown
[b]: https://github.com/lkxed
[1]: https://opensource.com/article/20/9/open-source-alternatives-confluence
[2]: https://github.com/tinymce/
[3]: https://www.diagrams.net/
[4]: https://opensource.com/article/19/9/introduction-markdown
[5]: https://opensource.com/downloads/mariadb-mysql-cheat-sheet
[6]: https://github.com/minio/
[7]: https://www.keycloak.org/
[8]: https://www.bookstackapp.com/docs/
[9]: https://www.youtube.com/c/BookStackApp
[10]: https://www.reddit.com/r/bookstack
[11]: https://github.com/BookStackApp/BookStack/issues
[12]: https://www.bookstackapp.com/support
[13]: https://demo.bookstackapp.com/books/bookstack-demo-site/page/logging-in-to-the-demo-site
[14]: https://www.bookstackapp.com/docs/admin/installation/

98
translated/tech/20230103.1 ⭐️⭐️ Document with BookStack, an open source Confluence alternative.md Normal file
View File

@ -0,0 +1,98 @@
[#]: subject: "Document with BookStack, an open source Confluence alternative"
[#]: via: "https://opensource.com/article/23/1/bookstack-open-source-documentation"
[#]: author: "Dan Brown https://opensource.com/users/ssddanbrown"
[#]: collector: "lkxed"
[#]: translator: "geekpi"
[#]: reviewer: " "
[#]: publisher: " "
[#]: url: " "
使用 BookStack 写文档，一个开源的 Confluence 替代品
======
BookStack 是一个开源的、基于网络的文档系统，它允许你创建一个结构化的知识库供个人、团队或公司使用。BookStack 专注于易用性和设计，以提供适合具有潜在的混合技术技能的受众的体验。它建立在 PHP 框架 Laravel 之上，使用 MySQL 或 MariaDB 作为数据存储。
在尝试为我的工作场所寻找文档或 wiki 系统后，我构建了 BookStack。[Confluence][1] 是最符合我要求的选项，但基于用户的定价带了的阻碍。Confluence 的封闭性也对我要构建的文档的寿命提出了质疑。最后，我决定建立自己的平台来满足我的需求。我用 MIT 许可发布它，以回馈我多年来喜爱并从中受益的开源社区。
### 内容层次和组织选项
为了保持熟悉和直观，BookStack 使用了现实世界的书籍术语来描述其组织结构。文档内容被创建“页”：
- 页属于一个特定的“书”。
- 在一本书中，页可以选择性地被分组为“章节”。
- 随着文档的增长，你可以使用“书架”来对“书”进行分类，如果需要，“书”可以成为多个书架的一部分。
这种结构是 BookStack 的核心，而且往往是决定 BookStack 是否适合你的使用情况的爱与恨的方面。
在这个核心层次上，BookStack 还提供了标签、用户收藏夹和高级搜索功能，以确保内容可被发现。
### 编写文档
在 BookStack 中编写文档的主要方法是通过使用其所见即所得（WYSIWYG）编辑器，它利用了开源的 [Tiny][2] 项目。这个编辑器提供了一系列的内容格式，包括：
- 各种标题级别
- 代码块
- 可折叠的块
- 表格
- 图片
- 链接
- iFrame 嵌入
- 提醒呼出
- 项目符、编号和任务列表
- 绘图（通过与开源 [diagrams.net][3] 的整合）
如果你喜欢 [Markdown][4]，你可以使用内置的 Markdown 编辑器，它提供实时预览并支持与所见即所得编辑器相同的功能集。如果权限允许，你甚至可以根据你所编辑的页面，在这些编辑器选项之间跳转。
### 你的数据是如何存储的
文档以相对简单的 HTML 格式存储在 [MySQL 或 MariaDB][5] 数据库中，如果使用了 Markdown，除了原始的 Markdown 内容外。很多设计和开发决定都是为了保持这种 HTML 格式的简单性。它尽可能地使用普通的标准 HTML 元素，以确保原始文档内容保持开放和可移植。
上传的图片、附件和创建的图纸被保存在本地文件系统中，但也可以选择存储在一个与 s3 兼容的数据存储中，比如开源的 [MinIO][6]。
为了保持你的内容可访问性，有内置的选项可以将内容导出为 PDF、HTML、纯文本或 Markdown。对于外部消费，有一个 HTTP REST API 和一个 webhook 系统。在扩展方面，一个“逻辑主题系统”允许在广泛的系统事件中运行自定义的 PHP 代码。
### 为业务做好准备
BookStack 具有一系列的功能来支持商业环境。内置了对一系列认证选项的支持，包括 SAML2、OpenID Connect 和 LDAP，允许使用 [KeyCloak][7] 等平台轻松实现单点登录。MFA 选项是可用的，并且可以根据角色进行授权。审计日志提供整个实例的修改活动的完整可见性。
一个完全基于角色的权限系统为管理员提供了对系统内容的创建、查看、更新和删除操作的完全控制。这允许每个角色的系统默认值，以及在每个层次项目基础上设置自定义权限的选项。
### 一个支持的社区
经过 7 年多的活跃，BookStack 的社区已经发展到了各种讨论和支持的渠道。我们现在有：
- [我们的文档站点][8]
- [YouTube 上的视频指南][9]
- [一个 subreddit][10]
- [一个活跃的 GitHub 问题列表][11]
- [付费业务支持][12]
如果你想玩玩 BookStack，你可以[在我们的演示网站][13]试试。要了解如何设置你自己的实例，请访问[我们文档的安装页面][14]。
--------------------------------------------------------------------------------
via: https://opensource.com/article/23/1/bookstack-open-source-documentation
作者：[Dan Brown][a]
选题：[lkxed][b]
译者：[geekpi](https://github.com/geekpi)
校对：[校对者ID](https://github.com/校对者ID)
本文由 [LCTT](https://github.com/LCTT/TranslateProject) 原创编译，[Linux中国](https://linux.cn/) 荣誉推出
[a]: https://opensource.com/users/ssddanbrown
[b]: https://github.com/lkxed
[1]: https://opensource.com/article/20/9/open-source-alternatives-confluence
[2]: https://github.com/tinymce/
[3]: https://www.diagrams.net/
[4]: https://opensource.com/article/19/9/introduction-markdown
[5]: https://opensource.com/downloads/mariadb-mysql-cheat-sheet
[6]: https://github.com/minio/
[7]: https://www.keycloak.org/
[8]: https://www.bookstackapp.com/docs/
[9]: https://www.youtube.com/c/BookStackApp
[10]: https://www.reddit.com/r/bookstack
[11]: https://github.com/BookStackApp/BookStack/issues
[12]: https://www.bookstackapp.com/support
[13]: https://demo.bookstackapp.com/books/bookstack-demo-site/page/logging-in-to-the-demo-site
[14]: https://www.bookstackapp.com/docs/admin/installation/