如何在github上免费发布个人静态博客-阿里云开发者社区

开发者社区> 技术小能手> 正文

如何在github上免费发布个人静态博客

简介:
+关注继续查看

 ●  本文仅是缩略,笔者已将详细内容发布到github上

 ●  可点击本文最后的"阅读更多"进行访问,或者在github上搜"cyent markdown"也可以看到

目录

 ●  本文概述
 ●  mkdocs-material介绍
 ●  安装
 ●  初始化项目
 ●  修改主题
 ●  运行
 ●  发布到GitHub pages
 ●  发布到个人HTTP Server
 ●  mkdocs.yml注意事项
 ●  添加页面
 ●  添加扩展
 ●  markdown语法
 ●  其他功能

 ●  最佳实践

本文概述

mkdocs-material入门,包括安装、运行、发布至github-pages及个人站点

mkdocs-material介绍

符合google material ui规范的静态文档网站生成器,使用markdown进行文档书写

mkdocs

 ●  python编写的markdown解释器、编译器,带有本地cli工具
 ●  自带基于Tornado的小型http服务,用于本地调试
 ●  内置一键式发布至GitHub Pages
 ●  内置mkdocs风格、readthedocs风格的主题,并支持自定义主题
 ●  支持调用python模块实现语法及渲染的扩展

mkdocs-material

 ●  python模块,符合google material ui规范的mkdocs自定义主题
 ●  针对特定语法、功能做了渲染优化
 ●  根据客户端浏览器页面尺寸自动缩放,对PC、移动设备都友好
 ●  丰富的页面配色,多达19种主体配色和16种悬停链接文字配色
 ●  支持中文搜索

 ●  支持统计功能,如百度统计,谷歌统计

安装


  1. pip install mkdocs mkdocs-material

若下载慢,可更换安装源为豆瓣


  1. pip install --trusted-host pypi.douban.com -i

  2. http://pypi.douban.com/simple/ mkdocs mkdocs-material

初始化项目

  1. mkdocs new my-project

会生成my-project目录,进入该目录里,可以看到默认放置了一些文件,包括mkdocs.yml,这是主配置文件

修改主题

mkdocs.yml里添加:


  1. theme:

  2. name: material

运行

  1. # 在my-project目录里执行

  2. mkdocs serve

通过浏览器访问本地ip的8000端口(比如http://127.0.0.1:8000/) 查看效果,如图所示

7c5f13cace7bd49207d34b59da01003ab8941057

发布到GitHub pages

通过 mkdocs gh-deploy自动编译出html并发布至GitHub pages,步骤如下

初始化repo

1.在github上创建一个repo,名字叫my-project(可以是其他名,这里先假设叫my-project),创建repo时候选择初始化带有README.md 2.使用git clone将repo同步到本地

导入项目

1.将mkdocs根目录(即my-project目录)下的所有东西移到刚刚git clone下来的git目录下 2.然后可以将最早创建的mkdocs根目录(即my-project目录)删除了

发布

在本地git目录下执行


  1. mkdocs gh-deploy

发布到个人HTTP Server

通过 mkdocs build编译出html并手动同步至http server的根目录

生成站点文件

在git目录下执行命令


  1. mkdocs build

命令执行完毕后可以看到site目录

发布至http server

将site目录里的所有东西拷贝到http server的根目录下

mkdocs.yml注意事项

由于是yaml格式,因此首先要符合yaml的语法要求

docs下需要一个index.md,作为站点首页

文档层次结构虽然可以很多层,但最佳实践是控制在2层内,最多不要超过3层,否则展示会不够友好

添加页面

在my-project/docs/里放置.md文件,可以自行组织目录结构

然后在mkdocs.yml里添加,比如这样:


  1. nav:

  2. - 介绍: index.md

  3. - 安装:

  4. - 本地环境搭建: install/local.md

  5. - 发布至GitHub Pages: install/github-pages.md

  6. - 发布至自己的HTTP Server: install/http-server.md

  7. - 语法:

  8. - 语法总览: syntax/main.md

  9. - 标题: syntax/headline.md

  10. - 段落: syntax/paragraph.md

 ●  上面的index.md就是放置在my-project/docs/index.md

 ●  上面的local.md就是放置在my-project/docs/install/local.md

添加扩展

只有添加了扩展,才能完美使用mkdocs-material官方支持的所有markdown语法

mkdocs.yml里添加:


  1. markdown_extensions:

  2. - admonition

  3. - codehilite:

  4. guess_lang: false

  5. linenums: false

  6. - toc:

  7. permalink: true

  8. - footnotes

  9. - meta

  10. - def_list

  11. - pymdownx.arithmatex

  12. - pymdownx.betterem:

  13. smart_enable: all

  14. - pymdownx.caret

  15. - pymdownx.critic

  16. - pymdownx.details

  17. - pymdownx.emoji:

  18. emoji_generator: !!python/name:pymdownx.emoji.to_png

  19. - pymdownx.inlinehilite

  20. - pymdownx.magiclink

  21. - pymdownx.mark

  22. - pymdownx.smartsymbols

  23. - pymdownx.superfences

  24. - pymdownx.tasklist

  25. - pymdownx.tilde

markdown语法

mkdocs-material支持几十种markdown语法,有许多很酷炫的功能与效果,由于篇幅有限,无法在这一一展示,因此这里仅列举下所支持的主要语法

1.标题 2.段落 3.引用 4.表格 5.代码

 ●  行内
 ●  区块
 ●  高亮

6.字体样式

 ●  斜体,粗体,粗斜体
 ●  上标,下标
 ●  下划线
 ●  横线
 ●  下划线+横线

7.列表

 ●  无序列表
 ●  有序列表
 ●  任务列表

8.分割线 9.链接

 ●  普通链接
 ●  自动链接
 ●  锚点提示

10.图片

 ●  行内式
 ●  参考式

11.转义 12.高亮

 ●  代码高亮
 ●  背景高亮

13.注解

 ●  介绍
 ●  完整格式
 ●  空标题
 ●  无标题
 ●  无类型
 ●  折叠
 ●  11种颜色样式
 ●  嵌套

14.脚注 15.元信息 16.数学公式

 ●  介绍
 ●  导入js
 ●  用法

17.emoji

 ●  介绍
 ●  工作原理
 ●  最佳实践

18.特殊符号 19.嵌套

 ●  介绍
 ●  注解-注解
 ●  列表-列表
 ●  引用-引用
 ●  注解-代码块
 ●  列表-代码块
 ●  引用-代码块
 ●  黄色区块-代码
 ●  绿色区块-代码
 ●  红色区块-代码
 ●  绿接红区块-代码
 ●  注解-列表-引用
 ●  列表-列表-引用

 ●  引用-引用-代码

其他功能

mkdocs-material本身还支持如下功能:

 ●  添加js,可用于站点统计(如百度统计,谷歌统计)
 ●  页面以及跳转文字的配色

 ●  中文搜索

最佳实践

如果希望自己所写的markdown可以兼容各个markdown编辑器,那么只需了解markdown的传统语法即可

如果想让自己所写的markdown发布到web服务器,例如GitHub Pages、自己搭建的HTTP Server,那么可以考虑使用本文所介绍的语法,以实现丰富多样的渲染效果。

笔者建议:尽量使用传统语法,只在必要时候才使用本文介绍的语法。因为排版简洁、条理清晰才能带来最舒服的阅读感受。


原文发布时间为:2018-11-7
本文作者:小慢哥
本文来自云栖社区合作伙伴“老叶茶馆”,了解相关信息可以关注“老叶茶馆”。

版权声明:本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《阿里云开发者社区用户服务协议》和《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。

相关文章
使用NAT网关轻松为单台云服务器设置多个公网IP
在应用中,有时会遇到用户询问如何使单台云服务器具备多个公网IP的问题。 具体如何操作呢,有了NAT网关这个也不是难题。
26751 0
阿里云服务器怎么设置密码?怎么停机?怎么重启服务器?
如果在创建实例时没有设置密码,或者密码丢失,您可以在控制台上重新设置实例的登录密码。本文仅描述如何在 ECS 管理控制台上修改实例登录密码。
9757 0
使用SSH远程登录阿里云ECS服务器
远程连接服务器以及配置环境
2474 0
阿里云服务器端口号设置
阿里云服务器初级使用者可能面临的问题之一. 使用tomcat或者其他服务器软件设置端口号后,比如 一些不是默认的, mysql的 3306, mssql的1433,有时候打不开网页, 原因是没有在ecs安全组去设置这个端口号. 解决: 点击ecs下网络和安全下的安全组 在弹出的安全组中,如果没有就新建安全组,然后点击配置规则 最后如上图点击添加...或快速创建.   have fun!  将编程看作是一门艺术,而不单单是个技术。
10869 0
windows server 2008阿里云ECS服务器安全设置
最近我们Sinesafe安全公司在为客户使用阿里云ecs服务器做安全的过程中,发现服务器基础安全性都没有做。为了为站长们提供更加有效的安全基础解决方案,我们Sinesafe将对阿里云服务器win2008 系统进行基础安全部署实战过程! 比较重要的几部分 1.
9098 0
如何设置阿里云服务器安全组?阿里云安全组规则详细解说
阿里云安全组设置详细图文教程(收藏起来) 阿里云服务器安全组设置规则分享,阿里云服务器安全组如何放行端口设置教程。阿里云会要求客户设置安全组,如果不设置,阿里云会指定默认的安全组。那么,这个安全组是什么呢?顾名思义,就是为了服务器安全设置的。安全组其实就是一个虚拟的防火墙,可以让用户从端口、IP的维度来筛选对应服务器的访问者,从而形成一个云上的安全域。
7417 0
阿里云服务器ECS登录用户名是什么?系统不同默认账号也不同
阿里云服务器Windows系统默认用户名administrator,Linux镜像服务器用户名root
4269 0
阿里云服务器如何登录?阿里云服务器的三种登录方法
购买阿里云ECS云服务器后如何登录?场景不同,云吞铺子总结大概有三种登录方式: 登录到ECS云服务器控制台 在ECS云服务器控制台用户可以更改密码、更换系统盘、创建快照、配置安全组等操作如何登录ECS云服务器控制台? 1、先登录到阿里云ECS服务器控制台 2、点击顶部的“控制台” 3、通过左侧栏,切换到“云服务器ECS”即可,如下图所示 通过ECS控制台的远程连接来登录到云服务器 阿里云ECS云服务器自带远程连接功能,使用该功能可以登录到云服务器,简单且方便,如下图:点击“远程连接”,第一次连接会自动生成6位数字密码,输入密码即可登录到云服务器上。
22171 0
阿里云ECS云服务器初始化设置教程方法
阿里云ECS云服务器初始化是指将云服务器系统恢复到最初状态的过程,阿里云的服务器初始化是通过更换系统盘来实现的,是免费的,阿里云百科网分享服务器初始化教程: 服务器初始化教程方法 本文的服务器初始化是指将ECS云服务器系统恢复到最初状态,服务器中的数据也会被清空,所以初始化之前一定要先备份好。
7148 0
+关注
技术小能手
云栖运营小编~
7208
文章
9
问答
文章排行榜
最热
最新
相关电子书
更多
《2021云上架构与运维峰会演讲合集》
立即下载
《零基础CSS入门教程》
立即下载
《零基础HTML入门教程》
立即下载