README

QuickieDox 是一个 纯 PHP( >= 7.4) 项目，可让您快速从 markdown 文件创建优雅的文档。请访问 https://quickiedox.com 了解完整文档。

QuickieDox 不是软件即服务，因此不托管任何文档。您需要像托管任何网站一样自行托管一切。

谁可以使用 QuickieDox

要使用 QuickieDox，您必须已经知道如何编写 markdown 语法，并且也了解一些基本的 PHP。本指南可以帮助您熟悉 markdown 编写。
无论文档大小如何，任何有文档需求的人都可以使用 QuickieDox

安装

有两种方式可以使用 QuickieDox 创建自己的文档网站。

通过 Composer

这是一个最简单的选项。只需运行以下命令。

# replace your-project-name with the name of the directory you want created
# or the name of your project (directory will be created if it does not exist)

composer create-project mkocansey/quickiedox your-project-name

从 GitHub 克隆: HTTPS

# create a directory where you want to clone quickiedox
# cd into that directory and run

git clone https://github.com/mkocansey/quickiedox.git

从 GitHub 克隆: SSH

# create a directory where you want to clone quickiedox
# cd into that directory and run

git clone git@github.com:mkocansey/quickiedox.git

重命名 .env-example

您将在您刚刚克隆的项目根目录下找到一个 .env-example 文件。将其重命名为 .env。如果不这样做，应用将无法运行。

mv .env-example .env

运行应用

现在您已经克隆了仓库，让我们运行应用以确保您可以看到默认提供的文档。从您刚刚创建的目录的根目录中运行

composer install

让我们启动一个内置的 PHP 服务器以快速测试。仍然在项目根目录中，输入

php -S localhost:8000

上面的命令假设端口 8000 不会被其他网站或应用占用。您应该看到类似于以下内容的输出。PHP 版本可能会根据您的机器上安装的版本而有所不同。

[Thu Mar  9 00:11:36 2023] PHP 8.2.3 Development Server (https://:8000) started

导航到 https://:8000 应该显示以下屏幕。

如上图所示，从主页点击 阅读文档 应该显示以下屏幕。

从上面的图片中可以看出，QuickieDox 无法加载文档导航或默认文档页面。这是非常预期的，因为我们还没有拉入组成文档的 markdown 文件。

默认情况下，QuickieDox 预期 markdown 文件位于您刚刚创建的项目根目录下的 markdown 目录中。您可以使用任何您选择的目录名称，但请确保更新配置文件以告诉 QuickieDox 从哪里加载您的 .md 文件。

拉入 markdown 文件

组成文档的 markdown 文件预计将位于您指定的目录中。默认为 markdown。这里的假设/约定是您的 markdown 文件托管在其自己的 git 仓库中。有两种方式可以拉入 markdown 文件。

使用内置的克隆工具

通过 HTTP

使用 QuickieDox 内置的克隆 URL 拉入您的 markdown 文件要容易得多。假设您仍在上述使用 php -S localhost:8000 启动的服务器上运行应用，您需要访问以下 URL。

https://:8000/get-markdown

请确保您已正确修改了QuickieDox的配置。URL将要求您输入在.env或.config.php文件中定义的PIN，作为GIT_CLONE_PIN。如果您的PIN为空，则无法使用此URL。

通过clone.sh文件

如果您是从公共仓库克隆，通过HTTP克隆将工作良好。如果您是从私有仓库克隆文档，使用clone.sh文件是更好的选择。

在项目根目录中包含一个clone.sh shell脚本，该脚本将从您指定的仓库中拉取markdown文件。您需要编辑此文件以更改默认的GIT_REPO_URL、DOCS_DIRECTORY和DOC_VERSIONS值。

# clone.sh

#!/bin/bash

# update this to your own documentation repo url

GIT_REPO_URL="https://github.com/mkocansey/quickiedox-mds.git"


# update this to the directory you prefer to clone your docs into

DOCS_DIRECTORY="markdown"


# note the versions are not strings
# each version needs to be defined on its own line without quotes

DOC_VERSIONS=(
  main
  #master
  #2.x
  #1.x
)

确保脚本具有对所有者和/或组的执行权限。运行。

ls -l clone.sh

# you should get an output similar to the line below

-rwxr-xr--@  1 your-username  your-group  1026 Mar 20 11:14 clone.sh

现在运行此命令以执行shell脚本以拉取文档。

./clone.sh

复制和粘贴

QuickieDox只需要在markdown目录中的.md文件。您可以将.md文件简单地复制并粘贴到该目录中，然后就可以使用了！如果您的文档有版本，您需要为每个版本创建一个单独的目录。例如，如果您的文档有版本1.5和2.2，您需要在markdown目录中创建1.5和2.2目录。然后您需要将适当的.md文件复制到相应的目录中。有关更多信息，请参阅常规 > 版本化文档。

进一步阅读

请访问https://quickiedox.com以获取完整文档，但这些应该有助于您更好地理解QuickieDox的工作方式。

已知问题

Algolia集成
更快的全站搜索
保护需要登录才能阅读的文档
顶级导航项只能是父项，而不能是页面的链接

支持

如果您有任何问题，可以@quickiedox发推文或kabutey@gmail.com发送电子邮件。

mkocansey / quickiedox

维护者

详细信息