README

WebDocBook 是一个简单的 PHP 应用，用于从 Markdown 文件构建遵循文件系统架构的丰富 HTML5 视图。它嵌入了一些经典 CMS 的网站特性，如内容搜索、一些 RSS 源生成或翻译切换。

WebDocBook 从简单的 Markdown 文件构建一个“像书一样”的交互式网站。

要开始，请访问 http://webdocbook.com/ 网站。

关键特性

• WebDocBook 是一个简单的应用，它以 Markdown 文件的文件系统架构组织。每个文件是一个“页面”，每个子目录是一个“页面”的“部分”。文件或目录的标题用作页面或部分的标题；
• 在 Bootstrap 的帮助下，WebDocBook 视图是 HTML5 有效的；
• WebDocBook 非常 可配置 和 可定制；
• WebDocBook 使用 Markdown 扩展 高级语法；
• WebDocBook 可以轻松生成网站地图和 RSS 源；
• WebDocBook 不使用数据库。

快速安装

1. 要安装 WebDocBook，您首先需要 Composer，这是安装所有依赖项所必需的。

2. Composer 安装后，您只需运行：

   $ composer create-project wdbo/webdocbook your/path/to/webdocbook 1.* --no-dev
   

3. 在您的 web 服务器上配置一个虚拟主机，将其指向安装的 www/ 目录。

4. 浏览到您的新虚拟主机，并修复任何启动错误。

这样就完成了！您的 WebDocBook 已经准备好了！

要开始，您可以将一些内容复制或链接到安装的 www/ 目录中。

要获取帮助，您可以查看 docs/ 中的文档。

组织概述

所有 Markdown 文件，网站的真实页面，都必须存储在 www/ 目录或其子目录中。

任何目录中名为 INDEX.md 的文件都将被视为其索引，如果没有在其他 URL 中请求其他文件，则将其交付。

任何目录中名为 README.md 的文件都将在目录内容索引的底部显示，就像 Apache 的默认行为一样。

任何您想要包含或用于 Markdown 内容的资产、图像或其他媒体文件都必须存储在当前目录中的 assets/ 子目录中。如果您不遵循此规则，您的文件将无法通过 web 服务器访问。

默认情况下，任何包含在名为 wip/ 的目录中的文件都不会公开显示，也不会在 网站地图 或索引中引用；要查看它，您将必须手动编写其 URL。

了解这一点后，一个经典的 WebDocBook 目录组织应该是这样的：

| chapter-name/
| ------------- README.md           // the first file shown loading the directory
| ------------- assets/             // a directory containing your medias
| ------------- wip/                // a directory containing your work-in-progress contents
| ------------- PAGE.md             // a Markdown content file (page 1)
| ------------- OTHER-PAGE.md       // another Markdown content file (page 2)
| ------------- OTHER-PAGE.fr.md    // the french translation of page 2
| ------------- sub-chapter1/       // a sub-directory containing a sub-chapter
| ------------- sub-chapter2/       // a sub-directory containing another sub-chapter

您所有第一层目录（直接包含在您的 WebDocBook www/ 根目录中的目录）都被视为您的章节，并在每个页面的页眉导航栏中列出，以便快速访问。

Docker 容器

WebDocBook的完整源代码构建的Dockerfile旨在创建一个容器。该文件将创建一个包含本地源代码的本地Docker镜像，在容器中安装应用程序，并通过HTTP和HTTPS协议公开您的WebDocBook应用。您可以在运行时配置一些特殊的端口映射，并将一些Markdown文件的本地卷挂载到容器中使用。

以下为构建容器的步骤

1. 准备一个包含已安装应用程序的Docker镜像

   docker build -t wdbo_server .
   

   在构建镜像时，您可以使用--build-arg <var>=<val>参数自定义环境变量；Dockerfile顶部的列表显示了可用的变量。

2. 基于该镜像创建一个新的容器（以下示例中，容器的默认80和443端口映射到主机上的自定义端口，并挂载了特殊的本地卷以替代默认的WebDocBook数据）

   docker run -d \
       --name wdbo_server_c \
       -p 8080:80 \
       -p 8443:443 \
       -v /path/to/your/md/files:/var/www/webdocbook/www \
           wdbo_server
   

3. 可选，您可以使用“www-data”用户连接到您的容器

   docker exec -ti -u www-data wdbo_server_c bash
   

4. 可选，您可以使用以下命令查看Apache和PHP日志：

   docker logs -f wdbo_server_c
   

对于开发，您可以将整个本地源代码作为容器的卷挂载，以在容器中保持您的开发工作

docker run -d \
    --name wdbo_server_c \
    -p 8080:80 \
    -p 8443:443 \
    -v $(pwd):/var/www/webdocbook \
        wdbo_server

在这种情况下，您可能需要更改文件系统的所有者，以匹配容器的服务器用户（对于UID/GID为1000的“www-data”）。

许可证

WebDocBook是一个开源软件，在GNU通用公共许可证版本3下发布。您可以自由下载、使用或分发，只要您遵守许可证条件。有关更多信息，请参阅LICENSE文件。