Daux.io 是一个文档生成器,可以帮助用户快速生成漂亮的项目文档,此外,用户还可以通过简单的文件结构和Markdown文件来创建自定义格式的文档。 它可以帮助你使用对于开发更加友好的方式创建文档。
添加php到系统路径
命令行下,进入docx目录下,运行命令 php index.php admin deploy your-blog-name
使用nginx rewrite部署时,请去掉将location中的.php$改为.php或者.php(/|$),并去掉try_files
保证temp和public两个目录可写
php本身不带yaml扩展,请将配置中的cache_ext由.yml改为.json
重构代码,改为独立的几个类,并可使用压缩后的库文件。
原来的命令行操作,除了git外,也都移到WEB管理页面。
增加PDF输出功能,需要安装WkHtmlToPdf
在Markdown中增加Metadata,支持设置文档标题和slug和时间等。
可设置文档模板layout,支持文件倒序排列,可作为静态博客使用。Metadata类似这样:
layout: post
date: 2014-04-08
title: 快速开始
slug: getting-started
tags: 帮助, 快速开始
comments: false
#第一次使用git时设置
git config --global user.name "Ryan Liu"
git config --global user.email "azhaixxx@126.com"
#下载源码
git clone http://git.oschina.net/azhai/docx.git
#将原始md文档纳入新的版本库管理
cd docx\docs\
git init
cd ..\..
#以下为管理静态博客,以gitcafe为例,先去申请一个帐号,并建立一个同名项目
#参考其网站上的帮助,拿到pages项目地址
rm -rf static
git submodule add -f https://gitcafe.com/azhai/azhai.git static
cd static
git checkout -b gitcafe-pages
php ..\index.php gen
git add .
git commit -a -m '第一次生成静态博客'
git push -u origin gitcafe-pages
这是一个使用Daux.io的站点列表:
看到Daux.io了吗? 给我发送pull request或者新建一个issue,我将会将你的站点加入到这个列表里面!
下载zip格式的版本库文件, 并且解压. 拷贝这些文件到一个可以运行高于PHP5.3版本的服务器上. 你还可以在本地使用Grunt.js运行这些文档,使用方法会在readme结尾处讨论.
默认文档生成器会搜索目录/docs
. 添加你的目录到/docs
目录中. 该项目已经包括一些实例文件夹和文件帮助你快速使用.
你可以嵌套任意级别的文件夹来达到你所希望的结构. 目录结构将会被转化为嵌套折叠导航.
如果你希望保留你的文档在其他位置(例如在 daux.io根目录之外的目录),你可以通过在配置文件config.json
中指定文档路径.
生成器将会搜索/docs
目录及其子目录中的Markdown *.md
文件. 译者注:Markdown是一种轻量级的标记语言.
你必须使用.md
文件扩展名命名你的文档文件. 另外文件名你需要使用下划线来代替空格 这里有一些文件名的案例已经它们转化为可以被接受的格式:
推荐的格式:
不推荐:
如果你需要对你的文件和文件夹进行排序,你可以为他们添加数字和下划线前缀, 例如: /docs/01_Hello_World.md
和 /docs/05_Features.md
这将会在Features之前列出 Hello World 从而覆盖了默认的字母数字排序顺序. 这些数字将会从导航和urls中剥离出去,不会显示.
如果你希望为你的项目创建一个漂亮的着陆页,只需要简单的创建一个index.md
文件在你的文档根目录/docs
中. 该文件将会被用于创建着陆页. 你还可以通过配置文件添加一个品牌口号和图片到该页面,配置如下:
{
"title": "Daux.io",
"tagline": "最简单的方式构建你的项目文档",
"image": "img/app.png"
}
提示:图像可以是本地图像或者远程图像.
你可以在文件夹/docs
中创建config.json
配置文件来定制项目文档的外观和感觉. config.json
配置文件是一个简单的JSON对象,你可以修改该文件来改变文档一些基础设置.
###标题: 在这些文档中修改标题栏
{
"title": "Daux.io"
}
###文档路径: 如果你更希望你的文档在Daux.io以外的文件夹,你可以提供一个文件路径在配置文件中.
注意:你的配置文件 config.json
需要任然保存在目录 /daux.io/docs
之下.
{
"docs_path": "../../my_docs"
}
###主题:
我们提供了4中内置的Bootstrap主题样式. 如果要使用这些主题,仅仅需要在配置文档中,设置theme
选项为以下值:
{
"theme": "blue"
}
###用户定制:
用户可以定制文档配色,通过设置设置 theme
属性 custom
然后再定义不同内容的颜色即可. 拷贝以下配置文件开始自定义文档配色:
{
"theme": "custom",
"colors": {
"sidebar-background": "#f7f7f7",
"sidebar-hover": "#c5c5cb",
"lines": "#e7e7e9",
"dark": "#3f4657",
"light": "#82becd",
"text": "#2d2d2d",
"syntax-string": "#022e99",
"syntax-comment": "#84989b",
"syntax-number": "#2f9b92",
"syntax-label": "#840d7a"
}
}
###代码悬浮:
默认设置你的文档中的代码块会被悬浮于内容的右侧.(译者注:当屏幕超过1150px的时候) 如果需要关闭该特性,只需要设置 float
属性为 false
.
{
"float": false
}
###切换代码框显示
有些用户希望只看文档而隐藏代码部分. 您可以设置 toggle_code
为 true
给他们选择的权利, 这时页面上将会多出一个切换按钮(译注:在导航的最下面,是个链接).
{
"toggle_code": true
}
###GitHub 版本控制: 添加一个带有 'Fork me on GitHub'内容的横幅彩带的配置项如下:
{
"repo": "justinwalsh/daux.io"
}
###Twitter: 包含twitter关注按钮在侧边栏.
{
"twitter": ["justin_walsh", "todaymade"]
}
###链接: 包含用户定制链接在侧边栏配置如下:
{
"links": {
"GitHub Repo": "https://github.com/justinwalsh/daux.io",
"Help/Support/Bugs": "https://github.com/justinwalsh/daux.io/issues",
"Made by Todaymade": "http://todaymade.com"
}
}
###文件编辑器:
Enable front-end Markdown editor. Disabled by default.
{
"file_editor": true
}
###添加Google分析: 这里将会嵌入Google分析跟踪码.
{
"google_analytics": "UA-XXXXXXXXX-XX"
}
###Piwik分析: 这里将会嵌入Piwik跟踪码.
{
"piwik_analytics": "my-url-for-piwik.com"
}
###过滤忽视文件:
设置忽略/docs
文件夹中特定的文件和文件夹 ,使其不显示在文档中. 对于文件,确保文件扩展名包含在配置文件中. 对于文件和文件夹,名字时大小写敏感的.
{
"ignore": {
"files": ["Work_In_Progress.md"],
"folders": ["99_Not_Ready"]
}
}
###关闭URLs重写 默认Daux.io将创建url重写,url中将不包含index.php. 如果服务器端运行的Apache,上传 .htaccess 文件,将会实现该url重写. 如果服务器端没有运行Apache或者不能自定义 .htaccess 文件, 你可能需要关闭clean_url功能,方法如下:
{
"clean_urls": false
}
###日期修改 默认daux.io将会显示最后更新时间在每个文档标题下面,该时间来自系统反馈. 关闭该功能,需要更改 config.json 中的date_modified选项为 false.
{
"date_modified": false
}
###时区设置 如果你的服务器没有在php.ini中设置默认时区,文档在获取最后修改日期时间时会返回错误. 修改该错误,需要在配置文件中指定时区. 有效的设置选项参考PHP手册 PHP Manual.
{
"timezone": "America/Los_Angeles"
}
###多语言
开启多语言支持,在`docs/`目录下,请将每种语言的文件放入一个子目录.
```json
{
"languages": { "en": "English", "de": "German" }
}
目录结构:
├── docs/
│ ├── index.md
│ ├── en
│ │ ├── 00_Getting_Started.md
│ │ ├── 01_Examples
│ │ │ ├── 01_GitHub_Flavored_Markdown.md
│ │ │ ├── 05_Code_Highlighting.md
│ │ ├── 05_More_Examples
│ │ │ ├── Hello_World.md
│ │ │ ├── 05_Code_Highlighting.md
│ ├── de
│ │ ├── 00_Getting_Started.md
│ │ ├── 01_Examples
│ │ │ ├── 01_GitHub_Flavored_Markdown.md
│ │ │ ├── 05_Code_Highlighting.md
│ │ ├── 05_More_Examples
│ │ │ ├── Hello_World.md
│ │ │ ├── 05_Code_Highlighting.md
从版本库复制文件到基于PHP5.3或更高的web服务器.
这里有一些本地运行该文档生成器的方法. 你可以使用类似于MAMP 或者 WAMP的服务器集成架设软件. 如果你想我一样经常使用Node.js和 Grunt.js, 那么你可以使用我已经预先打包好的可选的grunt命令,它将会在项目文件夹中启动PHP web 服务器.
Grunt.js将会利用内置的PHP 5.4 web服务器为你构建本地的文档. 这是仅仅为了被用于当你希望撰写或更新大量的文档并且仅仅希望本地查看其更改.
使用可选的Grunt命令,你需要:
该项目包含一个 package.json 文件, 所以一旦你的系统满足以上要求,你只需要运行命令npm install
然后在项目文件夹中进行 grunt
操作来启动本地web服务器. 默认的服务器地址为: http://localhost:8085
可以将它们上传到提供静态托管服务的网站比如 pages.github.com
生成完整可独立浏览的页面, 并带有导航功能
php index.php generate
您也可以多传两个参数(都是可选的) 一个是配置文件 config.json 的路径,另一个是静态文件的输出目录
php index.php generate '\path\to\config.json' 'out\dir'
如果路径以 '' 开头,那么它将被当作一个绝对路径,否则,就是的docx目录下的相对路径.
如果你已经建立的本地或远程的IIS web站点,你需要一个 web.config
文件包含以下内容:
web.config
文件需要在<system.webServer>
之下一个入口名为<rewrite>
:
<configuration>
<system.webServer>
<rewrite>
<rules>
<rule name="Main Rule" stopProcessing="true">
<match url=".*" />
<conditions logicalGrouping="MatchAll">
<add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
<add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
</conditions>
<action type="Rewrite" url="index.php" appendQueryString="false" />
</rule>
</rules>
</rewrite>
</system.webServer>
</configuration>
在IIS6上使用整理URLs,你需要使用自定义的URL重写规则,例如URL Rewriter.
web.config
文件需要一个新的 <mimeMap>
入口, 在 <system.webServer>
中的<staticContent>
之下:
<staticContent>
<mimeMap fileExtension=".less" mimeType="text/css" />
</staticContent>
你将仅仅需要mine map入口,如果你正在使用自定义样式并且出现 .less
文件404s 错误.
如果你为服务器的.less
文件设置了全局的mime map入口,你将会收到一个内部服务的错误 internal server (500) error ,是因为mime map入口重复了.
如果你需要帮助关于使用Daux.io或者发现bug,请在Github上创建 issue 反馈,地址为GitHub repo. 中文翻译issue反馈地址:Daux.io中文.
此处可能存在不合适展示的内容,页面不予展示。您可通过相关编辑功能自查并修改。
如您确认内容无涉及 不当用语 / 纯广告导流 / 暴力 / 低俗色情 / 侵权 / 盗版 / 虚假 / 无价值内容或违法国家有关法律法规的内容,可点击提交进行申诉,我们将尽快为您处理。
1. 开源生态
2. 协作、人、软件
3. 评估模型