页面概述
使用GitHub Pages搭建的简易静态博客,用于记录研究生学习过程中遇到的问题和可行的解决方法,包括常见环境工具的安装使用,文献论文阅读记录,专业基础和读书笔记等等.
使用jekyll作为渲染引擎,选择适合于文档页面组织展示的Just the Docs主题,可以输出较为规整简洁的web页面.
大部分文档编写可以使用markdown标记语言来书写,可以根据Just the Docs上面定义的一些扩展Liquid模板标记来个性化文档书写,可以使用html书写更为灵活的文档.
页面编写
- 除了404,主页等页面,其它页面应当按照主题进行分类放置.
+-- ..
|-- (Jekyll files)
|
|-- envs_tools
| |-- index.md (parent page)
| |-- Github_Pages
| | |-- index.md (parent page)
| | |-- GithubPages安装.md
| | |-- GithubPages配置Just the Docs主题.md
| | |-- Just the Docs主题下markdown基本组件的使用.md
| | +-- just the docs 主题导航结构.md
| |-- Python
| |-- Git
| |-- (other md files, pages with no children)
| +-- ..
|-- Machine_Learning
|
|-- 404.html
|-- index.md
|-- (Jekyll files)
+-- ..
比如在主目录下有一个envs_tools目录,用来放置一些常用软件工具环境相关的页面,在下一级目录下,安装软件工具的类别,分成GithubPages,Python, Git等等.在GithubPages放置了安装配置和使用GithubPages相关的一些页面.主目录下的Machine_Learning目录用于放置记学习ML的一些页面记录,根目录下的404.html,index.md等等则是整个GithubPages站点相关的一些页面.
- 导航栏页面顺序的显示
通过在页面的YAML参数指定nav_order:参数可以控制当前页面在导航栏显示的次序,如果不指定则按页面的title属性的值按照字典序进行排序,指定的参数在前,其后是字典序,字典序区分大小写,大写在前.
- 导航栏层级结构
导航栏最多支持三级结构,在每个分类文件夹下有一个index.md文档,用来组织当前文件夹下所有页面的层级逻辑结构.显示当前文件夹下几个子文件夹下页面组织的index.md导航结构的组织.而子文件夹下的index.md则记录了当前该小主题下所有页面的集合.
- 注意:
- 如果在文档中需要插入图片,建议先将图片上传到图床,然后再根据图床中图片的url进行插入.用起来很好的图床推荐:SM.MS
- 插入图片也可以先将图片放到当前目录
images下,然后使用相对于当前根目录的方法,比如在images下有一张名为邀请成员.png的图片,可以这样使用,效果如下图所示:
TODO
- 文件下载功能
- 评论反馈功能
- Github pages 协同编写更新
- ……
在线直接预览Github的repo上的pdf
将文件放到Github Pages站点下的文件夹,按照内容类别分类存放,使用的方式一般为[文件名](https://gxl-groups.github.io/pathname/filename.pdf),如下面的例子:
文件下载
文件下载链接的一般格式是[文件名](https://raw.githubusercontent.com/github用户名/githubrepo名/分支名/pathname/filename)
邀请成员协同参与编写
-
点击
Add people选项
-
输入协作人员的github的用户名
-
设置邀请协作人员的权限
-
等待成员同意
-
协作者再编写页面时应该先从远端拉取最新的项目到本地,然后编写页面,添加提交,将编写后的最新项目推送到远端.