mkdocs教程:http://www.mkdocs.org/#installation(英文)
http://markdown-docs-zh.readthedocs.org/zh_CN/latest/(中文)
MacDown的下载包:http://yunpan.cn/cdmKrfvZs2fsc (提取码:6a8e)
开始学习mkdocs!!!
执行命令 sudo pip install mkdocs ,因为网速慢总是退出,报timeout错
后在网络上找到0.14.0的包直接装也因为网络的缘故暂停
提供的网址上 http://topmanopensource.iteye.com/blog/2004853 的教程里提到命令 镜像
pip install web.py -i http://pypi.douban.com/simple 速度超级快!
安装完成后按照文档教程里开始学习啦!
在指定目录下执行 mkdocs new my_pro 会生成一个目录 其中包含-docs-index.md 和-mkdocs.yml
其中mkdocs.yml 中设置站点名称 会自动显示在网页左上角和网页标里
index.md 里按照既定好的格式来描写文档
生成好目录之后 在mkdocs.yml同目录下执行mkdocs serve 命令启动内建服务器
然后修改docs/index.md文件中site_name,在保存的时候可以观察到网页和shell里面都在刷新
添加页面
编辑index.md文件 修改标题,保存文件可以看到网页刷新
为文档添加第二个页面,教程给到的命令格式是:curl ‘index.md‘ > zzz.md 这个curl是在命令行方式下使用的开源文件传输工具,后面紧跟的是传输源文件 之后的文件是接受传输的文件,传输规则时若没有则新建,若存在则覆盖 。
文件新建好了之后需要加在网页显示,这时候在mkdocs.yml中需要添加一些内容了。
这样的格式在保存后网页会出现导航栏。
配置主题
再配置主题,再在该文档后添加 theme: readthdocs 保存后可以看到浏览器主题的变化
site_name: MkLorum
pages:
- [index.md, Home]
- [about.md, About]
theme: readthdocs
站点生成
在mkdocs.yml的上一级目录下执行mkdocs build,目录下会新生成site目录,
这个目录在git提交的时候最好选择ignore掉:echo ‘site/‘ >> .ignore
教程文档提醒 site目录下, 源码分别输出为index.html 和about/index.html
mkdocs build —clean 命令在有些文档从源码中移除后,在执行这个命令的时候可以移除这些文档
以上是生成静态文档,接下来需要将文档放在网络上让更多的人看到
http://www.ruanyifeng.com/blog/2012/08/blogging_with_jekyll.html
该网址是jekyll的教程
Jekyll 是一个静态网站生成器,接下来根据教程来学习:
http://lvxuedan.github.io/mkdoc_test/site/
git下的这个工程目录
git init (对该目录进行git初始化)
git checkout —orphan gh-pages (创建一个没有父节点的分支gh-pages。因为github规定,只有该分支中的页面,才会生成网页文件)
git add . (先把所有内容加入本地git库)
git commit -m "first post”
git remote add origin https://github.com/username/jekyll_demo.git
git push origin gh-pages